RUNNING TESTS

JUnit

Run Karate tests seamlessly with JUnit's fluent API, generate detailed HTML reports, and validate feature files without execution.

Karate v2

Karate v2 uses karate-junit6 instead of karate-junit5. The API is the same — only the dependency name changes. See Migration from v1 for details.

Benefits of JUnit Integration

• Multiple test methods: Run different feature sets in a single class
• Fluent API: Configure tests with method chaining
• Zero configuration: HTML reports generated automatically
• IDE support: Right-click to run individual tests
• Streaming test generation (v2): Dynamic test discovery via @TestFactory

Basic JUnit Setup

Karate supports JUnit with a clean fluent API. You need only one import and can have multiple test methods in a single class.

Gherkin

Feature: Retrieve existing posts

  Background:
    * url 'https://jsonplaceholder.typicode.com'

  Scenario: Get all posts successfully
    Given path 'posts'
    When method get
    Then status 200
    And match response == '#[10]'
    And match each response.userId == '#number'

Java

class UserTest {

    @Karate.Test
    Karate testUsers() {
        return Karate.run("users").relativeTo(getClass());
    }

    @Karate.Test
    Karate testSmokeTests() {
        return Karate.run("classpath:tests")
                .tags("@smoke")
                .relativeTo(getClass());
    }

    @Karate.Test
    Karate testEnvironmentSpecific() {
        return Karate.run("login")
                .tags("@regression")
                .karateEnv("staging")
                .systemProperty("api.key", "test-key")
                .relativeTo(getClass());
    }

}

Key Points

• Java classes don't need to be public
• Test methods don't need to be public
• Karate traverses subdirectories automatically
• Use relativeTo(getClass()) for package-relative feature files

Maven Configuration

Ensure you have the correct dependencies and plugins in your pom.xml:

Karate v2 (recommended)

<dependencies>
    <dependency>
        <groupId>io.karatelabs</groupId>
        <artifactId>karate-junit6</artifactId>
        <version>2.0.0</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>5.10.1</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>3.5.2</version>
        </plugin>
    </plugins>
</build>

Karate v1 dependency (legacy)

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

JUnit HTML Reports

Karate automatically generates comprehensive HTML reports after each feature execution. These reports include complete request/response details, perfect for debugging.

Report Location and Access

After running tests, HTML reports are saved to target/karate-reports/:

target/karate-reports/
├── com.mycompany.UserTest.html          # Individual test reports
├── com.mycompany.UserTest.testUsers.html
└── karate-summary.html                   # Overall summary

The console output shows direct file URLs:

html report: (paste into browser to view)
-----------------------------------------
file:///projects/myproject/target/karate-reports/com.mycompany.UserTest.html

Report Contents

HTML reports include:

• Request details: Headers, body, method, URL
• Response data: Status, headers, full response body
• Assertions: Match results with expected vs actual values
• Debug output: All print statements and variable values
• Timing: Execution time for each step
• Screenshots: For UI automation tests

Custom Report Directory

You can customize the report directory using builder methods:

@Karate.Test
Karate testWithCustomReports() {
  return Karate.run("users")
          .outputDir("custom-reports")
          .relativeTo(getClass());
}

Debugging with Reports

HTML reports are invaluable for troubleshooting failed tests. They show the exact request/response flow, making it easy to identify issues.

Dry Run Validation

Dry run validates feature file syntax and structure without executing HTTP requests or assertions. This is perfect for:

• Syntax validation: Check Gherkin syntax and Karate expressions
• Refactoring: Validate changes without hitting external systems
• CI pipeline: Quick validation before full test execution
• Large test suites: Fast feedback on structural issues

Java

    @Karate.Test
    Karate validateAllFeatures() {
        // Dry run all features in the current package
        return Karate.run("classpath:tests")
                .dryRun(true)
                .relativeTo(getClass());
    }

    @Karate.Test
    Karate validateSpecificTag() {
        // Dry run only smoke tests
        return Karate.run("classpath:tests")
                .tags("@smoke")
                .dryRun(true)
                .relativeTo(getClass());
    }

}

Performance Benefits

Dry run is significantly faster than full execution, making it ideal for continuous validation during development.

Command Line Integration

JUnit 5 tests integrate seamlessly with command-line execution. For comprehensive command-line options, see Command Line Execution.

Command Line

# Run specific JUnit test class
mvn test -Dtest=UserTest

# Run specific test method
mvn test -Dtest=UserTest#testSmokeTests

IDE Integration

JUnit 5 provides excellent IDE support for running Karate tests:

• Right-click execution: Run individual test methods or entire classes
• Debug support: Set breakpoints in Java runner code
• Test results: Visual pass/fail indicators in IDE
• Report access: Quick links to HTML reports

Development Workflow

Use JUnit 5 runners during development for quick iteration, then switch to the parallel runner for CI/CD pipelines.

Advanced Configuration

JUnit 5 runners support additional builder methods from the Runner.Builder class:

@Karate.Test
Karate advancedConfiguration() {
  return Karate.run("advanced-tests")
          .tags("@integration", "@regression")  // AND operation
          .karateEnv("production")
          .systemProperty("timeout", "30000")
          .outputDir("integration-reports")
          .relativeTo(getClass());
}

Available configuration methods:

• tags() - Filter tests by tags
• karateEnv() - Set environment
• systemProperty() - Pass system properties
• outputDir() - Custom report directory
• dryRun() - Validation mode
• relativeTo() - Base path for feature files

Next Steps

• Learn parallel execution: Parallel Execution
• Explore command line options: Command Line
• Set up test reports: Test Reports