Karate Robot Windows Install Guide

To make this a comprehensive guide, this will take you through the process of installing Karate Robot on a freshly provisioned Windows box from AWS. You may be able to skip some of the steps (e.g. installing Java) depending on what already exists in your environment.

Acquire Windows Instance

The AMI chosen is "Microsoft Windows Server 2022".

Install Visual Studio Code and official Karate extension

Download it from https://code.visualstudio.com/.

Follow the instructions here to install the official Karate extension for VS Code and make sure you can run a simple API test.

The good thing about the official Karate extension for VS Code is that it includes the Karate runtime. You will need to manually add karate-robot.jar to the runtime as we will see in the section below.

Download Karate Robot

Look for the latest release on GitHub and scroll down to find the "Assets". Look for the file with the name: karate-robot-<version>.jar. Download it to the root of your project folder, and rename the file to karate-robot.jar.

Your project should look something like this:

Edit Karate Extension Classpath

Click on the extensions icon on the left, and then click on the "gear" icon for the Karate extension, and choose "Extension Settings" as shown below:

Find the setting for "Classpath Prefix" and change it to .,./karate-robot.jar

karate src/demo/robot/calc.feature

Or if it is the "old" version of the Windows Calculator, use this:

karate src/demo/robot/calc-old.feature

Here's what the "old" calculator test in action looks like:

So at this point you can create and run Karate tests for Windows applications ! But to really get productive, we recommend that you use the Visual Studio Code IDE support.

Install the Karate Runner

After installing, open Visual Studio Code and go to "Extensions" (the bottom vertical tab on the left). You can type "karate" in the search-box to find the Karate Runner extension.

Change Command Line Settings

Click on "Install". After that you should see the "gear" icon, click on it to edit some extra settings needed for Karate Robot. Choose the "Extension Settings" option from the menu.

Scroll down to find this setting called "Command Line Args"

Change it to add karate-robot.jar. The whole line would be:

java -cp karate.jar;karate-robot.jar;. com.intuit.karate.Main

Now the IDE is ready to open Karate projects and files and run and even debug tests. Go to File --> Open Folder and browse to the Karate / project folder.

Here we have also opened the calc.feature (or calc-old.feature).

Note how you can click on Karate Run at the top of the file to run a test. You can try it now, but you will get this error.

Change Default Shell

This is because Visual Studio Code uses "powershell" by default instead of "cmd.exe" which is what we need. There is an easy way to set this. Click on the "Task" drop-down you see in the bottom "Terminal" tab and you should see an option to "Select Default Shell" like you see above.

If you really need to use PowerShell, you can try by modifying the Command Line Settings to have the -cp (classpath) argument within single-quotes: e.g. java -cp 'karate.jar:karate-robot.jar;.' com.intuit.karate.Main

And now you can choose cmd.exe.

You can change this any time by going to File --> Preferences --> Settings and searching for "terminal windows". For more information on changing the default terminal on Windows, refer to this thread on Stack Overflow.

Now try clicking again on "Karate Run" in the Feature: and it should work. Note that you can see reports in the target/surefire-reports folder - which even includes screenshots if requested as part of the test-script.

Debug Mode

This is a must for writing and maintaining tests and one of the best things about the IDE support. Try clicking on "Karate Debug". This one-time prompt to select a "Debug Configuration" will come up. You can choose Karate (debug).

You don't have to change the default "Launch Configuration" that will be created. You can close this launch.json tab now and get back to the feature file.

Now try "Karate Debug" again, but this time before you do anything, set a break-point, see the red-dot on line 12 below.

And as we expect, Karate will stop at the break-point like seen below.

Now you can do some interesting things. Find the "Debug Console" tab in the bottom pane (click on the "..." icon if needed) and type highlightAll('//button')

Hit ENTER and you should see this. You can try other commands such as highlight('6'). Any Karate step should work. You can see how this is extremely useful for building or troubleshooting tests.

Note that you can even step back and edit & hot-reload steps. Also see this video.

Pre-Step Hook

This is needed when using Karate-Robot for desktop automation and when you use the Karate-Runner in debug mode. Most of the time, Karate-Robot expects a particular application-window to be "in focus" and visible, and on top of all other windows. But when you use the debug actions such as [step-forward], [continue] etc. after hitting a break-point - the Visual Studio Code window would be the one having "focus" instead.

So there needs to be a way to tell Karate to "flip" focus back to the AUT (Application Under Test). This can be easily done - as Karate has a way to execute any arbitrary script before resuming execution when in debug mode. And typically, the most effective way is to trigger an ALT+TAB input sequence.

The Visual Studio Code Launch Configuration (.vscode/launch.json) for the Karate Debug Server takes an optional debugPreStep parameter. For example, this is the configuration that can switch focus to the previously most recently focused window:

{
  "type": "karate",
  "name": "Karate (debug): Standalone",
  "request": "launch",
  "feature": "${command:karateRunner.getDebugFile}",
  "karateOptions": "",
  "karateCli": "${config:karateRunner.karateJar.commandLineArgs} -d",
  "debugPreStep": "input(Key.ALT + Key.TAB)"
}

Note that the step-prefix (e.g. *, Given, When then etc. can be omitted). Only a single step can be configured, but the good thing is that you can call any valid feature if you have a need to run a sequence of pre-step operations:

    "debugPreStep": "call read('some.feature')"

Windows Tips

The "Inspect.exe" tool can be used to figure out how to select UI elements. One way to acquire this is to install the Windows SDK (selecting "Windows SDK for Desktop C++ x86" should be sufficient).

It seems that there may be better options such as Accessibility Insights for Windows so you could try that - or any other similar tool instead.

Tesseract Data Files

Besides image-driven navigation, Karate Robot has experimental support for OCR (Optical Character Recognition) that can be useful in case there is no other way you could find to "select" an element or control, possibly because it is a UI framework that Windows has limited support for.

For the OCR support to work, you need to separately download some data files. You can read the documentation for details, but for now we will just use the defaults for "English" and just add a single data-file in a pre-defined (default) directory.

• Download eng.traineddata from the tessdata_fast data-set.

• Place this in a tessdata folder in the root of your Karate project folder. This is how it should look.

Now you can enter this command in the Debug Console (when a debug / breakpoint session is in progress) and hit ENTER.

robot.active.debugExtract()

You should see Karate attempt to OCR-scan the "active" window for text:

For convenience an additional Window will appear with details so that you can study it at leisure.

Please Contribute !

There may be some more work needed to make the OCR capabilities more accurate and robust, please do contribute if you can !

Karate Robot Documentation

Note that when using an RC release, the latest documentation would be in the develop branch:

https://github.com/intuit/karate/tree/develop/karate-robot