Karate Debug

A powerful VS Code extension for debugging Karate API tests. Set breakpoints directly in your .feature files, step through scenarios, inspect variables, and run tests with a single click.

Features

Breakpoint Debugging

Set breakpoints in your .feature files and step through your Karate tests line by line. Inspect variables, view request/response data, and understand exactly what's happening at each step.

▶ One-Click Test Execution

CodeLens buttons appear above every Feature and Scenario, letting you debug with a single click—no configuration required.

Feature Explorer

Browse all your Karate features and scenarios in a dedicated sidebar. Navigate your test suite at a glance and run any test directly from the tree view.

Environment Switching

Quickly switch between environments (dev, qa, stage, or your custom environments) from the status bar. Your selection persists across sessions.

Syntax Highlighting

Full syntax highlighting for the Karate DSL, including Gherkin keywords, JSON/XML payloads, JavaScript expressions, and embedded variables.

Java Debugging Support

For advanced scenarios, attach a Java debugger simultaneously to debug both your Karate features and underlying Java code.

Requirements

• Java 17+ (Java 21 recommended for best compatibility)
• Maven project with Karate dependencies
• Tests located in src/test/java or src/test/resources

Quick Start

1. Install the extension from the VS Code Marketplace
2. Open a Maven project containing Karate tests
3. Open any .feature file
4. Click ▶ Debug Feature or ▶ Debug Scenario above your test

That's it! The debugger will start, and you can set breakpoints, step through code, and inspect variables.

Configuration

Configure the extension via VS Code Settings (Cmd+, or Ctrl+,):

Example settings.json

{
  "karateDebug.environments": ["local", "dev", "qa", "stage", "prod"],
  "karateDebug.defaultEnvironment": "dev"
}

Launch Configuration

For advanced scenarios, create a .vscode/launch.json configuration. When you create a new launch configuration and select "Karate Debug", the extension provides ready-to-use templates.

Simultaneous Karate and Java Debugging

Debug both your .feature files AND underlying Java code in the same session. This is useful when your Karate tests call custom Java helpers or when you need to debug into Karate's internals.

How it works:

1. Start the "1. Karate: Start with Java Debug" configuration
2. While it's waiting, start "2. Java: Attach to Karate"
3. Both debuggers are now active - set breakpoints in .feature files AND .java files

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "karate",
      "request": "launch",
      "name": "1. Karate: Start with Java Debug",
      "feature": "${file}",
      "javaDebugPort": 5006
    },
    {
      "type": "java",
      "request": "attach",
      "name": "2. Java: Attach to Karate",
      "hostName": "localhost",
      "port": 5006,
      "timeout": 30000
    },
    {
      "type": "karate",
      "request": "launch",
      "name": "Karate: Debug Feature Only",
      "feature": "${file}"
    }
  ]
}

Launch Configuration Options

Building from Source

# Clone the repository
git clone https://github.com/j8d/karate-debug.git
cd karate-debug

# Build the Java debug server
cd debug-server && mvn clean package -q && cd ..

# Install dependencies and compile
npm install
npm run compile

# Package the extension
npm run package

# Install locally
code --install-extension karate-debug-*.vsix

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an Issue.

Support the Project

If this extension helps you, consider supporting my work:

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Karate - The powerful API testing framework
• VS Code Debug Adapter Protocol - Debug adapter implementation