Skip to main content

Installation

KTestify ships as a Docker image. There is nothing to compile or install, pull the image and point it at your features.

docker pull ghcr.io/ktestify/ktestify-cucumber:latest

The image supports linux/amd64 and linux/arm64.

What you need​

  • A dedicated Kafka cluster for testing, not shared, not production. Why this matters →
  • A Git repository that holds your .feature files and asset payloads, this is your test project (see layout below). Your CI pipeline checks it out and mounts it into the container.
  • Optionally, a Confluent Schema Registry if you use Avro topics.

Project layout​

Your features and assets live in a dedicated Git repository, your test project. Keep it separate from your application code so it can evolve independently and be checked out by any CI agent.

The recommended structure inside that repository:

my-ktestify-tests/                  ← your Git repository root
└── workspace/
    └── features/
        └── order-processing/           ← one folder per feature set
            ├── order-processing.feature
            └── assets/                 ← payloads + expected files live right next to the feature
                ├── order.json
                └── order-enriched.json

Co-locating assets with their feature makes each test self-contained, everything a scenario needs is in one place.

Your CI pipeline checks out this repository and mounts workspace/ into the container at /workspace.

Configuration file​

Create an application.conf (HOCON) that points to your dedicated test environment:

application.conf
ktestify {
  kafka {
    bootstrap-servers = "kafka:9092"
    topic-namespace   = "myapp"
  }
  schema-registry {
    url = "http://schema-registry:8081"
  }
  framework {
    timeouts {
      default-read-timeout = 30s
    }
  }
}

All values can be overridden by environment variables, see Configuration →.

Running the container​

Minimal run, pass Kafka coordinates as env vars:

docker run --rm \
  -v "$(pwd)/workspace/features:/workspace/features" \
  -v "$(pwd)/workspace/reports:/workspace/reports" \
  -e KTESTIFY_BOOTSTRAP_SERVERS=kafka:9092 \
  -e KTESTIFY_TOPIC_NAMESPACE=myapp \
  ghcr.io/ktestify/ktestify-cucumber:latest \
  /workspace/features

The container exits with code 0 (all scenarios passed) or non-zero (failures), suitable for use directly as a CI step.

CI examples​

The preferred way to run KTestify is on a scheduled daily pipeline so regressions are caught before they reach production. See CI environment → for the full architecture.

GitLab CI runners can execute Docker commands via the Docker executor or Docker-in-Docker. The repository is automatically checked out into $CI_PROJECT_DIR.

.gitlab-ci.yml
regression-tests:
  stage: test
  image: docker:27
  services:
    - docker:27-dind
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'   # nightly schedule
    - if: '$CI_PIPELINE_SOURCE == "push"'        # also on every push
  script:
    - docker run --rm
        -v "$CI_PROJECT_DIR/workspace/features:/workspace/features"
        -v "$CI_PROJECT_DIR/workspace/reports:/workspace/reports"
        -e KTESTIFY_BOOTSTRAP_SERVERS="$TEST_KAFKA_BROKERS"
        -e KTESTIFY_TOPIC_NAMESPACE="$KTESTIFY_TOPIC_NAMESPACE"
        -e KTESTIFY_SCHEMA_REGISTRY_URL="$TEST_SCHEMA_REGISTRY_URL"
        ghcr.io/ktestify/ktestify-cucumber:latest
        /workspace/features
  artifacts:
    when: always
    paths:
      - workspace/reports/

Set TEST_KAFKA_BROKERS, TEST_SCHEMA_REGISTRY_URL, and KTESTIFY_TOPIC_NAMESPACE as CI/CD variables in your project settings.

Next steps​