DOCSEARCHbyAlgolia
Submit Docs

KTestify Documentation

website·Indexed 30 days ago

https://docs.ktestify.xyz

A modular, open-source framework for testing Kafka applications using Gherkin feature files and BDD. It provides a Docker-based environment to produce and assert Kafka records using raw, Avro, and XML formats, featuring a plugin system for custom transports and notifications to Slack, Microsoft Teams, and HTTP webhooks.

Tokens
33.5K
Snippets
165
Records
240
Agent score
49%

What's inside KTestify

  1. Overview of KTestify for Kafka integration testing

    KTestify is a modular, open-source framework designed for integration-testing Kafka and Kafka Streams data pipelines. It uses a transport-agnostic engine divided into three layers: Transport, Orchestration, and Assertion. The framework allows developers to write tests using plain-English Gherkin scenarios via the ktestify-cucumber adapter, enabling the production of messages, consumption from output topics, and record assertions without writing Kafka client code.
    Feature: Order stream validation

  Background:
    Given input topic
      | topicName  | topicAlias |
      | orders-in  | raw        |
    Given output topic
      | topicName  | topicAlias |
      | orders-out | enriched   |
    Given assets directory
      | absolutePath                  |
      | src/test/resources/assets     |

  Scenario: Raw order should be enriched with status
    When record from file is sent
      | topicName  | file           | recordKey |
      | orders-in  | order-123.json | order-123 |
    Then expected record from file
      | topicAlias | file                       |
      | enriched   | order-enriched-output.json |

  2. Overview of KTestify Kafka testing framework

    KTestify is a modular framework designed for integration testing of Apache Kafka data pipelines. It allows teams to produce messages, consume from output topics, and assert record content without writing Kafka client code. The framework is built around a transport-agnostic engine that supports pluggable record matchers (JSON, XML, XPath, Avro), dynamic variable injection, and a HOCON-based configuration system.

  3. Overview of ktestify-plugin-notifications

    The ktestify-plugin-notifications is a first-party KTestify plugin that sends a rich, color-coded test suite summary after each run. It supports Microsoft Teams, Slack, and generic HTTP webhooks. Key features include per-tag group breakdowns (using Cucumber tags), automatic attachment of CI/Git context (branch, commit, build number), and configurable success-rate thresholds to drive alerting styles.

  4. Overview of ktestify-plugin-http

    The ktestify-plugin-http is a first-party KTestify plugin that adds a synchronous HTTP transport to test scenarios. Unlike Kafka or Azure Blob transports that block until a record appears, the HTTP transport sends requests and returns responses immediately. It is ideal for systems exposing synchronous REST APIs, requiring request/response assertions, or needing to poll endpoints until a specific status is returned. It can be combined with Kafka produce and consume steps in a single flow.

  5. Overview of ktestify-plugin-azureblob

    The ktestify-plugin-azureblob is a first-party KTestify plugin that integrates Azure Blob Storage into Kafka testing workflows. It is used to upload blobs as test fixtures before producing Kafka messages and to assert that pipelines correctly write output blobs. It is particularly useful for systems that read input files from or write result files to Azure Blob Storage as part of their Kafka processing logic.

  6. Overview of KTestify Plugin Capabilities

    KTestify's plugin system allows developers to extend the framework without modifying core code. Plugins are automatically discovered at startup and can be used to:

    • Add new transports (e.g., IBM MQ, Amazon SQS, MQTT, NATS).
    • Integrate external services (e.g., Azure Blob Storage, AWS S3, SFTP servers, databases).
    • Add custom assertions and domain-specific validation logic.
    • Contribute reusable Cucumber step definitions for Gherkin scenarios.

  7. Understand KTestify batch consumer mode

    KTestify's batch consumer mode allows a single assertion step to collect a configurable number of records before running assertions. This is primarily used for pipelines with fan-out (one input producing multiple outputs) or for verifying ordering guarantees. When expectedRecordsCount is greater than 1, the KafkaRecordFetcher polls continuously until the specified number of records is collected or the timeout expires. If the timeout is reached before the count is met, the test fails with a message indicating how many records were actually collected versus how many were expected.

  8. Implement the KTestify plugin three-layer architecture

    KTestify plugins follow a three-layer separation of concerns to ensure modularity between data retrieval, process orchestration, and validation:

    1. Transport: Implemented via RecordFetcher<T> (e.g., ExampleRecordFetcher implementing RecordFetcher<String>). This layer is responsible for fetching records from the external system.
    2. Orchestration: Handled by a consumer class (e.g., ExampleConsumer) that wires the flow from fetching to matching and finally to the result.
    3. Assertion: Utilizes standard RecordMatcher implementations provided by ktestify-core to validate the fetched data.

  9. Create a custom transport plugin for KTestify

    KTestify allows adding new transports as self-contained Maven modules (plugins). This architecture abstracts the transport layer using RecordFetcher<V> and ConsumedRecord<V>, meaning any new transport only needs to produce ConsumedRecord objects to be compatible with existing matchers (e.g., FileRecordMatcher, XmlRecordMatcher). Plugins are loaded at runtime from the /workspace/plugins directory, eliminating the need to rebuild ktestify-core or ktestify-cucumber.

  10. Understand the ktestify plugin three-layer architecture

    ktestify plugins follow a three-layer separation to decouple data retrieval from validation:

    1. Transport: Implemented via RecordFetcher<String>. This layer is responsible for fetching data and returning a List<ConsumedRecord<String>>. This is the only type that crosses layer boundaries.
    2. Orchestration: Implemented via the Consumer class. It wires the fetcher to the matcher and result. It uses RecordMatcherFactory.forRaw() to select the appropriate matcher.
    3. Assertion: Uses standard RecordMatcher implementations from ktestify-core. Plugin developers do not need to write custom matcher code.

  11. KTestify Architecture Overview

    KTestify uses a strict three-layer separation of concerns to decouple message transport from data assertion. The only data type that crosses layer boundaries is ConsumedRecord<V>. This architecture allows developers to swap transport layers (e.g., moving from Kafka to IBM MQ) without modifying the assertion logic, and reuse the same matchers across different transport protocols.

  12. Structure KTestify tests using Gherkin feature files

    KTestify tests are written as Gherkin feature files. A feature file consists of two primary building blocks: the Background and Scenario sections. The Background is used for global setup (namespaces, topics, assets) and runs once before every scenario in the file. Scenario blocks define individual test flows consisting of actions (When) and assertions (Then).