Getting started

Start by watching the 120-seconds KantuX video below. Then run some or all of the included demo macros. This will give you a good feeling of what KantuX can do. After that, you are ready to record your first macro.

KantuX is fun to use! But if you have no time to create automation scripts you can buy KantuX PRO. The license includes 3 hours of custom script creation services to get you started. So you just tell us what you want to automate, and KantuX tech support creates the macros and scripts for you.

KantuX Recording

To create your own image macros, click the "tape icon" and the image wizard appears. It helps you to take the screenshots for your macro.

  • Resize the screenshot area to fit your button or text box. In general, a smaller screenshot is better and faster.
  • Select the action to perform on the screenshot: Click or Click+Type (for sending text to input boxes)
  • . For web testing, there is also Find to assert a certain image is on the screen.
  • Click "Add" to record the screenshot and command
  • When you are done with recording, click stop.
  • Save the macro under a new name.
  • Select Play to run your macro.
Screenshot web automation with KantuX Tips:
  • The scroll command allows you to move up and down the screen.
  • You can use the "Comment" box to add a note for later
  • No worries: Wrongly recorded commands can be removed or changed in the editor after recording
Record screenshots step by step


Use the Editor to fine-tune

The KantuX Editor allows you to add and remove recorded commands, and also to easily rename and change images. For this, it has a built-in screenshot tool.


Waiting for page loads and images

By default, KantuX waits up to 10 seconds for an image to appear. It does not matter what delays the image appearance. Often, this will be a page load event, but it can be anything, for example some page internal processing that then auto-updates the page. If 10 seconds are too short, increase the value in the KantuX settings (applies to all macros) or use the SET FINDIMAGECOMMANDTIMEOUT to increase it inside the macro. The new value set by FINDIMAGECOMMANDTIMEOUT is valid for all visual commands (Click, Find and Extract) that follow after the new timeout value has been set.

How to wait longer for images to load...


Automating File Downloads

Just trigger the file download like you normally would do, this time using the image wizard. KantuX records it by adding a SET DownloadDirectory... value.


Automating File Uploads

Automating web browser file uploads is very easy with KantuX: Create a click command with the screenshot of the file upload "Browse" button and then select the file you want to upload from the native browser file upload dialog that appears. That is all. KantuX records path of the selected file and then fills it in during replay. KantuX works with all file upload methods that you can find on the web (We tested dozens of websites and it worked with all. If you come across any that does not work, contact us.)


Special feature: Folder upload: If you specify a folder name instead of a file name, KantuX will upload every file in the folder. To do so, set the loop counter (at the very bottom of the right sidebar) to a value > 1. With every macro loop, KantuX grabs a new file from the folder and fills its file name to the upload box. KantuX selects the files to upload alphabetically a-z.


Automating Select Boxes

Automating selected boxes can be sometimes a bit tricky. On the one hand there are modern-style select boxes (Example: Gmail sign-up dialog). These can be automated just like any other element on the page.

The tricky part are only the “classic” old-style select boxes. You can detect them as you will be unable to create a screenshot of them with the wizard. And sometimes they overlap the recording wizard once open. And in any case, they look old and very “Web 1.0”.


To automate these kind of select boxes you have to use keyboard events: To select an entry from select boxes, please enter {DOWN} to select entries. If you want to select the 3rd entry, then enter {DOWN}{DOWN}{DOWN}. Then send {ENTER}. So the complete sequence looks like


You can also tell KantuX to type the first character of an entry. Example: To select Germany in a typical country list, type " G" and then 3-times down:


Typing “G” will jump to “Gabon” and from there you are only 3 times {DOWN} away from Germany.

Web Scraping/ Data Extraction

The new KantuX Version has full support for data extraction via the API. For more details, please see the visual web scraping page.

Visual Web Scraping with OCR

Looping a macro

In web testing you often need to replay a macro more than once. KantuX has a built-in function for that: Enter the desired number of loops in the field and then press Play. Another method to loop a macro is to use the PLAY command provided by the API and call it for example within a FOR...NEXT loop of your favorite scripting language.

