samurai: Instructions file for Claude Code

CLAUDE.md

This file contains guidance for Claude Code when working on this project.

Project Overview

Samurai is a scoped testing framework for Go with path isolation, inspired by GoConvey but modernized with:

• Explicit context passing (no GLS/goroutine-local-storage)
• Standard context.Context support for cancellation/timeouts
• Assertion-library agnostic (users bring their own)
• Zero external dependencies
• Parallel execution by default — including the top-level TestXxx function, not just samurai-generated sub-tests. Pass samurai.Sequential() to opt out (required for tests that use t.Setenv, bind fixed ports, etc.)
• No double execution - code runs exactly once per test path
• Generic RunWith for custom test contexts via embedded *BaseContext (Go 1.25+ generic type aliases)

Git Workflow

• NEVER push directly to master. Always work through a PR: create a branch, push, gh pr create, gh pr merge.
• Release via the Release GitHub Actions workflow (workflow_dispatch). Trigger it with gh workflow run release.yml -f version=vX.Y.Z (version must match v*.*.*). The workflow gates the release on go vet + go test -race ./..., then creates the tag and the GitHub Release with --generate-notes. NEVER tag or release manually (git tag, gh release create) — that bypasses the race-test gate. See .github/workflows/release.yml.

Build & Test Commands

go test ./...           # Run all tests
go test -v ./...        # Verbose test output
go test -race ./...     # Run with race detector

Code Style

• Follow standard Go conventions
• Keep the API minimal - users control behavior via their assertion library and t.Skip()
• Prefer composition over inheritance
• All public types and functions must have doc comments

Architecture

• samurai.go - Public API: Run, RunWith[V], Context interface, W type alias, options (Parallel, Sequential); internal path tree building (pathNode, buildPathTree, executeTree[V]); identityFactory for the non-generic Run
• scope.go - TestScope[V] generic struct with Test() and Skip() methods; type Scope = TestScope[W] alias
• scope_runner.go - Generic path discovery (collectScopedPaths[V], collectPathsFromChildren, probeBuilder) and execution (executeScope[V], executeScopedPath[V])
• base_context.go - BaseContext struct implementing Context interface; provides Context(), Testing() and Cleanup()
• runner.go - Shared helpers: panic recovery, cleanup execution