samurai

Samurai Test Writing Rules

Good For: Go tests with a branching state-mutating tree (≥3 leaf paths, mutually exclusive siblings) using samurai.Run / samurai.RunWith. Bad For: read-only chains, sequential accumulation, same-action-different-input variants, flat independent tests (see "When to Use" below for full criteria).

Rules

• One action + its assertions = one Test(). Don't split assertions into child Tests — assert the result in the same callback that produced it. Child Tests are for new actions (setup, mutations, queries), not for checking fields of a parent's result
• DECLARE variables with var in the builder body, ASSIGN inside Test() callbacks
• Each leaf path re-executes the builder from scratch — fresh variables, full isolation
• w.Cleanup(fn): LIFO order, inner before outer, runs even on panic, thread-safe
• s.Skip(): affects entire scope regardless of call order, no callbacks/cleanups execute
• w.Context(): returns the scope's context.Context — use in factories for initialization needing a context
• context.Context: first param in Test callbacks, live during test, canceled after path completes
• Parallel by default; samurai.Sequential() forces order; go test -parallel N controls concurrency
• Assertion-agnostic: use w.Testing() with any library (testify, is, stdlib)

Naming

Every s.Test("name", ...) — at every tree level — names a business action or outcome from the actor's POV. Not the function under test, the assertion, or the input shape.

Forbidden patterns:

• Identifier leak — CamelCase tokens matching Go identifiers in the Test body. "UpdateQuote calls..." leaks UpdateQuote.
• HTTP code leak — bare 3-digit codes (\b[1-5]\d{2}\b) or 4xx/5xx shorthand. "returns 409" → "rejects duplicate id".
• Assertion phrasing — is / equals / returns / not nil / has length / contains. "err is not nil" → "rejects invalid signature".
• Structure phrasing — empty / nil / with N / map / slice / struct. "with empty slice" → "borrower has no past loans".