Skip to main content

FAQ

Frequently Asked Questions

Get quick answers to common questions about Karate installation, configuration, testing strategies, and troubleshooting.

Getting Started​

What is Karate?​

Karate is an open-source tool that combines API test automation, mocks, performance testing, and UI automation into a single unified framework. Tests are written in plain text using Gherkin syntax, making them readable by technical and non-technical team members.

Do I need programming knowledge to use Karate?​

No. Karate tests use plain text with simple, readable syntax. Programming knowledge helps with advanced features like custom JavaScript functions and Java interop, but is not required for basic API testing.

Feature: Basic API test

Scenario: Get user information
Given url 'https://api.example.com'
And path 'users', 123
When method GET
Then status 200
And match response.name == 'John Doe'

How does Karate compare to other testing tools?​

Karate offers a unified framework for API, UI, performance testing, and mocks. Unlike Cucumber, it requires no step definitions or glue code. Compared to Rest Assured, Karate provides simpler syntax with built-in assertions and debugging.

When to use Karate:

  • Testing APIs and UIs together
  • Teams with mixed technical skills
  • Need built-in mocking capabilities
  • Want unified test reporting

Consider alternatives:

  • Pure frontend testing: Use Cypress or Playwright
  • Java-heavy teams comfortable with code: Use Rest Assured
  • High-volume load testing: Use JMeter or k6
  • Mobile app testing: Use Appium directly

Installation & Setup​

What Java version do I need?​

Java 17 or higher is required as of Karate 1.4.0. Java 21 is recommended for best performance and modern JVM features.

# Check Java version
java -version
# Should show: java version "17.0.1" or higher

Version requirements:

  • Karate 0.9.x - 1.3.x: Java 8+
  • Karate 1.4.x+: Java 17+

Can I use Karate with Node.js projects?​

Yes. Install Karate CLI via npm and integrate with your existing npm scripts and CI/CD pipelines.

# Global installation
npm install -g @karatelabs/karate-cli

# Run tests
karate test.feature
karate --threads 4 src/test/features

# Local installation
npm install --save-dev @karatelabs/karate-cli
package.json
{
  "scripts": {
    "test:api": "karate src/test/features",
    "test:api:parallel": "karate --threads 4 src/test/features"
  }
}

Project structure example:

my-node-project/
├── src/
│   └── app.js
├── test/
│   ├── unit/           # Jest/Mocha tests
│   └── api/            # Karate tests
│       ├── karate-config.js
│       └── features/
│           └── user-api.feature
└── karate-reports/

How do I fix Maven archetype issues behind a corporate proxy?​

If Maven archetype commands fail behind a corporate proxy, temporarily disable your Maven settings.xml file or use the karate-core dependency with the all classifier.

pom.xml
<dependency>
  <groupId>io.karatelabs</groupId>
  <artifactId>karate-core</artifactId>
  <version>${karate.version}</version>
  <classifier>all</classifier>
  <scope>test</scope>
</dependency>

Add this to your pom.xml to keep .feature files with test classes:

pom.xml
<build>
  <testResources>
    <testResource>
      <directory>src/test/java</directory>
      <excludes>
        <exclude>**/*.java</exclude>
      </excludes>
    </testResource>
  </testResources>
</build>

Gradle configuration:

build.gradle
sourceSets {
  test {
    resources {
      srcDir file('src/test/java')
      exclude '**/*.java'
    }
  }
}

Benefits:

  • Keep .feature files with test classes
  • Easier artifact management in one location
  • No switching between src/test/java and src/test/resources

For more details, visit the Quick Start guide.

How do I set up VS Code for Karate?​

Install the official Karate extension from the VS Code marketplace. Open a .feature file to activate syntax highlighting, autocomplete, and debugging features.

Extension features:

  • Syntax highlighting for Gherkin
  • Run scenarios directly from editor
  • Step-through debugging
  • IntelliSense for Karate keywords

API Testing​

How do I handle authentication in tests?​

Use the Background section to authenticate once and reuse the token across scenarios.

