---
name: testing
description: Testing workflow for the Rstest monorepo. Use when running unit tests, e2e tests, browser e2e, example tests, watch-mode checks, writing test fixtures, debugging local or CI test failures, validating code changes, or reproducing bugs from external projects.
metadata:
  internal: true
---

# Testing Workflow

This skill owns the **mechanics**: how to run and write tests, fixtures, and builds. Whether a change needs test work is routed by the `development` skill; what counts as evidence that a change works is defined by the `verify` skill.

## Running tests

### Package/unit tests from repository root (single file — preferred)

```bash
pnpm rstest packages/core/tests/core/rsbuild.test.ts
```

Use this form for tests discovered by the root workspace config.
Do **not** pass `e2e/...` paths to the root `pnpm rstest` command.

### Package-level tests

```bash
pnpm --filter @rstest/core test
pnpm --filter @rstest/core test -- tests/core/rsbuild.test.ts  # single file
```

### E2E tests

Run e2e tests from inside the `e2e/` directory.
When passing the test path, strip the `e2e/` prefix because the working directory is already `e2e/`.

```bash
cd e2e && pnpm test <path-to-test>
```

To run tests in a fixture directory directly:

```bash
cd e2e/<test>/fixtures/<fixture>/ && npx rstest
```

## Rebuild before E2E

E2E tests and examples execute against **built package output**, not TypeScript sources. If you changed package source code, you **must rebuild** before running e2e:

```bash
pnpm --filter @rstest/core build    # or whichever package was changed
cd e2e && pnpm test <path>
```

Forgetting this step means e2e runs against stale output — a common source of false passes/failures.

When the change may affect multiple packages, prefer a full workspace package build first:

```bash
pnpm build
cd e2e && pnpm test <path>
```

Important:

- Do **not** start e2e while any package build is still running.
- Do **not** overlap `pnpm build` and `pnpm e2e` in separate sessions.
- Wait for the build command to exit successfully before starting e2e.
- If e2e fails immediately with a missing built file such as `packages/core/dist/rstestSuppressWarnings.cjs`, treat that as an incomplete build and rebuild before retrying.
- When unsure whether the build is fully finished, verify the expected artifact exists before running e2e.

## Browser E2E

- Fixtures default to `headless: true` — no browser windows locally
- Headed smoke tests are skipped locally by default (CI only)
- To opt in locally: `cd e2e && RSTEST_E2E_RUN_HEADED=true pnpm test browser-mode/basic.test.ts`

### Browser E2E debugging

- Rebuild affected packages before retrying; stale `dist` is a common false signal.
- Separate host/protocol/provider issues from UI issues before editing `@rstest/browser-ui`.
- For flakes, check shared ports/cwd, persistent `dist/.rstest-temp/`, unawaited events, and order-dependent state before increasing timeouts.

## Watch-mode and long-running tests

- Use watch-mode tests only for file-change/rerun/invalidation behavior.
- Assert stable events/final output, clean up watchers/processes, and inspect open handles before changing production code for hangs.

## Test behavior, not source shape

Protect runtime invariants at the narrowest existing interface that exposes their observable result. Use integration or E2E coverage for cross-module orchestration. Do not add a production seam or abstraction solely to make an isolated unit test possible; use fakes or spies only when the code already has a natural interface for them.

- Treat first-party implementation source text as private. Do not add tests that read it and use regexes, strings, snapshots, or counts to pin helper names, call sites, imports, or control-flow shape; comments, formatting, and behavior-preserving refactors make those assertions lie.
- Reading source is appropriate when that source is itself the runtime input under test, such as a raw injected module or a transform fixture. Inspecting emitted bundles and generated files as product outputs is also appropriate.

## Unit tests are OS-agnostic

CI runs unit tests (the `ut` job) on ubuntu only; OS-specific coverage lives in the e2e job's macOS/Windows rows. Enforced by the `rstest/os-agnostic-tests` rule in `rslint.config.mts` as part of `pnpm lint`; the rule itself is unit-tested by `scripts/lint/os-agnostic-rule.test.ts` (in the `lint` project).

- Do not write unit tests whose behavior or expectations depend on the host OS (reading `process.platform`, `os.platform()`, etc.). CI would only ever exercise the Linux branch.
- To cover platform-dependent code paths in a unit test, stub the platform for the test's duration so every branch runs deterministically on any host — see `withPlatform` in `packages/core/tests/core/related.test.ts`.
- If the behavior cannot be stubbed (real filesystem case-sensitivity, native binaries, shell differences), cover it in `e2e/` instead.

## Fixture strategy

Before adding a fixture, list existing ones in the same area (`ls e2e/<area>/fixtures`) and name the closest match. Prefer extending it:

- Adding a project, config flag, or test file is additive reuse — "different config" alone does not justify a new fixture. **After extending, re-run every test using that fixture** to confirm none broke.
- A new fixture is right when reuse would force an **incompatible** change to config other tests depend on, or contort the fixture's intent. Name the mechanism that blocks reuse; config expressible per file (environment docblocks, per-file options) does not make a difference incompatible.
- The same rule applies **inside** a fixture: before adding a test file or helper module, look for one whose structure already matches — same shared module, same peer-file pairing — and extend it instead. Adding exports to an existing helper, or cases to an existing test file, is additive reuse.
- Prefer **one consolidated regression fixture** that exercises the whole surface over many near-duplicate per-feature files. When several cases share a structural root cause, assert them together.

## E2E rstest spawns with persistent `dist/.rstest-temp/`

A fixture that enables `performance.buildCache` (or `dev.writeToDisk: true`) forces rstest to persist the built bundle under `<cwd>/dist/.rstest-temp/`. If sibling test files share that `cwd`, those persistent writes race against any test asserting on the default path. Other disk writers like coverage or blob reporters land in `<cwd>/coverage/` or `<cwd>/.rstest-reports/` — different surfaces, not covered by this rule.

When your fixture enables persistent build output:

- Set `cwd` to the fixture subdirectory, not the parent test directory.
- In that fixture's config, drop any `include` referencing paths outside the fixture (e.g. `'./fixtures/<name>/index.test.ts'`). Fixture-local globs like `'./*.test.ts'` are fine.
- Read `dist/.rstest-temp/` assertions from that isolated fixture dir, not from a shared parent.

## Snapshot policy

- Only update snapshots when the behavioral change is **intentional**
- For package/unit tests from repository root, use `-u` / `--update`: `pnpm rstest -u packages/core/tests/core/rsbuild.test.ts`
- Do **not** use snapshot updates as a default way to silence test failures — investigate first
- When updating, review the snapshot diff to confirm it matches expected changes

## External repro projects

For external repos/fixtures: read README/scripts/deps, reproduce with the smallest command, classify the source, then port only the minimal regression case into this repo.

## Performance and benchmark validation

For performance work, compare like-for-like runs: same command/fixture/env/cache policy, enough samples to separate noise, and state whether the result covers startup, execution, transform/cache, browser startup, or reporter overhead.

## Validation before wrapping up

- Do not stop at targeted tests only. Before finishing a code change, run the narrowest relevant tests first, then decide whether broader validation is needed.
- `pnpm run check-unused` is part of the default validation pass for code changes in this repo. Run it before wrapping up, even when focused tests already pass.
- Treat `check-unused` failures as real regressions unless you have confirmed the reported item is an intentional temporary state.