Drag & Drop

The Drag & Drop command can drag anything to anywhere. You mark the point the drag should start (e. g. an icon, an image, a scrollbar) and then the place the drag should end (drag stop). As with other commands, the anchor area is marked with a green frame and the drag start and stop areas are marked with a pink rectangle.

Drag and Drop automation and testing

Data-driven testing/automation with CSV files and databases

There are two ways to import CSV data into KantuX:

(A.) Built-in csvRead command

You add the SET csvRead YourCSVfile.csv to the macro and KantuX loads it for you. The data from the CSV file is now available in the internal variables {{$COL1}}, {{$COL2}} and so on. KantuX loads a new row of the CSV file with every macro loop – so it is important that you set the loop counter (bottom right corner) to a value > 1. Typically, of course, you will pick a loop counter value matches the number of rows in your CSV file. Related demo macro "Demo-csvRead". It shows how to use a CSV file to populate multiple form entries.

(B.) Use the Scripting API [PRO]

This approach gives you the most flexibility. You can use the API not to read data from CSV file, but from any datasource (SQL, Access, ODBC,….). To do so, use the API to send data to KantuX. A VBS example script that reads from a CSV file and sends the data to KantuX for form filling is in our KantuX API GitHub repository.

Note that while CSV files (CSV is a comma separated values file) are the most popular way to store and read data, the API allows you to connect KantuX with databases or any other datasource as well.

Execute JavaScript (Content Scripts)

Sometimes visual automation is not enough, and you need to query website elements directly. Or you need the power of Javascript to generate custom values like "Yesterday's date" or "Random number between 200 and 250". KantuX includes the Javascript command for such tasks. It allows you to do everything JavaScript can do, but inside the visual KantuX macros. As KantuX builds on Google Chromium, its Javascript command is compatible to Chrome content scripts. Run the "Demo-Javascript" macro that ships with KantuX to see some scripts in action.

Example 1: Simulate a BACK button click with window.history.go(-1);

Example 2:Set a select box to a certain value:
var e = document.getElementById('tesla'); e.value = "y";

Example 3: Get today's date:
var today = new Date(); var date = today.getFullYear()+'-'+(today.getMonth()+1)+'-'+today.getDate(); var time = today.getHours() + ":" + today.getMinutes() + ":" + today.getSeconds(); var dateTime = date+' '+time; return dateTime;.
The return value of the script is available with the {{$JSRESULT}} internal variable.

Run Javascript inside a KantuX macro:


Adobe Flash testing/automation

KantuX's visual approach is ideally suited for automating and testing Flash applets. To get started, you only need to install the latest Adobe Flash Player. This takes less than one minute, please follow the instructions here.


Command Line Options

You can run KantuX from the command line/batch file:

  • KantuX.exe macro.kmacro => opens KantuX and runs macro.kmacro. KantuX stays open after the macro is completed.
  • KantuX.exe macro.kmacro -ae => opens KantuX, runs macro.kmacro, and then closes KantuX (ae = and exit). This is the recommended syntax if you start KantuX from a task scheduler.
  • Kantueditor.exe macro.kmacro => opens macro.kmacro in the KantuX Editor

Schedule Tasks: If you need to run macros periodically you can use KantuX with the built-in Windows task scheduler. By using Task Scheduler, you can schedule tasks such as uploading a file or filling a form at a defined time. The Task Scheduler takes care of this. It runs in the background, checking if any scheduled task is due. You can schedule a task to run daily, weekly, monthly, or at certain events such as system startup. KantuX supports headless mode.


Use the KantuX Browser Scripting API [PRO]

For more complex automation, there is the KantuX Browser API. It can be used from any programming or scripting language. Some VBS and PowerShell sample scripts are included. As a start, run them to see what the API can do.

Browser API

Easy to use API, works in any programming or scripting language on Windows

