feat(adapters): add test framework adapters for node:test, Mocha, and AVA (#157)

Co-authored-by: Claude <[email protected]>

Author: boneskull

AGENTS.md

@@ -8,12 +8,16 @@ In Markdown text, refer to the name of this project as `**modestbench**` (bold)
 
 ### Git Workflow
 
-**Linear History Required:**
+**IF YOU ARE EXECUTING A PLAN, ALWAYS CREATE A NEW WORKTREE AND BRANCH**. Non-planned work can be done in the main branch / worktree. See [Feature Development with Worktrees](#feature-development-with-worktrees) for more details.
+
+#### Linear History Required
 
 - No merge commits - use `git rebase` or `git merge --ff-only`
 - If merge commits exist, use `git rebase -i` to eliminate them
 
-**Feature Development with Worktrees:**
+#### Feature Development with Worktrees
+
+**IF YOU ARE ALREADY IN A WORKTREE, YOU CAN SKIP THIS STEP**.
 
 ```bash
 # Create worktree INSIDE project directory
@@ -25,28 +29,28 @@ cd .worktrees/<feature-name>/
 # When done, see skills/collaboration/finishing-a-development-branch
 ```
 
-**Branch Naming:**
+#### Branch Naming
 
 - Use `feature/<descriptive-name>` (not `feat/`)
-- Worktrees go in `../modestbench.worktree/` directory
+- Worktrees go in `.worktrees/` directory
 
 ### Code Style
 
-**Testing:**
+#### Testing
 
 - Follow TDD principles (search your user rules for "test-driven development")
 - Contract tests in `test/contract/`
 - Integration tests in `test/integration/`
 - Use the wallaby MCP tools for runtime debugging
 
-**Architecture:**
+#### Architecture
 
 - Core engine: `src/core/engine.ts` - benchmark execution
 - CLI commands: `src/cli/commands/` - yargs-based CLI
 - Reporters: `src/reporters/` - output formats (human, json, csv)
 - Config: `src/config/` - configuration management with Zod
 
-**Key Principles:**
+#### Key Principles
 
 - Reporters: `--quiet` suppresses progress (stderr), not data output (stdout)
 - When no `--output` specified, data reporters write to stdout
@@ -59,19 +63,19 @@ cd .worktrees/<feature-name>/
    - Write tests first (TDD)
    - Keep functions focused (see `skills/coding/keeping-routines-focused`)
    - Name by domain (see `skills/coding/naming-by-domain`)
-3. **Testing:** Run `npm test` - aim for high coverage
-4. **Building:** `npm run build` before committing
-5. **Verification:** Check linter with `eslint` (see `skills/debugging/verification-before-completion`)
+3. **Linting:** Run `npm run fix` to fix linting errors (and report remaining errors)
+4. **Testing:** Run `npm test` - aim for high coverage (see `skills/debugging/verification-before-completion`)
+5. **Building:** `npm run build` before committing
 
 ### Common Patterns
 
-**CLI Options:**
+#### CLI Options
 
 - Use yargs for argument parsing
 - Options in `src/cli/commands/*.ts`
 - Types in `src/types/cli.ts`
 
-**Reporter Structure:**
+#### Reporter Structure
 
 ```typescript
 class MyReporter implements Reporter {
@@ -86,7 +90,7 @@ class MyReporter implements Reporter {
 }
 ```
 
-**Adding CLI Flags:**
+#### Adding CLI Flags
 
 1. Add to command definition in `src/cli/commands/run.ts`
 2. Add type to `src/types/cli.ts`
@@ -97,9 +101,15 @@ class MyReporter implements Reporter {
 
 - Source: `src/`
 - Tests: `test/` (contract and integration)
+- `tsd` (type) tests: `test-d/`
 - Built output: `dist/` (gitignored)
 - Examples: `examples/`
-- Docs: `README.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`
+- Documentation sources: `site/`, `public/`
+- Generated documentation: `docs/`
+- Important documentation files: `README.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`
+- Design reference: `assets/`
+- Reusable scripts: `scripts/`
+- Ad-hoc and temporary scripts: `.tmp/`
 
 ### External Dependencies
 

README.md

@@ -14,6 +14,7 @@
 - **Multiple Output Formats**: Human-readable, JSON, and CSV reports (at the same time!!)
 - **Historical Tracking**: Store and compare benchmark results over time
 - **Code Profiling & Analysis**: Identify hot code paths that need benchmarking using V8's built-in profiler
+- **Run Tests as Benchmarks**: Use your existing Mocha, AVA, or node:test tests as benchmarks
 - **Performance Budgets**: Enforce performance standards and prevent regressions
 - **CLI & API**: Command-line interface and programmatic API
 - **TypeScript Support**: Full type safety
@@ -403,6 +404,48 @@ The profile command uses Node.js's built-in V8 profiler to identify functions th
 
 Functions that appear at the top of the profile report are good candidates for benchmarking, as optimizing them will have the most impact on overall performance.
 
+### Run Tests as Benchmarks
+
+Already have test files? Run them as benchmarks without writing any new code:
+
+```bash
+# Run Mocha tests as benchmarks
+modestbench test mocha "test/*.spec.js"
+
+# Run node:test files as benchmarks
+modestbench test node-test "test/*.test.js"
+
+# Run AVA tests as benchmarks
+modestbench test ava "test/*.js"
+
+# With options
+modestbench test mocha "test/unit/*.spec.js" --iterations 500 --json
+```
+
+**Supported Frameworks:**
+
+- `mocha` - Mocha test files with `describe`/`it` syntax
+- `node-test` - Node.js built-in test runner (`node:test`)
+- `ava` - AVA test files
+
+**How It Works:**
+
+The `test` command captures test definitions from your test files and runs each test as a benchmark task. Test suites map to benchmark suites, and individual tests become benchmark tasks. Setup/teardown hooks (`beforeEach`/`afterEach`) are preserved and run with each iteration.
+
+This is useful for:
+
+- **Quick performance checks** - See how fast your tests actually run
+- **Regression detection** - Identify tests that have become slower
+- **Optimization targets** - Find slow tests that might benefit from optimization
+
+**Test Command Options:**
+
+- `--iterations`, `-i` - Number of iterations per test (default: 100)
+- `--warmup`, `-w` - Number of warmup iterations (default: 5)
+- `--bail`, `-b` - Stop on first failure
+- `--json` - Output results as JSON
+- `--quiet`, `-q` - Minimal output
+
 ## Configuration
 
 ### Project Configuration

cspell.json

@@ -71,7 +71,8 @@
     "asciinema",
     "pasqal",
     "illionth",
-    "gintacent"
+    "gintacent",
+    "nargs"
   ],
   "words": ["bupkis", "deoptimization"]
 }

package.json

@@ -26,11 +26,31 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./ava": {
+      "types": "./dist/adapters/ava-register.d.cts",
+      "import": "./dist/adapters/ava-register.js",
+      "require": "./dist/adapters/ava-register.cjs"
+    },
+    "./ava-hooks": {
+      "types": "./dist/adapters/ava-hooks.d.cts",
+      "import": "./dist/adapters/ava-hooks.js",
+      "require": "./dist/adapters/ava-hooks.cjs"
+    },
     "./cli": {
       "types": "./dist/cli/index.d.cts",
       "import": "./dist/cli/index.js",
       "require": "./dist/cli/index.cjs"
     },
