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

- **BDD practices (Automation)**: See [references/bdd-practices.md](references/bdd-practices.md)
- **Gherkin syntax**: fetch https://git.secluded.site/agent-skills/blob/main/skills/ideating-with-bdd/references/gherkin-reference.md?raw=1 (it's plaintext)
- **gocuke API and property-based testing with rapid**: See [references/gocuke-api.md](references/gocuke-api.md)