testing

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

Running tests

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

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

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/.

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

To run tests in a fixture directory directly:

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:

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:

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.

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.
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.