With open you launch KantuX instances, and with play you run the image macro. All commands return detailed status and error information at runtime. Tasks you can use the API for include "if/then" decisions, reading form-filling data from a text file ("data-driven testing") or storing extracted information in a database.

For more details see the API command reference below.


Jenkins Integration

How to integrate KantuX visual testing with Jenkins:

Jenkins Service Windows

First - as with launching any UI-based Windows app from Jenkins - make sure that the Jenkins service runs under a normal user account and not the local system account, which is the default. Alternatively, launch the build process on a second machine via a Jenkins slave node.

Change user account of the Jenkins Windows Service

In this example we use Powershell and the Jenkins Powershell plugin to open the KantuX browser, run the test case (Play) and then close the browser again. The only special command for Jenkins is the last line, where we set the exit code to 1 (if error) or 0 if the test was successful. This is done to integrate with the Jenkins reporting where 1 means error. As you know, in the KantuX API it is just the opposite and a return value of 1 means success. Because the KantuX API is a standard windows COM object, you can use any other scripting language instead of Powershell. Some Jenkins/KantuX users also use a small C# app to control KantuX via the API, and then launch this app from Jenkins as batch file. The KantuX tech support can help in case of any problems.


KantuX - FAQs


Is using KantuX safe with confidential data? [YES]

KantuX is classical software and runs locally. So your confidential data is safe - it never leaves your PC in any other way than a regular browser does. For more details on this and on our very strict approach to privacy, please see our privacy policy page.

What does "Confidence level" mean?

This term has nothing to do with data privacy but is a term used for image matching. Another, maybe better name for it is ''similarity score'' (and we will change to that name with the next update). => What it means is the similarity between the input image (e. g. the button image) and the best found match on the website. A score of 1 means perfect match, and a score of, say 0.8, allows for some deviation between the images The image search algorithm scores every possible match with such a score. And if you set the similarity score threshold e. g. to 0.8, but the best possible match found is only 0.78, then KantuX will report this as "image not found" error. On the other hand, if the best possible match found is 0.83, then all is fine and KantuX will click the button and continue.

Why is this needed? Technically images are rarely rendered exactly the same between two machines. There are artifacts from the JPG compression, browser rendering, screen resolution or the image you are clicking changes a slightly different shade during mouse over. So the goal of the employed pattern matches algorithms that KantuX considers an image "the same" if a human would say it is "the same".

For example, an image that has a similarity score of 0.95 on your regular work PC might have the same score inside a VM on the same PC, but only a similarity score of 0.56 on a Surface Tablet with its High-PPI screen. In other words, a confidence 0.5 is usually a very good and stable default value.


How to create IF THEN ELSE statements with KantuX?

Community and PRO Edition: The Javascript command allows you, among many other things, to make if/then decisions within the command.
Example: var hour = new Date().getHours();if (hour >= 9 && hour < 18) { text = "store open"} else { text = "store closed"}; return text;

PRO Edition: KantuX separates the linear website flow logic (the KantuX screenshot macro) and the programming/scripting logic via the Scripting API. So for tasks like conditional statements, the Scripting Interface is the best solution. The PLAY command always returns detailed status and error information, and use can use this to base your IF/THEN/ELSE decisions on:

IntegerReturnValue = objKantu.Play ("macro1")
if IntegerReturnValue = 1 then
'Do something
MsgBox "OK!"
'Do something else
IntegerReturnValue = objKantu.Play ("macro2")
end if

This example uses the VBS/Visual Basic syntax, but you can use any programming or scripting language with the Scripting API.


How do I add additional steps to an existing recording?

You can use the KantuX Editor to copy & paste lines between macros: So you would first record macro A, then record the additional steps as macro B, and then copy & paste some or all lines of it into macro A.


Can KantuX run in headless mode? [YES]

Unlike most other visual automation solutions, KantuX Web Automation runs fine in headless mode (no physical monitor connected). This feature comes out-of-the-box, it requires no special settings or setup. Just start KantuX via command line or API. This also means that KantuX automation runs just fine on disconnected RDP (remote desktop connection) sessions, behind a Windows lock screen, inside VMware/Vbox/HyperV virtual machine or when started by the Windows task scheduler.