+    "./node-test": {
+      "types": "./dist/adapters/node-test-register.d.cts",
+      "import": "./dist/adapters/node-test-register.js",
+      "require": "./dist/adapters/node-test-register.cjs"
+    },
+    "./node-test-hooks": {
+      "types": "./dist/adapters/node-test-hooks.d.cts",
+      "import": "./dist/adapters/node-test-hooks.js",
+      "require": "./dist/adapters/node-test-hooks.cjs"
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -171,7 +191,9 @@
         "src/index.ts",
         "src/cli/index.ts",
         "examples/**/*.ts",
-        "examples/**/*.js"
+        "examples/**/*.js",
+        "src/adapters/*-hooks.ts",
+        "src/adapters/*-register.ts"
       ]
     }
   },
@@ -211,7 +233,11 @@
     "bin": "./src/cli/index.ts",
     "exports": {
       ".": "./src/index.ts",
+      "./ava": "./src/adapters/ava-register.ts",
+      "./ava-hooks": "./src/adapters/ava-hooks.ts",
       "./cli": "./src/cli/index.ts",
+      "./node-test": "./src/adapters/node-test-register.ts",
+      "./node-test-hooks": "./src/adapters/node-test-hooks.ts",
       "./package.json": "./package.json"
     }
   }

site/src/content/docs/guides/cli.md

