Skip to main content

Configuration

KTestify uses Typesafe Config (HOCON). Values are resolved in this priority order (highest first):

System properties     -Dktestify.kafka.bootstrap-servers=...
       ↓
Environment variables  KTESTIFY_BOOTSTRAP_SERVERS=...
       ↓
application.conf      your project's override file
       ↓
reference.conf        ktestify-core built-in defaults

Pointing to your config file​

Pass an application.conf to the container via --config:

docker run --rm \
  -v "$(pwd)/workspace/features:/workspace/features" \
  -v "$(pwd)/workspace/config:/workspace/config" \
  ghcr.io/ktestify/ktestify-cucumber:latest \
  --config /workspace/config/application.conf \
  /workspace/features

Or set it as an environment variable:

-e KTESTIFY_CONFIG_FILE=/workspace/config/application.conf

Minimal config​

The only two keys you must set for a basic raw-JSON test run:

application.conf
ktestify {
  kafka {
    bootstrap-servers = "kafka:9092"
    topic-namespace   = "myapp"
  }
}

For Avro tests, also add:

  schema-registry {
    url = "http://schema-registry:8081"
  }

Full reference​

Kafka​

HOCON keyEnvironment variableDefaultDescription
ktestify.kafka.bootstrap-serversKAFKA_BOOTSTRAP_SERVERSlocalhost:9092Comma-separated list of Kafka broker addresses
ktestify.kafka.topic-namespaceKTESTIFY_TOPIC_NAMESPACE""Prepended to every topic name as namespace.topicName. Leave blank for no prefix. Can be overridden per-scenario with Given namespace.
ktestify.kafka.security-protocolKAFKA_SECURITY_PROTOCOLPLAINTEXTConnection security: PLAINTEXT, SSL, SASL_PLAINTEXT, SASL_SSL

Consumer​

HOCON keyEnvironment variableDefaultDescription
ktestify.kafka.consumer.group-idKAFKA_CONSUMER_GROUP_IDktestify-consumer-groupKafka consumer group ID
ktestify.kafka.consumer.enable-auto-commit—falseAuto-commit offsets. Keep false — KTestify manages offsets manually.
ktestify.kafka.consumer.auto-offset-reset—earliestWhat to do when no offset exists: earliest or latest
ktestify.kafka.consumer.session-timeout—30sKafka consumer session timeout
ktestify.kafka.consumer.heartbeat-interval—10sHeartbeat interval (must be < session-timeout / 3)
ktestify.kafka.consumer.max-poll-records—500Max records returned per poll() call
ktestify.kafka.consumer.key-deserializer—StringDeserializerKey deserializer class (fully qualified)
ktestify.kafka.consumer.value-deserializer—StringDeserializerValue deserializer class. Avro consumers override this automatically.

Producer​

HOCON keyDefaultDescription
ktestify.kafka.producer.acksallAcknowledgement level: 0, 1, all
ktestify.kafka.producer.retries3Number of retries on transient send failure
ktestify.kafka.producer.batch-size16384Producer batch size in bytes
ktestify.kafka.producer.linger-ms1msHow long to wait for additional records before sending a batch
ktestify.kafka.producer.buffer-memory33554432Total bytes of memory the producer can use for buffering (32 MB)
ktestify.kafka.producer.key-serializerStringSerializerKey serializer class
ktestify.kafka.producer.value-serializerStringSerializerValue serializer class. Avro producers override this automatically.

Security (SSL / SASL)​

HOCON keyEnvironment variableDefaultDescription
ktestify.kafka.security.sasl-mechanismKAFKA_SASL_MECHANISM""SASL mechanism: PLAIN, SCRAM-SHA-256, SCRAM-SHA-512, OAUTHBEARER
ktestify.kafka.security.sasl-jaas-configKAFKA_SASL_JAAS_CONFIG""Full JAAS config string
ktestify.kafka.security.ssl-truststore-locationKAFKA_SSL_TRUSTSTORE_LOCATION""Path to SSL truststore file
ktestify.kafka.security.ssl-truststore-passwordKAFKA_SSL_TRUSTSTORE_PASSWORD""Truststore password
ktestify.kafka.security.ssl-keystore-locationKAFKA_SSL_KEYSTORE_LOCATION""Path to SSL keystore file (mutual TLS)
ktestify.kafka.security.ssl-keystore-passwordKAFKA_SSL_KEYSTORE_PASSWORD""Keystore password
ktestify.kafka.security.ssl-key-passwordKAFKA_SSL_KEY_PASSWORD""Private key password