Web testing specific FAQs are on the web testing FAQ page.


KantuX Command Reference

This chapter lists all KantuX macro commands. The compressed KantuX macro ( = .kmacro) files are standard zip files. If you rename *.kmacro to *.zip you can open and edit them in Windows Explorer or any other file manager. Some file managers such as Total Commander are even smart enough to let you open the .kmacro files without renaming the extension first. A KantuX macro consists of a .json file with the macro commands and the corresponding images in .png or .jpg format (.png recommended).

Click (and Right-Click)

Find the target image and click in the center of it. As any command that takes an image as input, the CLICK commands waits until "timeout" for the image to appear. The default is 12s. You can change the value either globally in the settings dialog or inside the KantuX macro with SET FindImageCommandTimeout (new time). Also, by default all image commands search only on the visible part of the screen for a better performance. You can change this by adding SET SearchImageInWholePage "true" to the macro. The Right-Click command works the same, but simulates a mouse-right-click. Typically websites like Google Docs use right-clicks to open context-sensitive menus.

If you want to find an image and click not in center, but somewhere else, then use relative click method.

Click & Type

This combines a Click and a Type command into one command. Typically this is used with input boxes. It finds the target image, clicka in the center of it and sends text and/or any of the special key codes listed below.

  • {DOWN} and {UP} - Useful to move through values in select boxes or to scroll inside frames/iframes
  • {ENTER}
  • {TAB} - Use it to jump between input fields
  • {LEFT} and {RIGHT}
  • {BACK} - Delete pre-filled characters
  • Need other values? Please ask tech support.

Drag & Drop

Drag and drop is explained here.


Extracts data from the website. The data is returned via the API interface. For more details see the Extract documentation.

Using Extract for Relative Clicks

Extract can also be used for relative mouseclicks if you use CLICK as value in the Extract method field. In this case, nothing is extracted, but instead a click is simulated in the middle of the pink box. This is great for triggering clicks relative to an image, for example you find something in column 1 and then click on a button in column3, or you find the image of a label and then click in the input box to the right/left/top/below of it.

Also supported are simulating Shift-Click (holding Shift key while clicking) with CLICKSHIFT and Ctrl-Click CLICKCTRL.

Relative Clicking with the EXTRACT command...
Screenshot: Using EXTRACT... CLICK for relative clicks.

Macro code for relative clicks
Macro code for relative clicks. Use TYPE to send text to the last click position.


Use Find to verify that the target image is loaded. Often this kind of check is also called assert. Just like Click command, find waits until the image is loaded (success) or until the timeout is reached (fail).


Execute Javascript on the loaded web page. Great for accessing the DOM and making basic IF/THEN decisions.


This command limits the search area for all image-commands. A green area in the image is the anchor, and the pink rectangle visually indicates the new search area. The new area is valid until a new LimitSearchArea defines a new area or the macro ends. To reset the search area to the whole browser screen, you use LimitSearchArea set to "Viewport".

Navigate (URL)

Loads a website. KantuX does not "wait" for a website to be loaded. The "waiting" is implicitly done by the image recognition of the FIND or CLICK commands.


This commands takes a screenshot of the website and saves it to file. The options are "full" (whole page) or "partial" (visible part).


This commands scroll the page up or down. Why is this useful? By default, the image recognition of KantuX operates on the visible part of the screen, so by scrolling up or down you can reach other parts of the website.

  • Top - scroll to top (~ "Home" key for humans)
  • UpPage - scroll one page up (~ "Arrow Up" key)
  • UpHalf - scroll half page up
  • DownHalf - scroll half page down
  • DownPage - scroll one page down (~ "Arrow Down" key)
  • Bottom - scroll to the very end (~ "End" key)

Recording SCROLL.
Screenshot: Recording the SCROLL command with the recording wizard.

You can change image search area with the SearchImageInWholePage parameter. It is set to false by default (ie. only the visible part of the page is used).If you want to set it so the image detection use the whole page during

