Add Cucumber Tests

BDD Test Generation with Tzatziki

Generate valid Cucumber .feature files from a user's functional specification, using Tzatziki's step definition library as the source of truth for legal step patterns.

Principles

These explain the reasoning behind the workflow — understanding them helps you handle edge cases the workflow doesn't explicitly cover.

1. Steps come from code, not imagination. Tzatziki provides hundreds of pre-built @Given / @When / @Then patterns in its *Steps.java files. Inventing step text that doesn't match a real definition produces UndefinedStepException at runtime. Per-module reference files in references/steps-*.md contain every legal step pattern — read the relevant ones before writing any scenario.

⚠️ Never paraphrase or improvise step keywords. Many step patterns use regex constants like COMPARING_WITH that expand to a small fixed set of keywords (e.g., "" empty, " exactly", " at least", " only"). Do not substitute natural-language synonyms such as "containing", "including", "matching", or any other word that "sounds right" — if the word does not appear in the @Given/@When/@Then annotation regex, the step will be undefined at runtime. When in doubt, re-read the Java source in references/steps-*.md rather than guessing.

1. Verify the environment before writing tests. Run at least one existing Cucumber test in the target module before creating new feature files. This catches missing dependencies, broken bootstrap, or misconfigured runners early — before you've invested effort in writing scenarios that can't execute. If no test exists yet, create the minimal bootstrap first and confirm it discovers at least one scenario.

1. YAML by default for structured data. Tzatziki scenarios are most readable when request bodies, database fixtures, Kafka payloads, and expected results use """yml doc strings. Fall back to Gherkin tables for naturally tabular data, or raw JSON only when the contract requires it.

1. Cover exactly what the user asked for — then help them think about what they missed. Generate scenarios for every functional behavior in the user's specification — not just the happy path. But don't silently add extra scenarios either. Instead, after covering the requested scope, actively identify edge cases and present them to the user as optional additions. To identify edge cases effectively, look at three things: (a) every external service call in the scenario — what happens if it returns an error (4xx, 5xx) or times out? (b) every data collection — what happens if it's empty or contains unexpected values? (c) existing test files in the project that test similar features — they often contain error-handling patterns you can adapt for the new scenario. The user decides which edge cases to include, but your job is to surface them so nothing important is missed.

1. Reuse what exists. If the project already has a runner, bootstrap class, feature location convention, or glue configuration — reuse them. Creating duplicates causes classpath conflicts and confuses test discovery.

1. Prefer updating existing scenarios over creating new ones. When a specification adds a new field, header, or assertion to an already-tested behavior (e.g., "add a traceId header to the message this flow already publishes"), the right approach is almost always to modify the `Then` assertion of an existing scenario that already exercises that behavior, rather than creating a brand-new scenario that duplicates all the same Given/When setup just to check one additional field. Creating a new scenario is only justified when the behavior itself is genuinely new — a different trigger, a different code path, or a different precondition combination that no existing scenario covers. This matters because test suites grow quickly, and every duplicated scenario is a maintenance burden: when the shared setup changes, every copy must be updated in lockstep or the suite becomes inconsistent.

Workflow

1. Understand the Specification

Analyze the user's input and break it into a checklist of distinct functional behaviors. Each behavior will become one or more scenarios. If anything is ambiguous, ask before proceeding.

While analyzing, classify each behavior as one of:

• New behavior — a genuinely new trigger, code path, or precondition combination that no existing scenario covers. This requires a new scenario.
• Additive change — a new field, header, assertion, or output added to an already-tested behavior (e.g., "add a traceId header to the message this scenario already publishes"). This should be handled by modifying the existing scenario's assertions, not by creating a new scenario. See Principle 6.

Also extract:

• External dependencies — every API, service, or data source the feature interacts with. Each one is a potential source of edge-case scenarios (errors, timeouts, empty responses).
• Performance or reliability hints — if the spec mentions performance concerns, large data volumes, or error handling, note them. These signal scenarios the user likely cares about even if they didn't write explicit acceptance tests for them.
• Implicit error paths — if the spec says "call service X to get Y", the spec is describing the happy path. The failure path (service X returns an error) is an edge case to suggest.

2. Discover the Project

Detect the build tool (prefer wrappers: ./mvnw over mvn, ./gradlew over gradle), then:

1. Always read `references/steps-core.md` — core step definitions (ObjectSteps) are used in every Tzatziki project for variables, assertions, and data manipulation.
2. *Detect which `tzatziki- modules** the project depends on by inspecting pom.xml or build.gradle for dependency declarations. A quick way to extract them: `bash grep -o 'tzatziki-[a-z-]*' pom.xml | sort -u ``
3. Read the matching per-module reference(s) based on detected dependencies:

• HTTP/REST testing → references/steps-http.md
• Spring context → references/steps-spring.md
• JPA/database → references/steps-spring-jpa.md
• Kafka messaging (plain Apache Kafka) → references/steps-kafka.md
• Kafka messaging (Spring Kafka) → references/steps-spring-kafka.md
• MongoDB → references/steps-spring-mongodb.md
• OpenSearch → references/steps-opensearch.md
• Logging assertions → references/steps-logback.md
• MCP/AI testing → references/steps-mcp.md

1. When in doubt between a step pattern inferred from a .feature example and one read from the Java *Steps.java source, trust the Java source.
2. Catalog error-handling patterns from existing .feature files you encounter during discovery. Note how the project tests HTTP error responses (e.g., mocking 404/500 from external APIs), empty data, cache misses, or retry behavior. You'll use these patterns as templates when suggesting edge cases in Step 5.

3. Check the Bootstrap

Search for the existing test infrastructure:

• Runner: @Suite + @IncludeEngines("cucumber") (JUnit 5) or AbstractTestNGCucumberTests
• Feature location: @SelectClasspathResource(...) or @SelectDirectories(...)
• Spring context: @CucumberContextConfiguration + @SpringBootTest (if Spring is used)

If any piece is missing, plan to create it. Read references/bootstrap-templates.md for the JUnit 5 runner and Spring configuration templates.

4. Verify the Environment

Run the existing test suite in the target module to confirm it works:

# Maven
./mvnw -pl <module> -Dtest=<RunnerClass> test
# Gradle
./gradlew :<module>:test --tests <RunnerClass>

A passing or functionally-failing run is fine — what matters is that Cucumber discovers and