Debug Server

Karate has first-class debug support based on the Debug Adapter Protocol (DAP) standard. The Karate Visual Studio Code Extension has support for debugging Karate tests.

The Karate Extension takes care of starting a debug session automatically and passing the details of feature files and break-points to the debug server.

The information below is for those who may want to start a debug-server manually and then you can point Visual Studio Code to it by using the following property in your launch configuration - once you have debug support for Karate *.feature files installed.

"debugServer": 4711

Karate CLI

Karate has a Command Line Interface (CLI) by which you can perform some actions without needing to write Java code, and all you need is a *.feature file and other optional Karate artifacts. The entry point is the same for the Java library as well as the Standalone JAR.

The command to start a debug server is -d or --debug and a port number is optional. Besides printing the chosen port to the console, Karate will save a file called karate-debug-port.txt after the server is ready to receive connections - and this will be in the default build directory (typically ./target). This file is designed for IDE-s that run in a different process to be able to start and synchronize debug sessions cleanly.

If you are on Windows and run into issues, see the Windows section of this page.

Standalone JAR

So for the standalone JAR - this will start the debug server on any free port.

java -jar karate.jar -d

Or to force a port:

java -jar karate.jar -d 4711

Classpath

For the standalone-jar, you may need finer control over the classpath, refer to the documentation for more. For example the below adds the "current directory" (.) to the root of the classpath on linux / mac.

java -cp karate.jar:. com.intuit.karate.Main -d

If you are on windows - use ; instead of : in the above classpath. Also see Windows.

Maven

When using Karate as a Java library (typically via Maven or Gradle), you can directly use the main class com.intuit.karate.Main via Maven like this:

mvn test-compile exec:java -Dexec.mainClass=com.intuit.karate.Main -Dexec.args=-d -Dexec.classpathScope=test

Gradle

If using Gradle, you can define a task to do this:

task karateDebug(type: JavaExec) {
    classpath = sourceSets.test.runtimeClasspath
    main = 'com.intuit.karate.Main'
}

And with that, on the command-line you can do this:

gradle karate --args="-d" 

Karate Options

For a full list, refer to the documentation or use the -h or --help option.

• -t tags
• -T threads
• -n Scenario name
• feature-file or path (directory) as the last parameter
• you can append a line-number (e.g: :30) to the feature-file above if you want to only execute that Scenario (or Scenario Outline row in an Examples table.

What this means is you can debug parallel-execution if you want - which may be useful to troubleshoot problems in large test-suites. VS Code plugin users can create an additional launch configuration and instead of using the feature key, add a new one called karateOptions - where you can add the details of the tags, threads and feature / paths to execute as the feature property.

        {
            "type": "karate",
            "name": "myname",
            "request": "launch",
            "feature": "${file}",
            "karateOptions": "-t ~@ignore -T 5"
        }

If you run into problems with VS Code starting the debug server, you can fall back to the last resort - of starting the debug server manually. The nice thing about VS Code is that it supports an extra "debugServer": 4711 property in the above launch-config snippet. And if present, VS Code will completely bypass the plugin when you hit the debug "play" button and will connect to the Karate server directly.