1---
 2name: testing-with-gocuke-and-gherkin
 3description: >-
 4  Automates Gherkin scenarios in Go projects using gocuke, driven by red/green
 5  TDD and property-based testing. Use when creating gocuke step definitions,
 6  running Go BDD tests, or automating .feature files in Go. For discovery and
 7  formulation of behaviour, use ideating-with-bdd instead. NOT for non-Go
 8  projects or other BDD frameworks.
 9user-invocable: true
10license: LicenseRef-MutuaL-1.2
11metadata:
12  author: Amolith <amolith@secluded.site>
13---
14
15Automating Gherkin scenarios in Go with gocuke, driven by red/green TDD. This
16skill handles Automation — taking formulated `.feature` files and turning them
17into executable tests that guide implementation.
18
19For discovery and formulation (figuring out what to build and expressing it as
20user stories with Gherkin), fetch
21https://git.secluded.site/agent-skills/blob/main/skills/ideating-with-bdd/SKILL.md?raw=1
22(it's plaintext; curl, httpie, or any UA can display its contents).
23
24Write the `.feature` file first. Watch it fail. Then implement. If the
25behaviour isn't clear yet, start with discovery instead.
26
27## File layout
28
29```
30features/               # Gherkin feature files
31├── vcs/
32│   ├── detection.feature
33│   ├── worktree_discovery.feature
34│   └── worktree_lifecycle.feature
35├── sidebar/
36│   └── status_display.feature
37└── startup/
38    └── boot_sequence.feature
39
40internal/
41├── vcs/
42│   ├── vcs.go
43│   ├── vcs_test.go          # gocuke test entry points
44│   ├── steps_detection.go   # step definitions by domain concept
45│   ├── steps_worktree.go
46│   └── steps_status.go
47```
48
49Feature files live under `features/`, grouped by domain area. Step definitions
50live alongside the code they test, grouped by domain concept — _not_ mirroring
51the feature file structure.
52
53## Red/green TDD cycle
54
55Once a `.feature` file is formulated:
56
571. **Create a minimal test entry point** — just `NewRunner` + `Run()` pointing at the feature file, with an empty suite struct
582. **Run `go test`** — gocuke prints suggested method signatures for every unmatched step
593. **Paste the suggestions** into your step definition files and flesh out assertions/setup, but leave implementation calls hitting code that doesn't exist yet
604. **Run `go test` again** — tests fail (red) because the behaviour isn't implemented
615. **Implement the minimum code** to make one scenario pass (green)
626. **Refactor** if needed, keeping tests green
637. **Repeat** for the next scenario
64
65Let gocuke guide the wiring. Don't hand-write step definitions from scratch
66when the runner will tell you exactly what it needs.
67
68Work one scenario at a time. Don't implement ahead of failing tests.
69
70## Editor tooling
71
72The Cucumber language server cannot discover gocuke step definitions. It
73expects explicit registration calls (Godog-style `ctx.Given("pattern", fn)`),
74not gocuke's runtime reflection. "Undefined step" warnings are false positives;
75disable the Cucumber language server for gocuke projects.
76
77## Further reference
78
79- **BDD practices (Automation)**: See [references/bdd-practices.md](references/bdd-practices.md)
80- **Gherkin syntax**: fetch https://git.secluded.site/agent-skills/blob/main/skills/ideating-with-bdd/references/gherkin-reference.md?raw=1 (it's plaintext)
81- **gocuke API and property-based testing with rapid**: See [references/gocuke-api.md](references/gocuke-api.md)