Enable and Verify Parallel Test Execution in Karate 1.5+

Desired Outcome

Cut the total runtime of a Karate test suite by leveraging multiple CPU cores while keeping results deterministic and reproducible.

Prerequisites

• Karate 1.5.0 or newer in your project dependencies.
• JUnit 5 or TestNG test runner configured (Karate’s own runners are thin wrappers).
• All feature files must be independent – no shared mutable state (static fields, global files, external services that are not isolated).
• Java 8+ (Karate’s parallel implementation relies on the standard Java thread pool).
• Build tool: Maven or Gradle. The examples below use Maven; the same flags apply to Gradle.

Focused Procedure

1. Determine the number of worker threads.

   Use the number of logical CPU cores minus one as a safe default. For a 4‑core machine, set karate.parallel=3. If memory is tight, choose a lower value.

2. Configure the flag in the build tool.

   For Maven, add the system property to the mvn test command or to the pom.xml:

   mvn test -Dkarate.parallel=3

   Or in pom.xml:

   <build>
     <plugins>
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-surefire-plugin</artifactId>
         <version>3.0.0-M5</version>
         <configuration>
           <systemPropertyVariables>
             <karate.parallel>3</karate.parallel>
           </systemPropertyVariables>
         </configuration>
       </plugin>
     </plugins>
   </build>

   For Gradle, set the property in the test task:

   tasks.test {
     systemProperty 'karate.parallel', '3'
   }

3. Run the suite.

   Execute the build command. Karate will spawn the specified number of worker threads and distribute feature files among them.

4. Verify parallel execution.

   Check the console output for lines prefixed with Parallel and thread identifiers. Example snippet:

   Parallel: Running feature /path/to/feature1.feature on Thread-0
   Parallel: Running feature /path/to/feature2.feature on Thread-1
   ...

   Also compare total elapsed time between -Dkarate.parallel=3 and -Dkarate.parallel=1. The former should finish noticeably faster if tests are independent.

5. Optional: Enable verbose thread logging.

   Use -Dkarate.log=TRACE to see thread‑local context details, useful for debugging race conditions.

Expected Checks

• Console shows Parallel prefixes with thread names.
• Test reports (JUnit XML, TestNG XML) contain the same number of test cases as before.
• No flaky failures appear that were absent in sequential runs.
• Memory usage stays within acceptable limits (monitor jcmd VM.native_memory summary if needed).

Recovery Options

• Revert to sequential execution. Set -Dkarate.parallel=1 or remove the property.
• Reduce thread count. If out‑of‑memory errors occur, try -Dkarate.parallel=2 or the default (CPU - 1).
• Isolate shared resources. Move any shared file writes or static state into a setup/teardown that runs per thread or use thread‑local containers.
• Use environment variables. For CI pipelines, export KARATE_PARALLEL and let the runner pick it up automatically.

Practical Checklist

Step	Action	Expected Result
1	Run with -Dkarate.parallel=4	Console shows four distinct Thread-* entries.
2	Compare timings	Parallel run < 50% of sequential if tests are independent.
3	Check for flaky failures	Same failure rate as sequential.
4	Monitor memory	Peak usage < 2× baseline of sequential run.

Limitations

• Only supported in Karate 1.5.0+. Earlier releases lack built‑in parallel support.
• Test cases that modify shared files or rely on static state will still fail nondeterministically.
• External services (e.g., databases) must provide isolation per thread or use transaction rollbacks.
• Large suites may hit the Java thread‑pool limit; adjust -Dkarate.max-threads if necessary.

Conclusion

Enabling Karate’s parallel mode is a one‑line change to your build configuration, but it requires disciplined test design. With proper isolation and a sensible thread count, you can halve or better the total execution time of large API test suites.