@@ -448,6 +448,126 @@ The profiler displays results with color-coded percentages:
 See the [Profiling Guide](/guides/profiling/) for detailed workflows, best practices, and programmatic usage.
 :::
 
+### `modestbench test`
+
+Run existing test files as benchmarks. Captures test definitions from Mocha, node:test, or AVA test files and executes them as benchmark tasks.
+
+```bash
+# Run Mocha tests as benchmarks
+modestbench test mocha "test/*.spec.js"
+
+# Run node:test files as benchmarks
+modestbench test node-test "test/*.test.js"
+
+# Run AVA tests as benchmarks
+modestbench test ava "test/*.js"
+
+# Multiple patterns
+modestbench test mocha "test/unit/*.spec.js" "test/integration/*.spec.js"
+```
+
+#### Supported Frameworks
+
+- **`mocha`** - Mocha test files using `describe`/`it` syntax
+- **`node-test`** - Node.js built-in test runner (`node:test` module)
+- **`ava`** - AVA test files
+
+#### Test Command Options
+
+##### `<framework>` (required)
+
+The test framework to use. Must be one of: `mocha`, `node-test`, `ava`.
+
+##### `[files..]`
+
+Test file paths or glob patterns.
+
+```bash
+modestbench test mocha "test/**/*.spec.js"
+```
+
+##### `--iterations <number>`, `-i <number>`
+
+Number of iterations per test (default: 100).
+
+```bash
+modestbench test mocha test/*.spec.js --iterations 500
+```
+
+##### `--warmup <number>`, `-w <number>`
+
+Number of warmup iterations before measurement (default: 5).
+
+```bash
+modestbench test mocha test/*.spec.js --warmup 10
+```
+
+##### `--bail`, `-b`
+
+Stop on first failure.
+
+```bash
+modestbench test mocha test/*.spec.js --bail
+```
+
+##### `--json`
+
+Output results in JSON format.
+
+```bash
+modestbench test mocha test/*.spec.js --json
+```
+
+##### `--quiet`, `-q`
+
+Minimal output mode.
+
+```bash
+modestbench test mocha test/*.spec.js --quiet
+```
+
+#### How It Works
+
+The `test` command:
+
+1. **Captures** test definitions by intercepting the test framework's API
+2. **Converts** test suites to benchmark suites and tests to benchmark tasks
+3. **Preserves** setup/teardown hooks (`beforeEach`/`afterEach`)
+4. **Executes** each test multiple times to collect timing statistics
+
+Test hierarchy is preserved: `describe` blocks become benchmark suites, `it`/`test` blocks become benchmark tasks.
+
+#### Use Cases
+
+- **Quick performance checks** - See how fast your tests actually run
+- **Regression detection** - Identify tests that have become slower over time
+- **Optimization targets** - Find slow tests that might benefit from optimization
+- **CI integration** - Add performance metrics to your test pipeline
+
+#### Test Command Examples
+
+```bash
+# Basic Mocha benchmarking
+modestbench test mocha "test/*.spec.js"
+
+# node:test with more iterations
+modestbench test node-test "test/*.test.js" --iterations 500
+
+# AVA with JSON output for CI
+modestbench test ava "test/*.js" --json --quiet
+
+# Stop on first slow test
+modestbench test mocha "test/unit/*.spec.js" --bail
+```
+
+:::tip[Framework Loader]
+For the test command to intercept imports correctly, modestbench uses ES module loader hooks. This happens automatically when you use the `test` command.
+:::
+
+:::note[Learn More]
+See the [Running Tests as Benchmarks](/guides/test-adapters/) guide for detailed workflows, framework-specific examples, and best practices.
+:::
+
 ### `modestbench history`
 
 Manage benchmark history and compare results over time.