vavalleevavallee/bindery/.claude/skills/testing/SKILL.md

testing

Skill518 starsChanged 57 days agoMITView on GitHub

Use when writing or running Bindery tests, before pushing, or before opening a PR — covers the full pre-PR matrix (lint, vet, govulncheck, test, frontend), pinned tool versions, the project's test patterns (db.OpenMemory, httptest, vitest), and common failure modes.

Installs packages

We split this skill into the rules it gives an agent

8 rules. 0 are common, 0 are distinctive, and 8 are very specific to this project.

0
Common
Most of the 171 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Always check rows.Err() after iterating SQL rows (rowserrcheck enforces it).
line 49
Very specific:
Prefer userEvent over fireEvent for interactions.
line 57
Very specific:
Run a single page test fast: npm test -- BooksPage.test.tsx (no watch).
line 58
Very specific:
Don't t.Skip() a flaky test to make CI green — investigate or revert the change that introduced flake.
line 84
Very specific:
Don't mock internal/db. Use the in-memory DB.
line 85
Very specific:
Don't add new build tags (//go:build foo) — the project doesn't use them.
line 86
Very specific:
Don't add //nolint without a reason on the same line.
line 87
Very specific:
Don't commit coverage.out or web/coverage/ — they're build artifacts.
line 88

“Common” is measured: kept by at least 6 in 10 of the 171 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

Testing Bindery

CI runs every check below on every push and PR. Mirror it locally before pushing — failing CI is slower than failing locally.

Pre-PR matrix

# Go
gofmt -l . | tee /dev/stderr | (! read)    # exits non-zero if any file is unformatted
go vet ./...
golangci-lint run --timeout=5m             # pinned to v2.11.4 — see below
govulncheck ./...
go test -race -coverprofile=coverage.out -covermode=atomic ./cmd/... ./internal/...

# Frontend (skip if web/ untouched)
cd web && npm ci && npm run lint && npm run typecheck && npm run build && npm test

Make wrappers for convenience:

make lint — Go + frontend linters
make test — Go tests + coverage, no race, same as the CI gate
make test-race — the race detector in CI's six shards (#2293)
make test-web — vitest + coverage

For wiring-level changes (handlers, scheduler jobs, downloader integrations, import flows), unit tests aren't enough. Escalate to make smoke — see the smoke-testing skill for the decision tree.

Pinned tool versions

go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.11.4
go install golang.org/x/vuln/cmd/govulncheck@latest

CI uses golangci-lint v2.11.4 exactly. @latest locally can disagree with CI and waste a round-trip.

Test patterns

Backend (Go)

One _test.go file per source file, sibling location (internal/api/books.go → internal/api/books_test.go).
DB-backed tests use db.OpenMemory() from internal/db. Never use temp files; never mock the DB. Mocked DB tests pass when migrations are broken.
HTTP handlers: httptest.NewRecorder + httptest.NewRequest, exercise routes through the same setup as production.
Assertions on wrapped errors: errors.Is / errors.As (errorlint rejects ==).
Always check rows.Err() after iterating SQL rows (rowserrcheck enforces it).
Outbound HTTP in tests: stub via httptest.NewServer, never live network.

Frontend (React + TS)

Pages: web/src/pages/<Name>Page.tsx with sibling <Name>Page.test.tsx.
vitest + @testing-library/react + jsdom; setup in web/src/test-setup.ts.
Mock the API client (web/src/api/) — never hit the network.
Prefer userEvent over fireEvent for interactions.
Run a single page test fast: npm test -- BooksPage.test.tsx (no watch).

When new code requires new tests

Change	Tests required?
New HTTP handler in `internal/api/`	Yes — sibling `_test.go` covering the success path and at least one error path
New exported function with branching	Yes
New domain logic in `internal/{indexer,downloader,importer,...}`	Yes
New React component with state, effects, or event handlers	Yes
Pure rendering / styled markup	Optional but appreciated
Pure refactor, no behaviour change	Existing tests must still pass; new tests not required

Common failure modes

Symptom	Likely cause
`gofmt` flags a file you didn't touch	Merge-base drift; run `gofmt -w <path>`
`govulncheck` fails with a CVE you didn't introduce	New advisory in a transitive dep. Bump the offender; call out the bump in the PR body
Every test in a package fails	A migration regression. Each package opens a fresh in-memory DB and runs all migrations — one broken migration takes the whole package down
`vitest` passes, `vite build` fails	Missing static asset import or type error `tsc --noEmit` didn't catch. Run typecheck + build together
Test passes locally, fails on CI with `-race`	A goroutine leak or unsynchronized map access. Run locally with `-race -count=10` to reproduce
Smoke suite hangs at startup	Binary panicking before binding. Run `./bindery` directly, read stderr

Don't

Don't t.Skip() a flaky test to make CI green — investigate or revert the change that introduced flake.
Don't mock internal/db. Use the in-memory DB.
Don't add new build tags (//go:build foo) — the project doesn't use them.
Don't add //nolint without a reason on the same line; readers and CI both expect a justification.
Don't commit coverage.out or web/coverage/ — they're build artifacts.

Download now (ZIP)

Other versions191 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 191
modelcontextprotocol/servers★ 92ksame name
lobehub/lobe-chat★ 84ksame name
lobehub/lobehub★ 84ksame name
penpot/penpot★ 62ksame name
meteor/meteor★ 45ksame name
iOfficeAI/AionUi★ 34ksame name
garrytan/gbrain★ 31ksame name
OpenZeppelin/openzeppelin-contracts★ 27ksame name
tursodatabase/turso★ 25ksame name
redis/go-redis★ 22ksame name
181 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use bundle-dependency-prs, update-library-template and 10 more.
Other files people use alongside this one.
- MicrosoftSkill
  bundle-dependency-prs
  Fix broken dependency update PRs and aggregate the ones that work into one PR.
  Also in 6 projects that use this
- MicrosoftSkill
  update-library-template
  Merges the latest Library.Template into this repo (at position of HEAD) and resolves conflicts.
  Also in 6 projects that use this
- zetaloopSkill
  assign-copilot
  Assigns a GitHub issue to the Copilot coding agent, optionally specifying a custom agent. Use this when asked to assign an issue to Copilot or delegate an issue to CCA.
  Also in 3 projects that use this
- NVIDIA-NeMoSkill
  build-and-dependency
  Build and dependency management for NeMo-RL. Covers Docker image building and running, uv usage, venv setup, and adding dependencies.
  Also in 3 projects that use this
- timmo001Skill
  changeset-scope
  Keep all scoped code work contained to the user-defined changeset. Use for implementation, fixes, diagnosis, refactoring, cleanup, and review when explicit instructions, named files, diffs, branches, pull requests, or injected work scopes define the boundary.
  Also in 3 projects that use this
- NVIDIA-NeMoSkill
  linting-and-formatting
  Code style guidelines for NeMo-RL (Python and shell). Covers naming, indentation, comments, docstrings, reflection avoidance, and uv usage.
  Also in 3 projects that use this
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- autofixSkill
- commitsSkill
- discord-reportsSkill
- fix-issueSkill
- prsSkill
- smoke-testingSkill
- tag-releaseSkill
- triageSkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free

8 rules. 0 are common, 0 are distinctive, and 8 are very specific to this project.

Testing Bindery

Pre-PR matrix

Pinned tool versions

Test patterns

When new code requires new tests

Common failure modes

Don't

Word for word · 0

Edited · 0

Wrote their own version · 191

bundle-dependency-prs

update-library-template

assign-copilot

build-and-dependency

changeset-scope

linting-and-formatting

Does it work?

Your trail

Now do this for your own.