Testing

Kafka has three levels of automated tests, plus JMH benchmarks and Trogdor for fault injection. This page tells you which to use, where the test code lives, and how to run it.

Tiers

Tier	Where	Runner	What it covers
Unit	<module>/src/test/java, <module>/src/test/scala	JUnit 5 + Gradle unitTest task	Deterministic in-process tests. Default for every PR.
Integration	<module>/src/test/java, clients-integration-tests/, streams/integration-tests/, connect/runtime/.../IntegrationTest.java	JUnit 5 + Gradle integrationTest task	Spins up real brokers in-process via kafka.testkit.*. Slower; gated on @Tag("integration").
System	tests/	ducktape (Python) + Trogdor / Vagrant / Docker	Multi-process scenarios across multiple VMs/containers; covers upgrades, network faults, security configs.
Microbenchmark	jmh-benchmarks/	JMH	Allocation- and latency-sensitive code paths.

Running unit tests

./gradlew test                          # everything
./gradlew unitTest                      # only unit tier
./gradlew clients:test                  # one module
./gradlew clients:test --tests RequestResponseTest
./gradlew core:test --tests kafka.api.ProducerFailureHandlingTest.testCannotSendToInternalTopic

A test that has been flagged as flaky is excluded by default and only runs with -Pkafka.test.run.flaky=true.

Running integration tests

./gradlew integrationTest               # all integration tests
./gradlew streams:integration-tests:test --tests org.apache.kafka.streams.integration.RestoreIntegrationTest
./gradlew clients:clients-integration-tests:test

Integration tests spin up brokers using kafka.testkit.KafkaClusterTestKit (core/src/test/java/kafka/testkit/) under core or via the EmbeddedKafkaCluster helper for Streams/Connect. They run inside the same JVM as the test, so they are far cheaper than a real cluster.

For Streams there is a dedicated module streams:integration-tests which is the canonical place for end-to-end Streams scenarios. Use the streams/test-utils/ TopologyTestDriver for deterministic, single-thread tests of a topology — it is preferred over a full integration test wherever possible.

Running a single test repeatedly

Useful when chasing a flaky test:

N=500; I=0; while [ $I -lt $N ] && \
  ./gradlew clients:test --tests RequestResponseTest --rerun --fail-fast; \
  do (( I=$I+1 )); echo "Completed run: $I"; sleep 1; done

Test conventions

• JUnit 5 across the board including the Scala core module.
• Tags — @Tag("integration") on integration tests; @Flaky("KAFKA-XXXXX") on tests that need quarantining.
• Test base classes — kafka.server.QuorumTestHarness for tests that need a KRaft cluster, kafka.api.IntegrationTestHarness for client-facing integration tests.
• Mock time — org.apache.kafka.common.utils.MockTime is widely used; never use real wall-clock sleeps in unit tests.
• Thread safety — test methods run in parallel within a class only if @Execution(CONCURRENT) is set; default is sequential.
• Mockito is the preferred mocking framework; PowerMock is no longer used.

System tests (ducktape)

System tests live under tests/ and use the ducktape Python framework on top of Vagrant or Docker to drive multi-host scenarios. They are not run on every PR — committers run them when validating risky changes.

cd tests
./docker/ducker-ak up                  # spin up the Docker cluster
./docker/ducker-ak test ./kafkatest/tests/sanity_test.py
./docker/ducker-ak down

tests/README.md has the full instructions, including tests/kafkatest/services/ (the per-service drivers) and tests/kafkatest/tests/ (the test scenarios). Major upgrade paths get their own streams/upgrade-system-tests-* Gradle modules so that older Streams binaries can be loaded by the test harness.

Trogdor

trogdor/ is Kafka's own distributed test harness. It can run agents on multiple hosts, inject faults (network partitions, slow disks), and run long workloads. It is what powers the longer-running ducktape scenarios. See trogdor/README.md.

Coverage

./gradlew reportCoverage -PenableTestCoverage=true -Dorg.gradle.parallel=false
./gradlew clients:reportCoverage -PenableTestCoverage=true -Dorg.gradle.parallel=false

Reports land at:

• core/build/reports/scoverageTest/index.html (Scala — Scoverage)
• <module>/build/reports/jacoco/test/html/index.html (Java — JaCoCo)

Coverage is opt-in because the bytecode instrumentation slows tests down by 15-20%.

JMH benchmarks

./gradlew jmh-benchmarks:shadowJar
java -jar jmh-benchmarks/build/libs/kafka-jmh-benchmarks-*-all.jar \
    -f 1 -wi 5 -i 10 ConsumerPerf

Benchmark sources are under jmh-benchmarks/src/main/java/org/apache/kafka/jmh/. See jmh-benchmarks/README.md for the full options.

Test harness helpers worth knowing

• org.apache.kafka.test.TestUtils — common assertions, retries, and helpers (in clients/src/test/java).
• org.apache.kafka.common.utils.MockTime, MockClock — controllable virtual clocks.
• kafka.server.QuorumTestHarness (Scala) — base class that boots a KRaft test cluster.
• kafka.testkit.KafkaClusterTestKit (Java) — preferred way to spin up a multi-broker cluster from a JUnit test.
• streams/test-utils — TopologyTestDriver and helpers for deterministic Streams tests.