development

# Feature / Bug-Fix Development Checklist This skill is a checklist of **guardrails** for feature and bug-fix work — reminders to catch missing work during development, then hand off to the more specific workflow when needed. The sections roughly follow a task's lifecycle for easy reading, but treat them as prompts to apply where relevant, not a rigid pipeline. ## Confirm Intent & Scope Decide what the task actually is before doing any work. - If the request is phrased as "review / verify / assess", treat it as **investigation** — report findings and confirm before implementing anything. - When the user enumerates a subset ("only the low items", "core field only", "先只加 skip"), implement exactly that subset and stop. - If a fix would span multiple clusters or packages, estimate file/PR size and confirm scope before writing code. Keep one PR per coherent seam. ## Build Verified Context Gather the real inputs and ground every claim in something you read **this session** — never answer from memory or impression. - For GitHub issues/PRs/checks/reviews, read the linked context before editing; do not implement from the title alone. - For external repros, reproduce with the smallest command first (workflow: `testing` → External repro projects). - Identify the smallest user-visible behavior, the affected package(s), and the validation path. - Behavioral, root-cause, version, or package-name claims must cite `path:line` — never answer from recall. - To answer "how does vitest/jest/rsbuild/rspack behave?", read the **latest upstream source, not the built `node_modules` dist**: if a local clone exists (e.g. `~/Projects/vitest`), bring it up to the latest default branch before reading (`git pull` — a `git fetch` alone leaves the working tree stale); otherwise shallow-clone fresh (vitest → `vitest-dev/vitest`; rsbuild/rspack → `web-infra-dev/{rsbuild,rspack}`; `npm view <pkg> repository` finds others). Prefer a subagent for the lookup. - If you cannot verify, say so explicitly instead of guessing. ## Map the Blast Radius Before writing code, determine what the change reaches: | Question | Action | | ----------------------------------------------- | ------------------------------------------------------ | | Which packages are touched? | List them (`@rstest/core`, `@rstest/browser`, etc.) | | Does it affect the public API or config schema? | If yes → docs update required | | Does it change behavior in Node mode? | If yes → unit tests + e2e required | | Does it change behavior in browser mode? | If yes → browser e2e required; see Browser Mode Impact | | Could it affect both Node and browser modes? | Evaluate both; see Browser Mode Impact | | Is the config option also present in Rsbuild? | If yes → adapter sync required; see Adapter Impact | ### Public API / Config / CLI Checklist For public API/config/CLI changes, check the full surface in one pass: 1. Canonical type/default/normalization/runtime consumer. 2. CLI flag/help/output/error text when applicable. 3. Adapters (`rsbuild`, `rslib`, `rspack`), browser mode, and docs (`en`, `zh`, `ApiMeta`) impact. 4. Unit tests for internals/transforms; e2e tests for user-facing behavior. ## Implement the Minimal Root-Cause Fix Make the smallest **design** change that resolves the root cause — this is where design-scope decisions belong. For in-file code quality (`any`/`as`, defensive checks, one-use abstractions, single source of truth, catch-and-rethrow), defer to the `typescript` skill rather than restating its rules here. - Fix at the single origin of the bug with the fewest lines. Find the one source, not N symptoms. - Do **not** add new config knobs, buffers, heuristics, timeouts, dependencies, abstractions, or mode-specific hacks (e.g. string-replacing the Rspack runtime) unless the user asks. Surface any such need as an explicit decision point or follow-up issue — never take the shortcut silently. - Before adding a top-level config option, prove the existing channel (`inlineConfig` / run params) cannot express it. - When aligning behavior with another tool, match the reference impl as the parity target — read its **source** (the latest upstream clone, per Build Verified Context), not the `node_modules` dist. Don't harden edges beyond it. ## Prove It Empirically Every behavioral change — feature or bug fix — must have a corresponding e2e test. Unit tests alone are not enough; e2e tests verify the full CLI → runner → reporter pipeline. Decide _whether_ test work is required here. For test layout, fixture strategy, rebuild requirements, and exact commands, switch to the `testing` skill. For what counts as **evidence** that the change works — forbidden proxy signals, per-change-shape observation standards — defer to the `verify` skill rather than restating its rules here. ### When Test Work Is Required - New feature or config behavior → add or extend an e2e test that exercises the user-facing flow. - Bug fix → add a regression test that fails before the fix and passes after it. - Internal refactor with no observable behavior change → evaluate whether existing coverage is enough, and note why if no new test is added. ### Bug-Fix Tests (Flip-and-Verify) Prove the repro both ways before claiming a fix: 1. Run the repro against `origin/main` (unfixed) → confirm it **fails**. 2. Run the same repro with your fix applied → confirm it **passes**. 3. Add the regression test that captures this delta. Never present a hypothesis as a conclusion — state confidence explicitly; "I believe" is not "verified". ## Browser Mode Impact Not every feature needs browser mode support, but you must **consciously decide** rather than ignore it. ### When Browser Mode Needs Changes - The feature touches test execution, module resolution, or runtime APIs → likely affects browser mode. - The feature adds a new config option → check if it should apply in browser mode too. - The feature modifies the reporter, CLI output, or test filtering → usually Node-only, but verify. ### When Browser Mode Does NOT Need Changes - Pure Node-specific features (e.g., `process.env` handling, Node module mocking). - Internal refactors that don't change the runtime contract. ### If Browser Mode Is Affected 1. Keep ownership clear: `@rstest/browser` = host/protocol/scheduling, `@rstest/browser-ui` = UI, runner/runtime = execution semantics, provider packages = provider behavior. 2. Update `packages/browser/` if the runtime behavior differs. 3. Add or update browser e2e coverage via the `testing` skill. 4. If the feature requires a new browser fixture, follow the pattern in `e2e/browser-mode/fixtures/`. 5. If the feature involves React component testing, check `@rstest/browser-react` as well. ### If Browser Mode Is Not Affected Add a brief note in the PR explaining **why** browser mode is unaffected, so reviewers don't have to ask. ## Adapter Impact If the new or changed configuration option also exists in Rsbuild, check whether the adapters (`@rstest/adapter-rsbuild`, `@rstest/adapter-rslib`) need to transform it. ### When Adapters Need Updates - The config option maps to an equivalent Rsbuild/Rslib config field → the adapter must translate it so users' existing Rsbuild configs work seamlessly. - A new rstest config is introduced that overlaps with Rsbuild concepts (e.g., resolve, output, source) → evaluate whether the adapter should auto-convert. ### Testing Adapters - If `@rstest/core` already has an e2e test covering the underlying feature, **do not duplicate it** in the adapter package. Prefer a **unit test** inside the adapter package (`packages/adapter-rsbuild/` or `packages/adapter-rslib/`) that verifies the config transformation logic. - Only add a separate adapter e2e test (`e2e/adapterTransformImport/`) when the transformation itself has complex behavior that unit tests cannot adequately cover. ### Adapter Docs - Update adapter-specific documentation when a new transform is added, so users know which Rsbuild configs are auto-converted. ## Keep Docs In Sync Documentation is not a follow-up task — it ships with the code. **Do not merge features without docs.** ### Route The Docs Work - Public API, config, CLI, or behavior changes usually require docs updates. - Treat this as the routing step: identify that docs must be updated, then inspect the existing docs structure under `website/docs/en/` and `website/docs/zh/` to edit the right pages. - If the change introduces a new docs surface or convention, follow the established structure in the surrounding guide/config/api pages instead of guessing a new location. ### Docs Conventions - Writing style, format, bilingual sync, and `ApiMeta` marker rules are owned by `website/AGENTS.md` — read it before editing docs rather than restating its rules here. - **Signature fidelity:** if you changed a public type in `packages/core/src/types/`, or edited a `**Type:**` / `**类型：**` block, run the `api-doc-sync` skill. The doc signatures are hand-written copies of the real types and drift silently (missing overloads, wrong arg order, en/zh divergence); `api-doc-sync` grounds them against source and `tsc`. ## Self-Check Before Committing Run through this before you consider the work done: - [ ] **Unit tests** cover the new/changed logic in the relevant package - [ ] **E2E test** covers the feature/fix end-to-end (see Prove It Empirically) - [ ] **Browser mode** impact evaluated — either updated or noted as unaffected - [ ] **Adapter sync** evaluated — config transforms updated or noted as N/A - [ ] **Docs** updated in both `en/` and `zh/` - [ ] **Public type surface matches docs** — TS declarations and `website/docs/{en,zh}` agree (e.g. `TestOptions.timeout?: number` is reflected for `describe`/`test`) - [ ] **Types** are correct — no new `any` leaking into public APIs (rule owned by the `typescript` skill) - [ ] **Unused exports / files checked** — run `pnpm run check-unused` before wrapping up (rule owned by the `testing` skill's validation pass) - [ ] **Build passes** — `pnpm --filter <package> build` succeeds - [ ] **Existing tests still pass** — `pnpm test` and relevant e2e tests green ## Handle Review Feedback by Redesign Review feedback arrives after you commit — resolve it by redesign, not more local patches. - When 2+ review comments hit the same code region or invariant, stop and assess for a single root-cause redesign before applying more local patches. - Flag any fix that creates the next finding (self-inflicted), and any field/option consumed only by tests — both are smells that the patch moved the bug rather than fixing it.