From 57a3961ab08a5b2363335e561da66482deb14183 Mon Sep 17 00:00:00 2001 From: Jonathan Jamroga Date: Thu, 29 Oct 2026 20:48:59 -0400 Subject: [PATCH 1/2] docs(test): add Given/When/AssertThat testing skill Signed-off-by: Jonathan Jamroga --- .../skills/given-when-assert-that/SKILL.md | 44 +++++++++++++++++++ .claude/skills/given-when-assert-that | 1 + 2 files changed, 45 insertions(+) create mode 100644 .agents/skills/given-when-assert-that/SKILL.md create mode 120000 .claude/skills/given-when-assert-that diff --git a/.agents/skills/given-when-assert-that/SKILL.md b/.agents/skills/given-when-assert-that/SKILL.md new file mode 100644 index 0000000000..2968833acf --- /dev/null +++ b/.agents/skills/given-when-assert-that/SKILL.md @@ -0,0 +1,44 @@ +--- +name: given-when-assert-that +description: Design and write Go behavior tests as readable Given/When/AssertThat scenarios with observable assertions, using ordinary Go tests without a BDD framework. +--- + +# Given/When/AssertThat Go tests + +Use this skill when writing Go behavior tests, including tests for new features and bug fixes. Keep the tests executable with `go test`. Do not add a BDD runner, `.feature` files, code generation, or a generic step registry. + +## Choose behavior before writing test code + +- Identify the user-visible contract and the boundary that proves it: an HTTP or gRPC response, handler reachability, caller identity, persisted state, or emitted event. Do not test only a helper when the behavior depends on listener wiring, serialization, or persistence. +- Start with a working case and the few failure or boundary cases that could change the outcome. Include missing, empty, malformed, and fallback inputs only when the contract treats them differently. Set up any state that a negative assertion depends on, so the test cannot pass against an empty or unwired system. +- For each case, write down `Given , when , assert that `. Make the assertion specific enough to fail if the behavior is absent; avoid tests that just check constants, mocks, or implementation steps. + +## Write the scenario as an ordinary Go test + +- Give each test function a short behavior name. When subtests help distinguish cases, give each `t.Run` a sentence: `Given , when , assert that `. Do not add a subtest or fixture just to satisfy the naming pattern. +- Use an **eventive When**, not a stative one. "When a caller sends an RPC without a token" names the stimulus. "When an RPC has no credentials" describes state. Put stable state in Given. +- Make the name match the actual input. "No valid token" includes missing, malformed, and expired tokens. Do not use it for a case that sends only a missing token. +- Keep variants in a `scenarios` matrix when they share an action and assertion. Give distinct behaviors separate named subtests. Do not branch assertions on expected outcomes to force unlike cases into one table. + +## Keep the invocation readable + +Keep setup local for a single case. When several cases share substantial setup or transport mechanics, put test functions and scenario matrices above reusable helpers and create a fresh fixture inside each subtest unless shared state is immutable and the cases cannot interfere. + +```go +func TestProtectedEndpoint(t *testing.T) { + t.Run("Given a protected endpoint, when a request has no token, assert that dispatch is rejected", func(t *testing.T) { + newAuthFixture(t). + GivenProtectedEndpoint(). + WhenRequestWithoutCredentials(). + AssertThatRequestIsRejectedBeforeDispatch() + }) +} +``` + +`Given` sets up the invariant, `When` performs the action, and `AssertThat` checks the result at the boundary. Keep an existing Options-based fixture setup when it makes configuration choices explicit; do not flatten it into raw transport calls for presentation. Pair this rejection case with a valid-token case proving the handler is reachable; otherwise a permanently unwired handler could pass the negative test. Use stage methods only when they remove repeated mechanics. + +If updating an existing test, preserve its behavior, assertions, cleanup, and meaningful edge cases. Do not rewrite neighboring tests merely for presentation. + +## Check that the tests prove the contract + +Run `gofmt` on changed Go files and the smallest `go test` command that exercises every new case. Run the repository's applicable lint command. For a regression test, confirm it fails against the broken behavior and passes with the fix; for a new feature, confirm each assertion observes the intended boundary rather than a fixture's own return value. Replace `/` in dynamic names so `testing.T.Run` does not split a sentence into nested subtests. diff --git a/.claude/skills/given-when-assert-that b/.claude/skills/given-when-assert-that new file mode 120000 index 0000000000..65428176fd --- /dev/null +++ b/.claude/skills/given-when-assert-that @@ -0,0 +1 @@ +../../.agents/skills/given-when-assert-that \ No newline at end of file From dd7212582140285996aef36482ba0e5e6fa41bc1 Mon Sep 17 00:00:00 2001 From: Jonathan Jamroga Date: Thu, 29 Oct 2026 20:52:25 -0400 Subject: [PATCH 2/2] docs(test): make scenario skill the Go testing default Signed-off-by: Jonathan Jamroga --- AGENTS.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index dabd5b7c70..e36e507dff 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -98,6 +98,9 @@ Preserve unrelated work in a dirty tree. Do not hand-edit generated outputs, add ## 7. Testing and Validation +- Before writing or changing Go behavior tests anywhere in this repository, use the + [`given-when-assert-that`](.agents/skills/given-when-assert-that/SKILL.md) skill. + Apply it to feature and bug-fix tests as well as test-only changes. - Unit-test new semantic behavior and failure paths. - Use table-driven Go tests where they make cases clearer; do not force the pattern onto a single case. - Mock external services in unit tests. Use real integration boundaries in E2E tests.