development

name	development
description	Feature and bug-fix development checklist for the Rstest monorepo. Use when implementing a new feature, fixing a bug, changing public APIs/config/CLI behavior, addressing a GitHub issue or PR request, or assessing cross-package impact before a PR.
metadata	{"internal":true}

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.