add-cucumber-tests

What this skill does

# 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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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 → `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`
4. 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.
5. **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:

```bash
# 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
executes scenarios. `Tests run: 0` means the runner or feature discovery is broken and needs
fixing before you writ