CurlShot: testing a screenshot API with Vitest (unit suite + real-Chromium engine suite)

[SergiuPogor]

Sharing a Vitest setup from a production project: two suites, one fast and one that drives real browsers.

CurlShot is a screenshot API (URL, HTML or Markdown in; PNG, JPEG, WebP, PDF or scrolling video out, rendered in headless Chromium). Everything is tested with Vitest:

1. Unit suite (npm test) — about 150 test files under tests/unit, environment: 'node', pool: 'forks'. A setup file deletes every env var that could send a message or charge money (alert bot tokens, Sentry DSN) and sets deterministic secrets, so a unit test can never reach a real service. Tests that need Postgres or Redis must mock them. Route handlers log expected failures on negative-path tests, so onConsoleLog drops console output unless VITEST_VERBOSE=1 is set. JSX is compiled through the oxc option so tests can render real .tsx components even though Next.js keeps jsx: preserve in tsconfig.

2. Engine suite (separate config) — npx vitest run --config tests/engine/vitest.config.ts. It spawns real renderer processes with real Chromium, Redis and Postgres, and talks to them the way the web tier does. Key settings: fileParallelism: false (each file starts its own renderers and browsers), testTimeout: 60_000, hookTimeout: 120_000. A local fixture HTTP server counts every request and records headers, so a test can prove a request was or was not made (for example that blocked trackers were never fetched).

One test I like: a fuzz test that takes every option value the parser accepts and sends it to a real renderer. The answer must be an image or a deliberate error code, never a 500 and never a dead renderer process.

Thanks to the Vitest team. Running both kinds of suites with one tool and two configs kept things simple.