Schema Registry​

HOCON keyEnvironment variableDefaultDescription
ktestify.schema-registry.urlSCHEMA_REGISTRY_URLhttp://localhost:8081Schema Registry base URL
ktestify.schema-registry.cache-capacity—50Number of schemas to cache in memory
ktestify.schema-registry.auto-register-schemas—trueAutomatically register new schemas when producing Avro
ktestify.schema-registry.compatibility-level—BACKWARDSchema compatibility level: NONE, BACKWARD, FORWARD, FULL
ktestify.schema-registry.auth.basic-auth-credentials-sourceSCHEMA_REGISTRY_BASIC_AUTH_CREDENTIALS_SOURCE""Credentials source: USER_INFO, URL, SASL_INHERIT
ktestify.schema-registry.auth.basic-auth-user-infoSCHEMA_REGISTRY_BASIC_AUTH_USER_INFO""Credentials in username:password format
ktestify.schema-registry.ssl.truststore-locationSCHEMA_REGISTRY_SSL_TRUSTSTORE_LOCATION""Path to SSL truststore for Schema Registry
ktestify.schema-registry.ssl.truststore-passwordSCHEMA_REGISTRY_SSL_TRUSTSTORE_PASSWORD""Truststore password
ktestify.schema-registry.ssl.keystore-locationSCHEMA_REGISTRY_SSL_KEYSTORE_LOCATION""Path to SSL keystore for Schema Registry
ktestify.schema-registry.ssl.keystore-passwordSCHEMA_REGISTRY_SSL_KEYSTORE_PASSWORD""Keystore password

Timeouts​

Default overrides

ktestify-cucumber ships with longer defaults than ktestify-core to suit end-to-end test scenarios. The values below reflect the effective defaults when running the Docker image.

HOCON keyEnvironment variableCore defaultCucumber defaultDescription
ktestify.framework.timeouts.default-read-timeoutKTESTIFY_DEFAULT_READ_TIMEOUT10s30sHow long to wait for a matching record on the output topic
ktestify.framework.timeouts.consumer-delta-timeKTESTIFY_CONSUMER_DELTA_TIME20s60sHow far back in time to seek before consuming (now − delta)
ktestify.framework.timeouts.poll-interval—100ms100msKafka poll loop interval
ktestify.framework.timeouts.buffer-time—5s5sSafety buffer added to the outer ExecutorService timeout on top of default-read-timeout

Both default-read-timeout and consumer-delta-time can be overridden per scenario in the validation step DataTable (values in seconds):

Then expected record from file
  | topicAlias | file          | consumerReadTimeout | consumerDeltaTime |
  | orders-out | expected.json | 60                  | 120               |

Directories​

HOCON keyEnvironment variableDefaultDescription
ktestify.framework.directories.assetsKTESTIFY_ASSETS_DIR""Base directory for payload and expected files. Can be set per-scenario with Given assets directory.
ktestify.framework.directories.outputKTESTIFY_OUTPUT_DIR""Directory for test output files

Execution​

HOCON keyEnvironment variableDefaultDescription
ktestify.framework.execution.snapshot-modeKTESTIFY_SNAPSHOT_MODEfalseWhen true, updates expected files instead of asserting against them
ktestify.framework.execution.strict-matching—trueFail on any mismatch. Always false internally in KTestify's matchers — not user-configurable at this time.
ktestify.framework.execution.max-retries—3Maximum retries for transient failures

Logging​

HOCON keyEnvironment variableDefaultDescription
ktestify.logging.levelKTESTIFY_LOG_LEVELDEBUGLog level for io.github.ktestify.* (the framework itself)
ktestify.logging.root-levelKTESTIFY_ROOT_LOG_LEVELINFORoot logger level (all other classes)
ktestify.logging.kafka-levelKTESTIFY_KAFKA_LOG_LEVELWARNLog level for Apache Kafka client libraries
ktestify.logging.confluent-levelKTESTIFY_CONFLUENT_LOG_LEVELWARNLog level for Confluent Schema Registry / Avro libraries
ktestify.logging.testcontainers-levelKTESTIFY_TC_LOG_LEVELINFOLog level for Testcontainers (only relevant during internal test development)

Common patterns​

application.conf
ktestify {
  kafka {
    bootstrap-servers = "kafka:9092"
    topic-namespace   = "myapp"
  }
  framework {
    timeouts {
      default-read-timeout = 45s
      consumer-delta-time  = 90s
    }
    directories {
      assets = "/workspace/features"
    }
  }
}