🧪 bestest

bestest is an AI-native testing skill that architects your entire testing layer — not just generates a test file and hopes for the best.

It's a 120+ file, ~40K-line specification that lives inside your AI coding agent and handles strategy, framework selection, test generation, CI pipelines, flaky test management, framework migration, and living documentation. All version-controlled in your repo.

Other tools: "Write a test for X" → a test file (maybe compiles, maybe passes)
bestest: Detect stack → Pick framework → Generate → Compile → Run → Score → Ship

Runtime Model — bestest is a skill, not a CLI tool. It's a directory of markdown files that AI coding agents (GSD/pi, Claude Code, Cursor, etc.) load as instructions. When you run /bestest generate, the agent reads the corresponding spoke file and follows it step-by-step. There's no daemon, no binary, no API server — just structured markdown that makes your agent smarter about testing.

bestest works with any AI coding agent that loads skills from a local directory — including GSD/pi (an agent harness with auto-mode), Claude Code, Cursor, and others.

A skill is a directory of markdown instructions that AI coding agents read and follow. When you install bestest into your agent's skills directory, the agent gains the ability to architect your entire testing layer — detecting your stack, recommending frameworks, generating tests, and managing CI pipelines — all without leaving your editor.

# Clone the repo
git clone https://github.com/baagad-ai/bestest.git
# Copy to your agent's skills directory
cp -r bestest/ ~/.agents/skills/bestest/

In any agent session:

/bestest # First run? Initializes testing infrastructure
/bestest init # Audit repo, scaffold test infrastructure
/bestest generate src/ # Generate tests for a file or directory
/bestest scan # Deep audit of current test state
/bestest run # Execute test suites with structured result capture
/bestest doctor # Health check your test infrastructure

That's it. bestest detects your stack automatically — no config needed to start.

init ──► scan ──► generate ──► run ──► coverage ──► fix
 │ │ │
 ▼ ▼ ▼
config.yaml New test files Fixed tests
TESTING.md (compiled + passed) (root-caused + verified)
stack-profile.json

bestest uses a lean orchestrator + spoke pattern. Only one spoke loads per command, keeping context windows small while supporting 16 commands (19 spokes) across 4 languages.

SKILL.md (orchestrator — routing, principles, reference index)
├── references/
│ ├── spoke-init.md ← /bestest init
│ ├── spoke-generate.md ← /bestest generate (JS/TS)
│ ├── spoke-generate-python.md ← /bestest generate (Python)
│ ├── spoke-generate-java.md ← /bestest generate (Java)
│ ├── spoke-generate-go.md ← /bestest generate (Go)
│ ├── spoke-scan.md ← /bestest scan
│ ├── spoke-run.md ← /bestest run
│ ├── spoke-fix.md ← /bestest fix
│ ├── spoke-coverage.md ← /bestest coverage
│ ├── spoke-doctor.md ← /bestest doctor
│ ├── spoke-migrate.md ← /bestest migrate
│ ├── spoke-ci.md ← /bestest ci
│ └── ... (19 spokes total)
└── scripts/
 ├── validate-skill.sh ← 347 structural consistency checks
 ├── validate-contracts.sh ← 77 golden-fixture contract checks
 └── bestest-cli.py ← deterministic helper (detect/config/report/lock/metrics)

When you run /bestest generate, it doesn't just spit out a test file. It runs a verified pipeline:

Phase 1: TARGET → Which files need tests?
Phase 2: CONTEXT → Read source, existing tests, framework docs (via Context7)
Phase 3: STRATEGY → Map each export to a test strategy (pure fn, component, API, etc.)
Phase 4: GENERATION → Write the test code with proper mocking and assertions
Phase 5: COMPILE → Run the compiler. Auto-fix if it fails. (3 retry attempts)
Phase 6: EXECUTE → Run the tests. Auto-fix if they fail. (2 retry attempts)
Phase 7: QUALITY AUDIT → Score 0-100. Anti-pattern detection. Flakiness check.

Every generated test must compile, pass, and score ≥ 70 on the quality rubric before it lands on disk.

bestest detects your stack from 190+ signals across 14 categories, with confidence scores and evidence arrays:

Detected: TypeScript (0.94), React (0.88), Vitest (0.72), Vite (0.91)
Evidence: tsconfig.json, package.json → "typescript" in devDeps, src/**/*.ts, vite.config.ts
Framework recommendation: Vitest (existing framework — continue using it)

No "what framework are you using?" prompts. It knows.

All state lives in .bestest/ inside your repo — version-controlled, auditable, shareable:

.bestest/
├── config.yaml ← Single source of truth
├── TESTING.md ← Living documentation (auto-updated)
├── state/
│ ├── stack-profile.json ← Detected stack with confidence scores
│ └── metrics.json ← Cross-spoke metrics store
├── adrs/
│ └── ADR-001-test-framework.md ← Architecture Decision Records
└── reports/
 └── scan-2026年04月26日.json ← Timestamped scan reports

1. Test architecture, not just tests — Tests are the output; architecture is the product
2. Repo as source of truth — All state in .bestest/, version-controlled, no external stores
3. Progressive complexity — init gives you a foundation; each command adds capability
4. Human-in-the-loop on mutations — Confirmation gates for init, generate, fix, migrate, ci. No gate on read-only commands (scan, run, coverage, report, doctor)
5. Framework-agnostic — Detects your stack, recommends the right tool, never forces a choice
6. Verification-driven — Every generated test compiles, passes, and covers meaningful behavior
7. Living documentation — TESTING.md is generated once, updated automatically on every scan

bestest validates itself. A CI pipeline runs three suites — 347 structural consistency checks, 314 integrity checks, and 77 golden-fixture contract checks — across these domains:

• File structure integrity
• Cross-reference validity (no phantom file references)
• Schema compliance
• Content completeness (no placeholders)
• Spoke consistency (shared sections match)
• Template validity
• Version parity
• Behavioral field contracts (every spoke reads only fields the schemas define)

bestest is a skill, not a CLI tool — see the callout under Why bestest? for how it runs inside your agent.

Alongside the prose spec, bestest ships a small deterministic helper (scripts/bestest-cli.py, stdlib-only Python) that the agent uses for mechanical operations — report selection (with companion-run filtering), config read/write/validate, concurrency locks, and metrics merges. It's optional: if python3 isn't available, the agent follows the documented manual steps instead. See references/bestest-cli.md.

MIT © 2025–2026 Prajwal Mishra and contributors