Rstest monorepo

Rstest is an Rsbuild-based testing framework for JavaScript/TypeScript projects.

Sub-package Instructions

When working on code in a specific package, read that package's AGENTS.md file for package-specific guidelines:

• For @rstest/core: packages/core/AGENTS.md
• For @rstest/browser: packages/browser/AGENTS.md
• For @rstest/browser-ui: packages/browser-ui/AGENTS.md
• For @rstest/browser-react: packages/browser-react/AGENTS.md
• For @rstest/playwright: packages/playwright/AGENTS.md
• For @rstest/coverage-istanbul: packages/coverage-istanbul/AGENTS.md
• For @rstest/adapter-rslib: packages/adapter-rslib/AGENTS.md
• For @rstest/adapter-rsbuild: packages/adapter-rsbuild/AGENTS.md
• For @rstest/adapter-rspack: packages/adapter-rspack/AGENTS.md
• For documentation site: website/AGENTS.md

If a package does not have its own AGENTS.md, follow this root file and copy the closest local patterns.

pnpm check-harness-docs validates the package index and the command, path, and dependency claims written inside AGENTS.md/SKILL.md files.

Altitude rule: document only what the code cannot express — cross-boundary data flow, invariants, coupling points, pitfalls — phrased as constraints on future changes. No file inventories, no file:line references (the checker validates paths, not line numbers — line refs are undetectable drift); refer to symbols. A claim you cannot verify gets deleted, not hedged.

Monorepo structure

• packages/core/ — @rstest/core: core testing framework (CLI, runtime, reporter, pool)
• packages/browser/ — @rstest/browser: browser mode support (Playwright, WebSocket RPC)
• packages/browser-ui/ — @rstest/browser-ui: prebuilt browser container UI (React + Tailwind + Ant Design)
• packages/browser-react/ — @rstest/browser-react: React component testing utilities for browser mode
• packages/playwright/ — @rstest/playwright: Node-side Playwright browser automation fixtures
• packages/coverage-istanbul/ — @rstest/coverage-istanbul: Istanbul coverage provider
• packages/coverage-v8/ — @rstest/coverage-v8: V8 coverage provider
• packages/adapter-rslib/ — @rstest/adapter-rslib: Rslib configuration adapter
• packages/adapter-rsbuild/ — @rstest/adapter-rsbuild: Rsbuild configuration adapter
• packages/adapter-rspack/ — @rstest/adapter-rspack: Rspack configuration adapter
• benchmarks/ — benchmark projects and runners
• e2e/ — end-to-end integration tests
• examples/ — example projects (node, react, browser)
• website/ — documentation site (Rspress)
• scripts/ — build scripts and shared configs

Package manager and workspace

• Use pnpm (the version is pinned via the packageManager field in the root package.json).
• The workspace includes benchmarks, website, scripts/**, packages/**, examples/**, and e2e/**.
• Dependency installs use pnpm's stricter settings (minimumReleaseAge, strictDepBuilds, and explicit build-script approvals). Do not loosen these settings or add heavy dependencies without discussion.

Commands

# Root commands
pnpm install                  # Install all workspace dependencies
pnpm build                    # Build all packages under packages/*
pnpm test                     # Run unit tests via rstest
pnpm e2e                      # Run e2e tests
pnpm lint                     # Formatting + spell check + doc type sync + harness docs + lint/type check
pnpm lint:type                # Run rs lint --type-check (needs built package .d.ts)
pnpm typecheck                # Alias of lint:type
pnpm format                   # Format files, including heading case, via rs fmt
pnpm check-unused             # Run knip
pnpm test:examples            # Run example tests
pnpm bench:cpu                # Run CPU benchmarks
pnpm bench:memory             # Run memory benchmarks

# Package-specific examples
pnpm --filter @rstest/core build
pnpm --filter @rstest/core dev
pnpm --filter @rstest/core test
pnpm --filter @rstest/core test -- tests/core/rsbuild.test.ts

# File-scoped / faster feedback (from the repository root)
pnpm exec rs lint packages/core
pnpm rstest packages/core/tests/core/rsbuild.test.ts
pnpm exec rs fmt path/to/file.ts

Note: E2E tests and examples consume built package output. Rebuild affected packages before running them (for example, pnpm --filter @rstest/browser build). For testing workflows, use the testing skill.

Note: Run lint and type checks from the repository root so paths in rstack.config.mts resolve consistently. pnpm exec rs lint lints the repository; file arguments narrow lint diagnostics. pnpm typecheck also checks types across the configured projects and cannot be narrowed to a package.

Development workflow

• Before changing behavior, identify the affected package(s), public API/config impact, browser-mode impact, adapter impact, docs impact, and test scope.
• The editor integration is maintained in a separate repository, rstackjs/rstack-editor, which drives @rstest/core/api (createRstest, listTests, run, ListedTest, reporter events) from its own worker and maps Test Explorer actions to CLI flags. On main pushes that can change the built packages, .github/workflows/ecosystem-ci.yml dispatches rstackjs/rstack-ecosystem-ci, which builds @rstest/core from that commit and runs rstack-editor's test:unit and lint (rs lint --type-check) against it. It does not run rstack-editor's VS Code E2E; that runs in rstack-editor on the Renovate PR for each @rstest/core release. Both report a break only after the change has landed, so when a change touches that API surface, the CLI flags, or reporter output, open the matching change (or at least an issue) in rstack-editor in the same PR cycle and link both.
• Public API or config changes usually require docs updates.
• Behavioral changes require corresponding e2e coverage unless there is a clear reason existing coverage is sufficient.
• If a config option is shared with Rsbuild/Rslib/Rspack, check whether the adapters need to transform or pass it through consistently.
• Keep release-train versions separate from @rstest/core compatibility: packages compatible across releases must declare an explicit peer range starting at the oldest supported core version. Use a ranged workspace marker such as workspace:^ only temporarily when a package starts consuming an unreleased core capability. Packages that require an identical core version must use workspace:* so the published peer is exact.
• In every release: PR, replace temporary ranged workspace peer markers with the actual release range, confirm every @rstest/core peer accepts the new core version, and review ranges at each potentially breaking core boundary (each minor while core is 0.x, then each major from 1.x onward). Do not raise a package's lower bound when its core compatibility did not change, and do not widen an exact lockstep peer.
• Do not make repo-wide rewrites unless explicitly asked.
• Do not revert unrelated local changes.

Testing guidance

• For root-discovered unit tests, prefer pnpm rstest <package-test-path>.
• Do not pass e2e/... paths to the root pnpm rstest command.
• Run e2e tests from the e2e/ directory; when passing a path, strip the e2e/ prefix.
• Do not overlap pnpm build and pnpm e2e; wait for builds to finish before e2e.
• If e2e fails with missing built files, rebuild the affected package(s) before retrying.

Code style

• Use ESM-first: .mjs for runtime loaders, .ts/.mts for typed utilities.
• Do not mix CommonJS and ESM in the same module unless the file is intentionally a compatibility fixture.
• Use 2-space indentation and LF line endings.
• Use camelCase for locals, PascalCase for types/components, and SCREAMING_SNAKE_CASE for constants.
• Avoid namespace imports like import * as foo from 'foo' unless the module shape requires it.
• In-file TypeScript quality rules (restating comments, defensive checks, as/any, one-use abstractions, drift prevention) are owned by the typescript skill — apply it when writing .ts/.tsx/.mts files.

Skills

Available workflow skills in .agents/skills/: