KTestify

The foundation library. A fluent Java API for testing Kafka producers, consumers, and Kafka Streams topologies, with no Cucumber dependency.

What it gives you:

• Fluent producer & consumer DSL via ConsumerContext / ProducerContext
• Kafka Streams topology test harness
• Rich message matchers: JSON file, XML, XPath, positional fields, key-only, batch
• Avro support through Schema Registry, including GenericRecord matching and excluded fields
• Dynamic variable system in payloads: {{DATE:...}}, {{ENV:...}}, {{RANDOM:...}}
• HOCON configuration (reference.conf + environment variable overrides)
• Separate transport contracts for streaming (RecordFetcher<V>) and synchronous request/response (RequestResponseClient<Req, V>) integrations

ConsumerContext<String, String> ctx = ConsumerContext.<String, String>builder()
        .topic(outputTopic)
        .matchMethod(ConfigConstants.methodMatchFile)
        .matchFilePaths(List.of("expected/order.json"))
        .readTimeout(Duration.ofSeconds(30))
        .build();

Boolean passed = new RawKafkaConsumer(ctx).call();

assertTrue(passed);

A standalone BDD test runner. Uses Cucumber 7 and Gherkin to express Kafka scenarios in plain language, backed by the ktestify-core API. Run it with Docker or as a fat JAR; it is not an embeddable Cucumber library.

What it gives you:

• Ready-to-use Gherkin steps for record production and assertions
• Raw and Avro scenarios, with key matching and positive or negative presence checks
• Raw JSON, XML, and text alongside Avro scenarios in the same suite
• Batch consumer assertions (expectedRecordsCount)
• consumerReadTimeout and consumerDeltaTime per-scenario tuning
• Shell script execution steps
• Rich CI reports via cucumber-reportr

The runner connects to a Kafka test cluster that you provide. It does not start a broker for you.

Feature: Order enrichment

Background:
Given namespace
| namespace |
| ktestify  |
Given input topic
| topicName     | topicAlias |
| raw-roundtrip | orders-in  |
Given output topic
| topicName     | topicAlias |
| raw-roundtrip | orders-out |

Scenario: Order enrichment, JSON file match
When record from file is sent
| topicName     | file              | recordKey |
| raw-roundtrip | data/order.json   | order-123 |
Then expected record from file
| topicAlias | file                    | expectedRecordKey |
| orders-out | expected/order.json     | order-123         |

Cross-platform test suite notifications for ktestify-cucumber. Sends a rich summary card at the end of each test run, with per-tag group breakdowns, CI/Git context, and configurable success-rate thresholds.

What it gives you:

• Four built-in channels: Teams (Adaptive Card), Slack (Block Kit), generic HTTP webhook, and a zero-dependency log channel
• Tag-based scenario grouping, each group gets its own success rate and colour-coded style in the card
• Auto-detected CI/CD context (GitLab CI, GitHub Actions, CircleCI, Jenkins…) via cucumber-cienvironment
• Visual thresholds: good ≥ 75 %, warning ≥ 50 %, attention < 50 %
• Fully overridable templates, inline HOCON, classpath resource, filesystem path, or bundled defaults
• Extensible via SPI, custom channels registered in META-INF/services/ are discovered automatically
• Async and failure-safe, notifications run in a background thread pool and never block a test run

ktestify.plugins.notifications {
  enabled = true
  channels = [
    {
      type = "teams"
      enabled = true
      webhook-url = ${?KTESTIFY_TEAMS_WEBHOOK_URL}
      on-failure-only = false
    }
  ]
}

Azure Blob Storage transport support for ktestify-cucumber. Ready-to-use Gherkin steps for uploading and asserting blobs are discovered automatically.

What it gives you:

• Gherkin step definitions for blob upload, assertion, and negative presence checks
• Seamless integration alongside Kafka steps in the same scenario
• Three auth modes, connection string, SAS token, or managed identity endpoint
• Auto-create containers on first use (configurable)
• Local development support via Azurite emulator with UseDevelopmentStorage=true
• Zero-config discovery via SPI, the plugin registers itself through META-INF/services/

ktestify.plugins.azure-blob {
  connection-string = ${?AZURE_STORAGE_CONNECTION_STRING}
  request-timeout = 30s
  auto-create-containers = true
}

Synchronous HTTP request/response support for ktestify-cucumber. Its Gherkin steps send requests and assert response status, headers, and bodies. The plugin uses the JDK HTTP client and is discovered automatically through SPI.

Given HTTP endpoint
  | endpointAlias | baseUrl                   |
  | orders-api    | http://localhost:8080/api |
When HTTP request is sent
  | endpointAlias | method | path   | file       | responseAlias |
  | orders-api    | POST   | /orders | order.json | order-response |
Then expected HTTP response status
  | responseAlias  | statusCode |
  | order-response | 200        |