☕️ Classic, reliable, trusted test framework for Node.js and the browser
docs: agent instructions to help review agents (#5839)
Pelle Wessmanbadac5b16322
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdnew file mode 100644index 00000000..11292a6c--- /dev/null+++ b/.github/copilot-instructions.md@@ -0,0 +1,22 @@+# Copilot Instructions (Mocha)++For this repository, follow `AGENTS.md` in the repo root as the primary onboarding source.++## Priority rules++1. Trust `AGENTS.md` command ordering and runbooks first.+2. Keep edits minimal and semver-safe.+3. Never edit generated bundle artifacts (`mocha.js`, `mocha.js.map`) directly.+4. Validate with targeted tests first, then broader checks as needed.+5. Prefer repository `npm` scripts and workflow-defined commands over ad hoc shell pipelines.+6. If the current tool environment cannot edit files or run commands, provide copy-ready patch/command text and clearly mark validation as not run.++## Minimum validation checklist++- Build if browser path is involved: `npm run build`+- Typecheck when signatures/types may be impacted: `npm run tsc`+- Run at least one relevant test suite under `test/`+- Include browser test coverage when browser code/reporters are touched+- Only report checks you actually ran; if blocked, say so and include the exact blocker.++If your local results conflict with expectations, capture exact command output and reconcile with workflow scripts in `.github/workflows/mocha.yml` and `.github/workflows/npm-script.yml`.diff --git a/AGENTS.md b/AGENTS.mdnew file mode 100644index 00000000..8fe0b6d5--- /dev/null+++ b/AGENTS.md@@ -0,0 +1,145 @@+# 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.md` as the primary repository playbook for agent work.+- Use `.github/copilot-instructions.md` as the short compatibility layer for tools that prefer it.+- If prose and executable configuration disagree on command details, trust `package.json` scripts and `.github/workflows/*.yml`.+- Prefer repository `npm` scripts 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`, `_mocha`)+- `test/` — unit, integration, node-only, browser-specific, smoke+- `docs/` — Astro/Starlight docs app with separate lockfile/scripts+- `mocha.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.js` or `mocha.js.map` by hand.+- These are generated via `npm run build` (Rollup).+- `npm run clean` removes generated bundle artifacts.++## Verified command runbooks++Run from repository root unless noted.++### Bootstrap++1. `npm install`+2. (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)++1. `npm run clean`+2. `npm run build`+3. `npm run tsc`+4. `npm run test-smoke`+5. 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 reporters subset: `npm run test-browser:reporters: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-smoke` plus the closest `test-node:*` suite.+- Type/signature changes: `npm run tsc`.+- Workflow or script changes: mirror the affected `package.json` script or workflow job locally when practical.++### Full local gate (closest to CI intent)++1. `npm run format:check`+2. `npm run lint`+3. `npm run test-node`+4. `npm run test-browser`+5. `npm run tsc`++## Critical command-order gotchas++- Browser tests depend on built bundle artifacts.+ - If you run `clean`, you **must** run `build` before low-level browser runner commands.+ - `npm run test-browser-run` after `clean` (without build) can fail with "Cannot find module 'mocha'" in Karma.+- `test-browser` script is safer than calling `test-browser-run` directly because it includes `clean build`.++## CI parity notes++Main workflow: `.github/workflows/mocha.yml`++CI partitions checks into separate jobs:+- `format:check`+- `lint`+- `test-smoke` (Node 20/22/24)+- `test-node:*` matrix (interfaces/unit/integration/jsapi/requires/reporters/only)+- browser tests (`test-browser` with 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 upload via Codecov++## 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.++## Docs subsystem notes (`docs/`)++- Separate package and lockfile.+- Script chain in `docs/package.json`:+ - `generate` fetches supporter metadata/assets+ - `build` runs `astro check && astro build`+ - `docs` script 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.