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