Scrolling inside a frame/iframe/popup

The regular SCROLL command always works (only) on the scroll bars of the main website (example: Scrolling on Google News). It does not scroll pages that are inside a frame or iframe. For example, the a9t9 Twitter applet on the Online OCR Status Page is a typical example where a list (here the list of tweets) is embedded into an iframe.

Scrolling pages inside a frame or iframe
Screenshot: Scrolling pages inside a frame or iframe

Solution: Use the ClickType command to send a sequence of {DOWN} keycodes to the page inside the frame. To do so, make the ClickType command click on any place inside the iframe so the frame receives the key sequence. If you want to scroll to the bottom of the list, then you might have to send 20 more {DOWN} to reach the bottom. But this is no problem... adding a few extra {DOWN} does not hurt, this way you can make sure you always reach the bottom. The screenshot above clarifies this further.

SET (Parameter)...

This commands sets internal values for the KantuX replay engine. Values set inside a macro override global values. For example, if the global replay speed is set to "Slow", a SET ReplaySpeedMode = FAST will overwrite the value for the macro itself, but not change the global setting. Do not confuse this command with the API command setVariable.

  • csvReadSpecify the CSV file to read data from. The number of columns is auto-detected. The data is available in the {{$COL1}},{{$COL2}}...{{$COL9}} variables.
  • DeleteAllCookies - Removes all cookies. Note that some cookie types are only really gone after a browser restart. (You can automate a browser restart via the KantuX API.)
    If you want to remove absolutely every data that the KantuX Chromium Browser stores, manually delete its cache. You find it at C:\Users\***your user***\AppData\Local\Temp\KantuX\cache. Delete the \cache folder and restart KantuX.
  • DownloadDirectory (string) : The path where the downloaded files should be stored during a record/replay. It overrides the global value set in the app settings.
  • ReplaySpeedMode - Fast. Medium or Slow. This overrides the global settings for the specific macro
  • ErrorIgnore (true/false). If set to true, KantuX continues the macro execution after an error (e. g. after an image is not found). This is very useful to click on buttons that are only sometimes on the screen.
  • ExtractAdd Adds a custom value to the list of extracted data. You can add for example the JS return value {{$JSRESULT}} or any other internal value to your extracted data. This way you can return such data to the calling script. It will be returned via the GetExtractImageData command just as any other extracted data.
  • FindImageCommandTimeout (int) : Wait for image to appear on website" Timeout, in ms, to use for every IMAGE commands during a replay. It overrides the global value set in the app settings.
  • Proxy: Sets a new proxy for the browser in the format IP:PORT|username(optional)|password(optional). This proxy overrides any global settings and is only valid for this macro run. It overrides the global value set in the app settings.
  • SearchImageInWholePage (boolean): It is set to false by default (ie. only the visible part of the page is used). If set to "true" the whole website is used for the image detection. This applies to all image related commands (CLICK, CLICKTYPE, EXTRACT, FIND). [PRO Edition feature]
  • SidebarVisible (boolean): It is set to true by default. Set it to false if you work on a smaller screen and want to use everything for the actual browser window.
  • Useragent (string): As the same suggests, this sets a new user agent string. This overrides any global settings and is only valid for this macro run. It overrides the global value set in the app settings.

Use SET to tell KantuX to search the whole page.

The screenshot shows the SET command dropdown box inside the KantuX Editor.


Waits x milliseconds. It is not required to use Wait with the image commands.

List of internal variables

