Testing

Astro has three test infrastructures running in parallel: legacy mocha, the newer node:test runner accessed via astro-scripts test, and Playwright-based end-to-end tests. Knowing which to reach for is half the battle.

Test runners by package

Runner	Used by	Entry script
mocha	Most existing tests in packages/astro/test/	pnpm -C packages/astro test
node:test via astro-scripts test	Newer tests across packages	pnpm -C <pkg> exec astro-scripts test
Playwright	packages/astro/e2e/	pnpm run test:e2e
Vitest	examples/with-vitest, examples/container-with-vitest	pnpm -C <example> test

The migration from mocha to node:test is in progress. New tests should prefer node:test.

Running tests

# Full suite — slow
pnpm run test

# Match by name
pnpm run test:match "cli"
pnpm --filter @astrojs/rss run test

# Inside a single package
pnpm -C packages/astro test
pnpm -C packages/astro test:match "cli"
pnpm -C packages/astro exec astro-scripts test "test/actions.test.js"
pnpm -C packages/astro exec astro-scripts test "test/**/*.test.js" --match "CSS"
pnpm -C packages/astro exec astro-scripts test "test/{actions,css,middleware}.test.js"

# Single test file with raw node
node --test ./test/foo.test.js

# Single it() — first add .only, then:
node --test --test-only test/astro-basic.test.js

astro-scripts test flags:

• --match / -m — filter by name (regex)
• --only / -o — run only .only tests
• --parallel / -p — parallel mode (sequential is default)
• --timeout / -t — per-test timeout in ms
• --watch / -w — re-run on file change

Source: scripts/cmd/test.js.

End-to-end tests

packages/astro/e2e/ hosts Playwright tests for HMR, hydration, view transitions, and other "must run in a real browser" scenarios. From CONTRIBUTING.md:

Any tests for astro build output should use the main mocha tests rather than E2E. If a test needs to validate what happens on the page after it's loaded in the browser, that's a perfect use for E2E.

pnpm run test:e2e                       # all e2e
pnpm run test:e2e:match "Tailwind CSS"

Playwright Firefox is installed lazily (pnpm playwright install firefox is part of these scripts). Configs:

• packages/astro/playwright.config.js
• packages/astro/playwright.firefox.config.js

Fixtures

packages/astro/test/test-utils.ts exports loadFixture(), which boots a real Astro project with a custom config:

const fixture = await loadFixture({
  root: './fixtures/some-fixture',
  outDir: './dist/some-folder',
});

If tests start to fail for no apparent reason, the first thing to look at is the outDir configuration. As build caches artifacts between runs, different tests might end up sharing some of the emitted modules. To avoid this possible overlap, make sure to add a custom outDir to your test case. — CONTRIBUTING.md

The fixture exposes build(), startDevServer(), fetch(), and readFile() for assertions. There is also loadFixture exposed via astro/_internal/test/test-utils for use in integration packages.

Test fixtures by package

• packages/astro/test/fixtures/ — shared fixtures for the framework tests.
• packages/astro/test/units/ — pure unit tests that do not boot a fixture.
• packages/astro/test/units/_temp-fixtures/ — opt-in scratch space (linked in pnpm-workspace.yaml).
• packages/integrations/<name>/test/fixtures/ — per-integration fixtures.
• packages/db/test/fixtures/, packages/create-astro/test/fixtures/, etc.

Type tests

pnpm run test:types          # tsc --noEmit on packages/astro/test/types

Implemented as .test-d.ts files. The runner is the standard TypeScript compiler in pnpm -C packages/astro test:types.

Smoke tests

pnpm run test:smoke           # build all examples and the docs site
pnpm run test:check-examples  # verify examples conform to the smoke shape

scripts/smoke/check.js enforces a minimal shape across examples/.

Debugging flaky CI tests

When tests time out only in CI, CONTRIBUTING.md recommends temporarily adding --parallel to the package's test script and pushing to find the offending file:

- "test": "astro-scripts test \"test/**/*.test.js\""
+ "test": "astro-scripts test --parallel \"test/**/*.test.js\""

Revert before merging.

Related pages

• Patterns and conventions
• Debugging
• Tooling