Feature: Protected API endpoints

Background:
Given url 'https://api.example.com'
And path 'auth/login'
And request { username: 'user', password: 'pass' }
When method POST
Then status 200
* def authToken = response.token

Scenario: Access protected resource
Given path 'protected-resource'
And header Authorization = 'Bearer ' + authToken
When method GET
Then status 200

How do I test GraphQL APIs?​

Use the text keyword to define GraphQL queries and send them as POST requests to the GraphQL endpoint.

Scenario: Query user data
Given url 'https://api.example.com/graphql'
And text query =
"""
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}
"""
And request { query: '#(query)', variables: { id: '123' } }
When method POST
Then status 200
And match response.data.user.name == '#string'

Can I test file uploads?​

Yes. Karate supports multipart file uploads with the multipart keyword.

Scenario: Upload PDF file
Given url 'https://api.example.com/upload'
And multipart file myFile = { read: 'test-file.pdf', filename: 'test.pdf', contentType: 'application/pdf' }
And multipart field message = 'Test upload'
When method POST
Then status 200

Data Management​

How do I read test data from files?​

Use the read function to load data from JSON, CSV, XML, or YAML files.

Scenario: Use external test data
* def userData = read('test-data/users.json')
* def user = userData[0]

# Read CSV data
* def csvData = read('test-data/users.csv')

Given url 'https://api.example.com'
And path 'users'
And request user
When method POST
Then status 201

Can I use databases in tests?​

Yes. Access databases through Java interop or by calling HTTP endpoints that query your database.

Scenario: Query database via HTTP
Given url 'http://localhost:8080/db'
And path 'query'
And request { sql: 'SELECT * FROM users WHERE id = ?', params: [123] }
When method POST
Then status 200
* def dbResult = response.data[0]

How does Karate handle different data formats?​

Karate natively supports JSON, XML, CSV, YAML, and binary data formats.

Scenario: Work with multiple formats
# JSON (native support)
* def user = { name: 'John', age: 30 }
* def users = read('users.json')

# XML (native support)
* def xmlData = <user><name>John</name></user>
* match xmlData/user/name == 'John'

# CSV (automatic conversion)
* def csvData = read('users.csv')
* def firstUser = csvData[0]

# YAML (automatic conversion)
* def config = read('config.yaml')

# Binary data
* def imageBytes = karate.readAsBytes('test-image.png')

Test Execution​

How do I run tests in parallel?​

Use the JUnit 5 runner with the parallel method to specify thread count.

@Test
void testParallel() {
    Results results = Runner.path("classpath:features")
        .tags("@regression")
        .parallel(5); // 5 parallel threads

    assertEquals(0, results.getFailCount());
}

How do I skip tests conditionally?​

Use the karate.abort function to skip tests based on environment or configuration.

Background:
* def skipTest = karate.env == 'production'
* karate.abort(skipTest)

Scenario: Development only test
Given path 'debug/endpoint'
When method GET
Then status 200

Can I generate test reports?​

Yes. Karate automatically generates detailed HTML reports in the target/karate-reports/ directory with timeline views, detailed logs, and pass/fail statistics.

Report formats:

  • HTML (interactive reports)
  • JSON (machine-readable)
  • JUnit XML (CI/CD integration)

Performance & Mocking​

Can I do performance testing?​

Yes. Karate integrates with Gatling for performance testing through the performance hook API.

@Test
void performanceTest() {
    PerfHook hook = new PerfHook("classpath:perf/load-test.js");
    Results results = Runner.path("classpath:features/api")
        .hook(hook)
        .parallel(10);
}

How do I create mock services?​

Use karate.start to start a mock server from a feature file.

Feature: Mock server

Background:
* def port = karate.start('user-mock.feature').port
* url 'http://localhost:' + port

Scenario: Mock returns user data
Given path 'users', 1
When method GET
Then status 200
And match response == { id: 1, name: 'John Doe' }

Troubleshooting​

My tests are failing intermittently​

Common causes include timing issues, test data dependencies, and environment differences.

