karate

name	karate
description	Expert in Karate API testing framework - BDD-style API testing with Given/When/Then syntax, assertions, and test automation. Use this when writing or debugging Karate API tests.
license	MIT

Karate API Testing Framework Expert

Expert in Karate DSL (1.4.1+) for BDD-style API testing with built-in assertions and JUnit5 integration.

When to Use This Skill

• Writing new Karate test scenarios
• Debugging failing Karate tests
• Understanding Karate DSL syntax
• Configuring Karate with Maven/Gradle
• API test automation best practices

Karate DSL Syntax

Basic Structure

Feature: Feature description

  Background:
    * url 'http://localhost:5000'
    * header Accept = 'application/json'

  Scenario: Scenario description
    Given path '/api/endpoint'
    And request { key: 'value' }
    When method POST
    Then status 200
    And match response.field == 'expected'

Common Assertions

# Status codes
Then status 200
Then status 404

# Exact match
And match response.name == 'John'

# Contains
And match response.message contains 'success'

# Type validation
And match response.id == '#number'
And match response.name == '#string'
And match response.active == '#boolean'
And match response.field == '#null'

# Array validation
And match response.items == '#[5]'  # exactly 5 items
And match response.items == '#[]'   # non-empty array

# Regex
And match response.email == '#regex .+@.+\\..+'

# Schema validation
And match response == { id: '#number', name: '#string' }

Request Methods

# GET
Given path '/users/1'
When method GET

# POST with JSON
Given path '/users'
And request { name: 'John', email: '[e-mail]' }
When method POST

# PUT/PATCH
Given path '/users/1'
And request { name: 'Jane' }
When method PUT

# DELETE
Given path '/users/1'
When method DELETE

# Query parameters
Given path '/users'
And param page = 1
And param size = 10
When method GET

Variables

# Define variables
* def userId = 123
* def user = { name: 'John', age: 30 }

# Use variables
Given path '/users', userId
And request user

# Extract from response
* def token = response.auth.token

# Use in next request
Given path '/protected'
And header Authorization = 'Bearer ' + token
When method GET

Data-Driven Tests

Scenario Outline: Test multiple values
  Given path '/search'
  And param q = '<query>'
  When method GET
  Then status 200

  Examples:
    | query |
    | eva   |
    | cam   |
    | phil  |

Project Configuration

Maven pom.xml

<dependencies>
    <dependency>
        <groupId>com.intuit.karate</groupId>
        <artifactId>karate-junit5</artifactId>
        <version>1.4.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>

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

JUnit5 Runner

package com.example;

import com.intuit.karate.junit5.Karate;

class ApiTest {
    @Karate.Test
    Karate testApi() {
        return Karate.run("api-tests").relativeTo(getClass());
    }
}

Configuration File (karate-config.js)

function fn() {
  var env = karate.env || 'dev';
  var config = {
    baseUrl: 'http://localhost:5000'
  };
  
  if (env == 'prod') {
    config.baseUrl = 'https://api.production.com';
  }
  
  return config;
}

Running Tests

# Run all tests
mvn test

# Run specific feature
mvn test -Dkarate.options="classpath:path/to/test.feature"

# Run with tags
mvn test -Dkarate.options="--tags @smoke"

# Parallel execution
mvn test -Dkarate.options="--threads 5"

Common Patterns

Background Setup

Background:
  * url baseUrl
  * def testUser = { name: 'Test', email: '[e-mail]' }
  
  # Create test data
  Given path '/users'
  And request testUser
  When method POST
  Then status 201
  * def userId = response.id

Retry Logic

Given path '/status'
And retry until response.ready == true
When method GET

Conditional Logic

* def result = response.status == 'active' ? 'enabled' : 'disabled'

Debugging

Print Statements

* print 'User ID:', userId
* print response

Reports

• HTML reports: target/karate-reports/karate-summary.html
• Detailed logs for each scenario
• Screenshots for UI tests

Common Issues

Connection refused:

• Ensure API is running
• Check port availability
• Verify base URL in karate-config.js

Assertion failures:

• Use * print response to see actual data
• Check data types (#string vs 'string')
• Verify JSON structure

JSON parsing errors:

• Use single quotes for keys in Karate
• Check JSON syntax in requests

Best Practices

1. Use Background for common setup (DRY)
2. Tag scenarios (@smoke, @regression)
3. Externalize test data with read()
4. One assertion per line for clarity
5. Meaningful scenario names describing behavior
6. Independent scenarios (no execution order dependency)
7. Clean test data in teardown if needed

Project Context

In this project, Karate tests are located in:

• tests/karate-tests/src/test/java/thoughtfulai/
• Test the Flask API at http://localhost:5000
• 13 scenarios covering all endpoints
• Run with: ./tests/run-karate-tests.sh