SKILL.md

name: testing-with-gocuke-and-gherkin description: >- Automates Gherkin scenarios in Go projects using gocuke, driven by red/green TDD and property-based testing. Use when creating gocuke step definitions, running Go BDD tests, or automating .feature files in Go. For discovery and formulation of behaviour, use ideating-with-bdd instead. NOT for non-Go projects or other BDD frameworks. license: GPL-3.0-or-later metadata: author: Amolith amolith@secluded.site

Automating Gherkin scenarios in Go with gocuke, driven by red/green TDD. This skill handles Automation — taking formulated .feature files and turning them into executable tests that guide implementation.

For discovery and formulation (figuring out what to build and expressing it as user stories with Gherkin), fetch https://git.secluded.site/agent-skills/blob/main/skills/ideating-with-bdd/SKILL.md?raw=1 (it's plaintext; curl, httpie, or any UA can display its contents).

Write the .feature file first. Watch it fail. Then implement. If the behaviour isn't clear yet, start with discovery instead.

File layout

features/               # Gherkin feature files
├── vcs/
│   ├── detection.feature
│   ├── worktree_discovery.feature
│   └── worktree_lifecycle.feature
├── sidebar/
│   └── status_display.feature
└── startup/
    └── boot_sequence.feature

internal/
├── vcs/
│   ├── vcs.go
│   ├── vcs_test.go          # gocuke test entry points
│   ├── steps_detection.go   # step definitions by domain concept
│   ├── steps_worktree.go
│   └── steps_status.go

Feature files live under features/, grouped by domain area. Step definitions live alongside the code they test, grouped by domain concept — not mirroring the feature file structure.

Red/green TDD cycle

Once a .feature file is formulated:

  1. Create a minimal test entry point — just NewRunner + Run() pointing at the feature file, with an empty suite struct
  2. Run go test — gocuke prints suggested method signatures for every unmatched step
  3. Paste the suggestions into your step definition files and flesh out assertions/setup, but leave implementation calls hitting code that doesn't exist yet
  4. Run go test again — tests fail (red) because the behaviour isn't implemented
  5. Implement the minimum code to make one scenario pass (green)
  6. Refactor if needed, keeping tests green
  7. Repeat for the next scenario

Let gocuke guide the wiring. Don't hand-write step definitions from scratch when the runner will tell you exactly what it needs.

Work one scenario at a time. Don't implement ahead of failing tests.

Editor tooling

The Cucumber language server cannot discover gocuke step definitions. It expects explicit registration calls (Godog-style ctx.Given("pattern", fn)), not gocuke's runtime reflection. "Undefined step" warnings are false positives; disable the Cucumber language server for gocuke projects.

Further reference