Solutions:

  1. Timing issues: Add waits or increase timeouts
Background:
* configure readTimeout = 30000
* retry until responseStatus == 200
  1. Test data dependencies: Use unique identifiers
Background:
* def uniqueId = java.util.UUID.randomUUID()
  1. Environment differences: Use proper configuration
// karate-config.js
if (env === 'ci') {
  config.readTimeout = 60000;
}

How do I debug failing tests?​

Enable detailed logging and response printing with configuration options.

Background:
* configure logPrettyResponse = true
* configure printEnabled = true

Scenario: Debug failing test
Given url 'https://api.example.com'
And path 'users', 1
When method GET
* print 'Response:', response
Then status 200

Tests work locally but fail in CI​

Ensure CI uses the correct environment configuration and has adequate timeouts for slower environments.

# GitHub Actions example
- name: Run Tests
  run: mvn test -Dkarate.env=ci

Common solutions:

  • Verify environment configuration matches CI
  • Increase timeouts for slower CI environments
  • Ensure all required services are running
  • Use test-specific data or mocks

Integration & Advanced​

Can I integrate with Cucumber reports?​

Yes. Karate generates Cucumber-compatible JSON reports.

Results results = Runner.path("classpath:features")
    .outputCucumberJson(true)
    .parallel(5);

How do I call Java code from Karate?​

Use the Java.type function to access Java classes and call methods.

Scenario: Call Java utility
* def JavaUtils = Java.type('com.mycompany.JavaUtils')
* def result = JavaUtils.processData('input-data')
* match result == 'expected-output'

# Call static methods
* def uuid = java.util.UUID.randomUUID() + ''

Can I use custom assertions?​

Yes. Create JavaScript functions in karate-config.js and use them in tests.

// karate-config.js
function customAssert(actual, expected) {
  return actual.toLowerCase() === expected.toLowerCase();
}

return { customAssert: customAssert };
Scenario: Use custom assertion
* assert customAssert(response.name, 'JOHN DOE')

Community & Support​

Where can I get support?​

Free community support:

Enterprise support:

  • Professional services and architecture design
  • Priority support with SLA guarantees
  • Corporate training programs
  • Custom feature development

Is Karate suitable for enterprise use?​

Yes. Karate is widely adopted by Fortune 500 companies and large enterprises for production environments with high transaction volumes.

Enterprise benefits:

  • Robust parallel execution and distributed testing
  • Comprehensive reporting for audit and compliance
  • Built-in support for OAuth, SAML, and mutual TLS
  • Reduces tool sprawl with unified API, UI, performance, and mock testing

How can I contribute to Karate?​

Contribute through code improvements, documentation, community support, or testing beta releases.

Ways to contribute:

  • Submit pull requests with tests and clear descriptions
  • Fix documentation typos or add examples
  • Answer questions on Discord and Stack Overflow
  • Test beta releases and provide feedback

Best Practices​

What are common anti-patterns to avoid?​

Avoid heavy setup in Background, testing implementation details, hardcoding environment values, and creating overly complex tests.

Anti-pattern: Heavy setup in Background

# DON'T
Background:
* call read('create-100-users.feature')
* call read('setup-complex-data.feature')

Better approach: Use callonce

# DO
Background:
* def testData = callonce read('lightweight-setup.feature')

Anti-pattern: Hardcoded environment values

# DON'T
Given url 'https://prod-api.company.com'

Better approach: Use configuration

# DO
Given url baseUrl

When should I NOT use Karate?​

Karate is not ideal for pure unit testing, frontend-only testing, non-HTTP protocols, or mobile app testing.

Better alternatives:

  • Unit tests: JUnit 5, TestNG, Jest
  • UI-only tests: Cypress, Playwright
  • Load testing: JMeter, k6, Artillery
  • Mobile testing: Appium, Detox, Espresso
Key Points
  • Keep tests focused with single responsibility
  • Use callonce for expensive setup operations
  • Test behavior, not implementation details
  • Configure environment-specific values in karate-config.js

Next Steps​

On This Page