☕️ Classic, reliable, trusted test framework for Node.js and the browser
AGENTS.md
Agent onboarding for the mochajs/mocha repository.
Trust this file first. If you are unsure about command order, use the sequences below before trying alternatives.
Instruction precedence and execution defaults
- Use
AGENTS.mdas the primary repository playbook for agent work. - Use
.github/copilot-instructions.mdas the short compatibility layer for tools that prefer it. - If prose and executable configuration disagree on command details, trust
package.jsonscripts and.github/workflows/*.yml. - Prefer repository
npmscripts over ad hoc shell pipelines. - If the current tool environment cannot edit files or run commands, provide copy-ready patch/command text and clearly mark validation as not run.
Mission and scope
- Keep changes minimal and targeted.
- Preserve compatibility (Mocha is highly depended-upon and semver-sensitive).
- Never edit generated artifacts directly.
- Validate locally with the smallest command set that matches your change.
Environment prerequisites
- Node.js:
^20.19.0 || >=22.12.0(prefer Node 22 locally) - npm (do not use pnpm/yarn for this repo)
- Google Chrome (required for browser tests)
Repository map (quick)
lib/— core runtime (runner, suite, hooks, reporters, CLI internals)bin/— CLI entrypoints (mocha)test/— unit, integration, node-only, browser-specific, smokedocs/— Astro/Starlight docs app with separate lockfile/scriptsmocha.js/mocha.js.map— browser bundle outputs (generated).github/workflows/— CI job matrix and script partitioning
Generated files and do-not-edit rules
- Do not edit
mocha.jsormocha.js.mapby hand. - These are generated via
npm run build(Rollup). npm run cleanremoves generated bundle artifacts.
Verified command runbooks
Run from repository root unless noted.
Bootstrap
npm install- (Docs work only)
cd docs && npm install
For clean CI reproduction on a fresh checkout, prefer npm ci --ignore-scripts; use npm install for normal local bootstrap.
Fast sanity (recommended before/after focused edits)
npm run cleannpm run buildnpm run tscnpm run test-smoke- Targeted tests relevant to changed area (see below)
Targeted tests
- Unit/core:
npm run test-node:unit - Integration:
npm run test-node:integration - Interfaces:
npm run test-node:interfaces - Reporters:
npm run test-node:reporters - Browser subset:
npm run test-browser -- --grep bdd - Full browser path:
npm run test-browser(includes clean + build)
Validation routing
- Instruction/docs-only edits: no runtime checks required unless behavior claims changed.
- Browser or reporter changes:
npm run clean→npm run build→ browser validation. - CLI or node runtime changes:
npm run test-smokeplus the closesttest-node:*suite. - Type/signature changes:
npm run tsc. - Workflow or script changes: mirror the affected
package.jsonscript or workflow job locally when practical.
Full local gate (closest to CI intent)
npm run format:checknpm run lintnpm run test-nodenpm run test-browsernpm run tsc
Critical command-order gotchas
- Browser tests depend on built bundle artifacts.
- If you run
clean, you must runbuildbefore invokingplaywright testdirectly, or the page will 404 on/mocha.js.
- If you run
test-browserscript is safer than callingplaywright testdirectly because it includesclean build.
CI parity notes
Main workflow: .github/workflows/mocha.yml
CI partitions checks into separate jobs:
format:checklinttest-smoke(Node 20/22/24)test-node:*matrix (interfaces/unit/integration/jsapi/requires/reporters/only)- browser tests (
test-browserwith ChromeHeadless) tsc
Reusable execution details in .github/workflows/npm-script.yml:
- Uses
npm ci --ignore-scripts - Default Node 22 unless overridden
NODE_OPTIONS=--trace-warnings- Optional coverage report upload, combined by the
coveragejob inmocha.yml
Transient validation issues and environment drift
During onboarding or after dependency refresh, you may encounter validation failures that reflect local environment or ecosystem drift rather than a persistent repository bug.
Common patterns include:
- Lint commands (for example,
npm run lint:code) failing because new or stricter rules turn warnings into errors (such as via--max-warnings 0). Inspect the reported rule and location before changing lint configuration or adding suppressions. - Docs-related workflows where documentation generation succeeds but a subsequent static site or bundler step (for example,
astro build) fails with runtime errors originating in third-party dependencies.
Treat these as potential environment/version drift signals. Do not resolve them by broadly weakening checks (for example, relaxing lint strictness or skipping build steps) unless explicitly requested in the task.
Change strategy for agents
- Prefer smallest reproducible command to validate your specific edit first.
- Add/adjust tests with behavior changes; do not change unrelated tests.
- Avoid broad dependency upgrades unless task explicitly requests it.
- If touching browser behavior, always include at least one browser test run.
- If touching CLI or node runtime behavior, include smoke + targeted node suite.
CJS to ESM migration conventions (runtime code)
- Scope: prioritize runtime modules under
lib/; do not include test fixtures unless explicitly requested. - For ESM modules, prefer named exports over
export default. - When consuming ESM from CJS via
require(), import named bindings from the namespace object:- Use
const { SomeName } = require("./file.mjs"); - Avoid
require("./file.mjs").defaultfor runtime modules.
- Use
- Keep PRs small and reviewable (roughly <=100 changed lines when practical).
- After each migration slice, update all direct runtime call sites in the same PR to avoid mixed import patterns.
Docs subsystem notes (docs/)
- Separate package and lockfile.
- Script chain in
docs/package.json:generatefetches supporter metadata/assetsbuildrunsastro check && astro builddocsscript reinstalls root+docs deps, then generate+build
- Docs output can be very noisy (many supporter image fetch logs).
High-signal troubleshooting
- Never claim a check passed unless you actually ran it.
- If blocked, report the exact command, working directory, and first meaningful error.
- Missing Chrome / browser launch failures: ensure local Chrome installed and available.
- Browser path errors after cleanup: rerun
npm run build. - Strange lint failures after dependency changes: rerun on clean install (
npm ci), inspect warning-as-error output first. - Unexpected CI mismatch: mirror exact script from workflow rather than invoking custom command combinations.