Internal variables expose some KantuX data for use inside your macro and Javascript. Most internal variables are "read-only", unless explicitly mentioned. Do not confuse these internal variables with the API command setVariable, that allows you to create your own variables to send data to KantuX macros.

  • {{$BOX1}}... {{$BOX9}} - content of the last pink frame(s) of an EXTRACT command. Use it, for example, to fill extracted data back into a form.
  • {{$COL1}}... {{$COL9}} - content of CSV file (read line by line during loops)
  • {{$FILE.UPLOAD}} - name of file the select for upload. Useful if you use the folder upload feature and want to fill in the current file name somewhere.
  • {{$FOLDER.DOWNLOAD}} - location of the KantuX download folder, typically C:\Users\(user name)\Documents\KantuX\download.
  • {{$JSRESULT}} - return value of the last Javascript command
  • {{$MACRO.NAME}} - name of the running macro. Useful, for example, as part of file names
  • {{$LOOP}} - number of the current loop. Starts with 1 (not 0)
  • {{$PASTE}} - content of the clipboard

KantuX API Reference [PRO]

This chapter lists all commands that are available from the KantuX scriting interface (API).

Example code/scripts for using the API from C#, Java, Python, Powershell, VB6, VBS and VB.NET are available in the KantuX KantuX API GitHub Repository.

objKantu = CreateObject ("KantuX")

Example objKantu = CreateObject ("KantuX").

Connects to the KantuX Browser API. The API is technically designed as a COM object, so it works with any programming or scripting language on Windows. They all support talking to COM objects. Now you can access all commands via the “objKantu” object just created: intReturncode = objKantu.CommandName


Syntax: iret =

  • open(true) - Opens the KantuX browser.
  • open(false) - connects to an existing, already open instance.

For experts: You can modify the default timeout that the API waits for KantuX to launch by using objKantu.Open(true/false, new timeout value in seconds). The default timeout value is 60 seconds, which is normally more than enough to launch the KantuX Browser. However, if you are launching many instances of KantuX at once, and the CPU usage is close to 100%, then it can take for longer. The option to increase the .Open timeout was added for this case.

PROXY and user agent change: You can add a proxy parameter with objKantu.Open(true, 60, "-proxy -useragent helloWorld "). This feature is only available in the regular PRO version (not PRO trial).

objKantu.echo (“Text”)

Displays a text string on the KantuX GUI. Try it :)

objKantu.setVariable (“VariableName", Value)

Set values in your programming language and KantuX uses them in the kmacro macros, for example {FirstName}. This command is for the custom variables (= variables that you create). It should not be confused with the SET command inside the KantuX macro, which is designed to set the built-in variables like ReplaySpeedMode, DeleteAllCookies, DownloadDirectory, FindImageCommandTimeout or SearchImageInWholePage.

Variables are only parsed in the “Value” field of a command. So you can not use them (yet= to replace/change for example parts of the URL in the “OPEN” command or change the images or other values. Meanwhile, contact tech support for some workarounds.


This is the most important command - it plays the .kmacro macro. If the macro completed OK, the command returns 1. If something went wrong a negative value is returned. The GetLastError function provides detailed error information on what went wrong.

Timeout value: Play and all other commands have a default timeout. This timeout avoids that the calling scripts waits "forever" in case the Chromium browser engine crashes or freezes. If this happens, the Play command returns after the timeout is expired. If the KantuX browser (and/or the Google Chromium engine inside it) is frozen, it is closed by the API. So the API object operates independently of the KantuX Browser. It runs in a separate process.

Important: The timeout might also trigger an error if the macro simply runs too long (longer than the timeout value). The solution for this case is to overwrite the default timeout value (60 seconds) by adding your own time like this:

objKantu.Play ("macro-name", 300)

In this example the KantuX API will wait 5 minutes (300 sec) for the PLAY command to complete before triggering a timeout error.

String = objKantu.getLastError()

Returns the error text of the last error that occurred. Typically this command is used after the Play command if the return value is < 0 (which indicates an error)

String = objKantu.GetExtractImageData()

Returns the extracted information as string


Closes the KantuX Browser.

More Commands

These commands are for expert use and typically used if you need a deeper integration between your application and KantuX.

i = objKantu.searchImage(image, 0.38)

Runs an image search on the currently open browser window.


And if your question is not answered here,...

...please contact us. We love to hear from you!

Subscribe to the a9t9 automation software newsletter . We'll send you updates on new releases that we're working on.