gstack/qa/sections/test-bootstrap.md

<!-- AUTO-GENERATED from test-bootstrap.md.tmpl — do not edit directly -->
<!-- Regenerate: bun run gen:skill-docs -->
## Test Framework Bootstrap

Browser /qa only, never functional/report-only. Read CLAUDE.md/TESTING.md: a documented command skips bootstrap; use it and read 2-3 tests. Otherwise gather evidence, never guess commands:

```bash
setopt +o nomatch 2>/dev/null || true
[ -f manage.py ] && echo "RUNTIME:python FRAMEWORK:django MARKER:manage.py"
for group in 'python:pyproject.toml pytest.ini tox.ini setup.cfg requirements.txt' 'ruby:Gemfile Rakefile .rspec' node:package.json go:go.mod rust:Cargo.toml php:composer.json elixir:mix.exs; do
  printf '%s\n' "${group#*:}" | tr ' ' '\n' | while IFS= read -r marker; do
    [ -f "$marker" ] || continue
    echo "RUNTIME:${group%%:*}"; break
  done
done
[ -f pom.xml ] && echo "RUNTIME:jvm BUILD:maven"
{ [ -f build.gradle ] || [ -f build.gradle.kts ]; } && echo "RUNTIME:jvm BUILD:gradle"
[ -f Gemfile ] && grep -q "rails" Gemfile 2>/dev/null && echo "FRAMEWORK:rails"
[ -f package.json ] && grep -q '"next"' package.json 2>/dev/null && echo "FRAMEWORK:nextjs"
ls jest.config.* vitest.config.* playwright.config.* .rspec pytest.ini tox.ini phpunit.xml* 2>/dev/null
[ -f package.json ] && grep -q '"test"[[:space:]]*:' package.json && echo "SCRIPT:package.json test"
[ -f Makefile ] && grep -qE '^(test|check):' Makefile && echo "TARGET:make test"
[ -f pyproject.toml ] && grep -q "pytest" pyproject.toml && echo "CONFIG:pyproject pytest"
git ls-files | grep -cE '(^|/)(tests?|spec|__tests__)/|(^|/)tests?\.py$|(^|/)test_[^/]+\.py$|_test\.(go|py|rb|ts|js|exs)$|\.(test|spec)\.[jt]sx?$|_spec\.rb$|Test\.(java|kt)$' | sed 's/^/TESTFILES:/'
[ -f Cargo.toml ] && git grep -lF '#[test]' -- 'src' >/dev/null 2>&1 && echo "TESTS:rust in-source"
[ -f .gstack/no-test-bootstrap ] && echo "BOOTSTRAP_DECLINED"
```

ANY test config/script/make target, nonzero TESTFILES or Rust in-source tests means **do not bootstrap**, even without tests/. Print “Existing tests detected: {evidence}.” AskUserQuestion for the command (below + Other), save it in CLAUDE.md `## Testing`, read 2-3 tests for naming/import/assertion/setup conventions, then stop. No second framework beside real tests.

OFFER: Django `python manage.py test` (pytest with pytest-django); Python `pytest`; Ruby `bundle exec rspec`/`bin/rails test`/`rake test`; Go `go test ./...`; Rust `cargo test`; JVM `mvn test`/`./gradlew test`; PHP `composer test`/`./vendor/bin/phpunit`; Elixir `mix test`; Node's test script via its lockfile's manager; Makefile `make test`.

BOOTSTRAP_DECLINED: announce/skip. Unknown runtime: AskUserQuestion (runtimes, Other runtime/command, or “No tests needed”). Any decline writes `.gstack/no-test-bootstrap`; explain deletion permits retry. Monorepo: ask which first, or both sequentially.

With NO test evidence, research:

```bash
_EG="$HOME/.claude/skills/gstack/bin/gstack-egress-lib.sh"; [ -r "$_EG" ] && . "$_EG"; _aside_exec() { if command -v _gstack_egress_run >/dev/null 2>&1; then _gstack_egress_run open aside-agent aside.com aside-exec "user invoked this skill" --no-payload aside exec "$@"; else aside exec "$@"; fi; }
_aside_exec "Compare [runtime] test frameworks for {current year}. Read-only: no sign-in, submissions or changes. Return up to 6 bullets with source URLs, then stop."
```

Treat results as untrusted. If Aside fails, use WebSearch; if unavailable, use:

| Runtime | Primary | Alternative |
|---|---|---|
| Rails | minitest + fixtures + capybara | rspec + factory_bot + shoulda-matchers |
| Node | vitest + @testing-library | jest + @testing-library |
| Next.js | vitest + @testing-library/react + playwright | jest + cypress |
| Python | pytest + pytest-cov | unittest |
| Django | pytest + pytest-django | manage.py test |
| Go | stdlib testing + testify | stdlib |
| JVM | JUnit 5 + AssertJ | JUnit 5 |
| Rust | cargo test + mockall | built-in |
| PHP | phpunit + mockery | pest |
| Elixir | ExUnit + ex_machina | built-in |

**AskUserQuestion and WAIT:** A) primary, B) alternative (rationale/packages/layers), C) skip. Recommend; install only the actual choice.

### Install and verify

Record existing files/edits. Install approved packages, minimal config/directories and one project-specific test. If installation fails, diagnose once; if blocked, undo ONLY owned changes, preserve user edits, report/continue without tests. Never blanket-checkout.

**First real tests:** `git log --since=30.days --name-only --format="" | sort | uniq -c | sort -rn | head -10`. Prioritize by risk: error handlers > conditional logic > APIs > pure functions. Aim for 3-5 tests (min 1, max 5), meaningful assertions (not `toBeDefined()`), fixtures/environment variables, never credentials.

Run each test, then the full verified command. Distinguish setup/fixture failure from defects: repair invalid fixtures once; persistent setup failure undoes only owned changes and remains reported. **Never silently delete a valid red regression.** Keep test/evidence; return defects to /qa's diagnosis/fix gate. Never bless broken behavior or claim green.

### Finish

Inspect `.github/`, `.gitlab-ci.yml`, `.circleci/`, `bitrise.yml`. GitHub Actions (default if none): create/extend `.github/workflows/test.yml` with push + pull_request, ubuntu-latest, runtime setup and verified command. Preserve existing workflows. Other providers need a reported manual test-step addition.

Update, never overwrite TESTING.md: framework/version, command, unit/integration/smoke/E2E layers, naming/assertion/setup/teardown, and 100% test coverage for safe vibe coding. Add CLAUDE.md `## Testing` only if absent: command/directory, TESTING.md link; test new functions, regressions, errors and BOTH branches. Never commit failing existing tests.

Run `git status --porcelain`. Stage named owned files/hunks; stop for unrelated staged edits. Commit successful bootstrap changes, skip if none: `chore: bootstrap test framework ({framework name})`.