Here is a jsdom test that passes. It mounts an Export button inside a toolbar styled to 48 pixels wide, forbids wrapping, and asserts that the label does not overflow. In Chromium the same code reports a content width of 82 pixels squeezed into a 44-pixel box. In jsdom both numbers are zero, and zero is less than or equal to zero.
\n\nThe opposite mistake is just as common and harder to see, because it is merely slow rather than wrong. A Playwright suite launches Chromium, Firefox and WebKit to check that \"Q3 Revenue / EMEA\" turns into q3-revenue-emea-2026-10-05.csv. Three browser launches to test a regular expression.
Both come from treating the runner as a preference. The useful question is narrower: where does the test code execute, and can it see the thing you are asserting from there?
\n\n@vitest/browser-playwright 5.0.2, Playwright 1.63.0, jsdom 30.1.1. Browser mode lost its experimental tag in Vitest 4.0, which also moved each provider into its own package and moved the context import from @vitest/browser/context to vitest/browser. Vitest 5 requires Node.js 22.12 or later and Vite 6.4 or later, and hands the WebdriverIO provider to the vitest-community organisation. The examples below were run against Vitest 5.0.2, jsdom 30.1.1 and Playwright 1.62.1 in Chromium.A Node process with no DOM. The default Vitest environment. It has more than people assume: Node ships a global Blob, marked no longer experimental since Node 18.0.0, so you can build the export payload and assert its type and bytes without any browser at all.
A Node process with a simulated DOM. Vitest's jsdom and happy-dom environments. The jsdom README lists two features as outside the project's scope. Layout, \"the ability to calculate where elements will be visually laid out as a result of CSS\", which affects getBoundingClientRect() and offsetTop. And navigation, the ability to replace the global object \"when clicking a link or assigning location.href\". For layout it returns \"zeros for many layout-related properties\". An anchor click that should start a download has nowhere to go.
Inside a real browser page. Vitest browser mode serves your test through Vite and runs it inside an iframe in a real browser, with input sent over the Chrome DevTools Protocol or WebDriver depending on the provider. Layout is real, focus is real, and URL.createObjectURL returns a URL the browser will actually resolve.
Outside the browser, driving it. A Playwright test runs in Node and controls the browser through its protocol, so it receives browser-level events: downloads, popups, dialogs, navigations.
\n\nThe asymmetry that decides most cases sits between the last two. Browser mode sees everything inside the page and nothing the browser does on the page's behalf. The Vitest commands documentation is explicit about where the outer page is: the page object on the server-side command context \"references the full page that contains the test iframe\", which is the orchestrator, and \"you most likely shouldn't touch it to not break things\". The download manager lives on the far side of that line.
The worked example is a report export. A button computes a filename, serialises rows, wraps them in a Blob and hands the browser an object URL through a temporary anchor:
\n\n// src/download-button.ts\nexport function triggerDownload(blob: Blob, filename: string): void {\n const url = URL.createObjectURL(blob)\n const link = document.createElement('a')\n link.href = url\n link.download = filename\n document.body.append(link)\n link.click()\n link.remove()\n setTimeout(() => URL.revokeObjectURL(url), 0)\n}mountExportButton wraps that in a button whose click calls exportFilename(reportName, format, now()), buildExport(rows, format) and then triggerDownload. The pure helpers live in their own module with no DOM imports. That split is the design decision that makes the rest cheap.
Everything that is a function of its inputs goes here, including the Blob, because Node has one:
\n\n// tests/export-file.unit.test.ts\nimport { describe, expect, test } from 'vitest'\nimport { buildExport, exportFilename, mimeFor, serialise } from '../src/export-file'\n\nconst at = new Date('2026-10-05T23:30:00Z')\n\ndescribe('exportFilename', () => {\n test.each([\n ['Q3 Revenue / EMEA', 'q3-revenue-emea-2026-10-05.csv'],\n ['Café Ørders', 'cafe-rders-2026-10-05.csv'],\n ['../../etc/passwd', 'etc-passwd-2026-10-05.csv'],\n ['***', 'export-2026-10-05.csv'],\n ])('%s -> %s', (name, expected) => {\n expect(exportFilename(name, 'csv', at)).toBe(expected)\n })\n})\n\ntest('CSV quoting survives commas, quotes and newlines', () => {\n expect(serialise([{ name: 'Smith, \"Jo\"', note: 'a\\nb' }], 'csv'))\n .toBe('name,note\\n\"Smith, \"\"Jo\"\"\",\"a\\nb\"')\n})\n\ntest('the Blob carries the MIME type and the bytes', async () => {\n const blob = buildExport([{ id: 1 }], 'json')\n expect(blob.type).toBe(mimeFor('json'))\n expect(JSON.parse(await blob.text())).toEqual([{ id: 1 }])\n})The filename table is where the edge cases belong, and it can grow to fifty rows at no cost. Notice the second row: Ø does not decompose under NFKD, so it is dropped rather than transliterated. If the slug pattern gets more involved, the Regex Tester is a quick way to try it against the awkward names before they become table rows.
Sanitising here is not optional polish. MDN's description of the download attribute says / and \\ are converted to underscores and that browsers \"will adjust the suggested name if necessary\" for characters a filesystem forbids. If you leave that to the browser, the name the user gets depends on which browser they use.
Run the two layers side by side with Vitest projects, the configuration shape the browser mode guide itself documents:
\n\n// vitest.config.ts\nimport { defineConfig } from 'vitest/config'\nimport { playwright } from '@vitest/browser-playwright'\n\nexport default defineConfig({\n test: {\n projects: [\n {\n test: {\n name: 'unit',\n environment: 'node',\n include: ['tests/**/*.unit.test.ts'],\n },\n },\n {\n test: {\n name: 'browser',\n include: ['tests/**/*.browser.test.ts'],\n browser: {\n enabled: true,\n provider: playwright(),\n headless: true,\n instances: [{ browser: 'chromium' }],\n },\n },\n },\n ],\n },\n})The browser test drives a real click, lets the real URL.createObjectURL run, and stops the download at the anchor so the test observes what the page handed over without the browser saving anything:
// tests/download-button.browser.test.ts\nimport { afterEach, expect, test, vi } from 'vitest'\nimport { page } from 'vitest/browser'\nimport { mountExportButton } from '../src/download-button'\n\nafterEach(() => {\n document.body.replaceChildren()\n vi.restoreAllMocks()\n})\n\ntest('a real click hands the browser a CSV blob under the computed name', async () => {\n const createUrl = vi.spyOn(URL, 'createObjectURL')\n const revokeUrl = vi.spyOn(URL, 'revokeObjectURL')\n\n let captured: { href: string; download: string } | undefined\n const stopDownload = (event: MouseEvent) => {\n const link = (event.target as Element).closest('a[download]') as HTMLAnchorElement | null\n if (!link) return\n captured = { href: link.href, download: link.download }\n event.preventDefault()\n }\n document.addEventListener('click', stopDownload, { capture: true })\n\n mountExportButton(document.body, {\n reportName: 'Q3 Revenue / EMEA',\n format: 'csv',\n getRows: () => [{ region: 'EMEA', total: 1200 }],\n now: () => new Date('2026-10-05T09:00:00Z'),\n })\n\n await page.getByRole('button', { name: 'Export CSV' }).click()\n\n expect(captured?.download).toBe('q3-revenue-emea-2026-10-05.csv')\n const blob = createUrl.mock.calls[0][0] as Blob\n const objectUrl = createUrl.mock.results[0].value as string\n expect(captured?.href).toBe(objectUrl)\n expect(blob.type).toBe('text/csv;charset=utf-8')\n expect(await blob.text()).toBe('region,total\\nEMEA,1200')\n\n await vi.waitFor(() => expect(revokeUrl).toHaveBeenCalledWith(objectUrl))\n await expect(fetch(objectUrl)).rejects.toThrow()\n\n document.removeEventListener('click', stopDownload, { capture: true })\n})Do not read the bytes by fetching captured.href after the click. It fails with TypeError: Failed to fetch: the click goes out to the provider and back before the promise resolves, and by then the zero-delay revoke timer has already fired. Read the Blob from the spy's arguments instead. Then turn the dead URL into an assertion: a fetch of a revoked object URL rejecting is proof that cleanup happened, and only a browser's own Blob URL store can give you that.
The choice of click matters too. The userEvent and locator methods from vitest/browser use CDP or WebDriver \"instead of faking events\". The guide recommends against @testing-library/user-event in browser mode for exactly this reason, and with the preview provider the same API \"fallbacks to simulated events\", which removes the point of being in a browser. Note also that in Vitest 5 locators match text exactly and case-sensitively by default, so 'Export CSV' will not match 'Export CSV file'.
Whether the browser actually treats that anchor as a download, and under what name, is not visible from inside the page. From outside it is one event:
\n\n// e2e/export.spec.ts\nimport { readFile } from 'node:fs/promises'\nimport { expect, test } from '@playwright/test'\n\ntest('the browser saves the export under the name the app chose', async ({ page }, testInfo) => {\n await page.goto('/reports/q3-emea')\n\n const downloadPromise = page.waitForEvent('download')\n await page.getByRole('button', { name: 'Export CSV' }).click()\n const download = await downloadPromise\n\n expect(download.suggestedFilename()).toBe('q3-revenue-emea-2026-10-05.csv')\n expect(await download.failure()).toBeNull()\n\n const target = testInfo.outputPath(download.suggestedFilename())\n await download.saveAs(target)\n expect(await readFile(target, 'utf8')).toContain('region,total')\n})Start waiting before the click; the Playwright docs mark the missing await on waitForEvent as deliberate. Save before the test ends, because \"downloaded files are deleted when the browser context that produced them is closed\", and note that download.path() returns a random GUID filename, so assert on suggestedFilename().
That method is the reason this layer exists. Its documentation says the name \"is typically computed by the browser from the Content-Disposition response header or the download attribute\" and that \"different browsers can use different logic for computing it\". Here is the first assertion in this article whose answer can differ by engine, so it is the first place a browser matrix earns its cost. It is also the test that notices if the export ever moves server-side, because MDN states that a filename in a Content-Disposition header \"takes priority over a filename specified in the download attribute\".
// playwright.config.ts\nimport { defineConfig, devices } from '@playwright/test'\n\nexport default defineConfig({\n use: { baseURL: 'http://localhost:4173', trace: 'on-first-retry' },\n projects: [\n { name: 'chromium', use: { ...devices['Desktop Chrome'] } },\n { name: 'firefox', use: { ...devices['Desktop Firefox'] } },\n { name: 'webkit', use: { ...devices['Desktop Safari'] } },\n ],\n})One test, against a deployed stack with real authentication and real data: a signed-in user opens a report that the server generated, exports it, and the file contains that report's rows. It catches what none of the layers above can, such as an authorisation rule that blanks the rows, or a reports API whose field names no longer match the columns the serialiser expects. It does not need the filename table, the quoting cases or three engines. Those already have homes.
\n\nRead each row as: if the assertion must observe the left column, the middle column is the cheapest layer that can, and the right column is what goes wrong one layer down.
\n\n| What the assertion must observe | Lowest sufficient layer | What the layer below gets wrong |
|---|---|---|
| Filename, MIME type, serialisation, Blob bytes | Vitest, node | Nothing below; a browser here only adds launch time |
| Rendered structure, accessible names, a click reaching its handler, disabled states | Vitest, jsdom or happy-dom | Node has no document, so you end up testing a hand-built fake |
Size, overflow, visibility, scroll position, anything read from getBoundingClientRect() | Vitest browser mode | jsdom returns zeros, so inequality assertions pass vacuously |
| Pointer, focus and keyboard behaviour; a live object URL and its revocation | Vitest browser mode with playwright | jsdom and the preview provider simulate events rather than dispatching real input |
| A download, popup, dialog or navigation the browser performs for the page | Playwright Test | Browser mode runs inside the test iframe and cannot see the browser's side of the transaction |
| An in-page API that behaves differently across engines | Browser mode with several instances | A single Chromium instance says nothing about Gecko or WebKit |
| A browser-level behaviour that differs across engines, such as the suggested download name | Playwright projects for each promised engine | Browser mode instances cannot observe the event at all |
| Server, auth, storage and browser agreeing on one outcome | One Playwright end-to-end test against a deployed stack | Every layer above stubs at least one of those parties |
Where the table leaves a genuine tie, usually a component that could run in jsdom or browser mode, default to browser mode if the component reads geometry, manages focus or creates object URLs, and to jsdom otherwise. Listing which browser APIs a component touches is mechanical work that a grep or an AI assistant does well. Deciding which of those behaviours you promise to users in which browsers is a product decision, and it has to come from whoever owns the supported-browser list.
\n\nThe opening test is the most common way this goes wrong, so here it is in full. In jsdom:
\n\n// @vitest-environment jsdom\ntest('export label fits a narrow toolbar', () => {\n const toolbar = document.createElement('div')\n toolbar.style.width = '48px'\n document.body.append(toolbar)\n const button = mountExportButton(toolbar, { reportName: 'Q3', format: 'csv', getRows: () => [] })\n button.style.whiteSpace = 'nowrap'\n button.style.overflow = 'hidden'\n button.style.maxWidth = '100%'\n\n // 0 <= 0: green at any toolbar width\n expect(button.scrollWidth).toBeLessThanOrEqual(button.clientWidth)\n})Moved to the browser project, with one extra line:
\n\n// tests/toolbar-fit.browser.test.ts\ntest.each([48, 160])('export label fits a %ipx toolbar', (width) => {\n // ...same setup...\n expect(button.clientWidth).toBeGreaterThan(0)\n expect(button.scrollWidth).toBeLessThanOrEqual(button.clientWidth)\n})\n// 48px fails: expected 82 to be less than or equal to 44\n// 160px passesThe toBeGreaterThan(0) guard is the part worth copying into every geometry test. If someone later moves the file into a jsdom project, it fails loudly instead of passing quietly. jsdom's README suggests overriding layout getters with Object.defineProperty() as a workaround. That makes the test pass on numbers you typed, which is a test of your fixture.
The other direction costs time, not correctness. A filename table in Playwright makes each row pay for a page, a navigation and a click to exercise code that never touches the browser, and reports failure as a mismatched download instead of a one-line diff. The Vitest documentation names its own overhead under drawbacks, as \"Longer Initialization\", because the provider and browser must start first. A Node test has none of that.
\n\nIf a transformation is only reachable through a click, extract it. Once exportFilename imports without a DOM, the browser tests shrink to one happy path each.
A Chromium-only suite proves the Chromium contract. That is often the right scope; reporting it as \"works in all browsers\" is the mistake.
\n\nThree documented facts limit what a WebKit or Firefox run can claim. Playwright's WebKit \"is derived from the latest WebKit main branch sources, often before these updates are incorporated into Apple Safari\", and Playwright \"doesn't work with the branded version of Safari since it relies on patches\". Its Firefox likewise tracks Firefox Stable but not the branded build. And platform matters: the same page notes that media codecs vary between Linux, macOS and Windows, and recommends running WebKit on macOS for the closest-to-Safari behaviour.
\n\nIf the supported-browser list says Safari by name and the behaviour is in-page, browser mode's WebdriverIO provider lists safari among its browsers, where Playwright offers webkit. Know what you are adopting: as of Vitest 5 that provider is community-maintained and \"addressed on a per-issue basis\".
When you do need several engines for in-page behaviour, prefer browser.instances over separate projects. The multiple-setups guide gives the reason: instances share one Vite server, so \"the file transform and dependency pre-bundling has to happen only once\".
Feedback time. Vitest's own benchmarks for the 5.0 release include one app measured both ways: the same 92-module React app took 1.07 seconds under jsdom (on the vmThreads pool) and 2.01 seconds in browser mode on Chromium. Roughly double, on a small app, before any cross-engine instances. That is cheap enough to use wherever the table says so, and too expensive to use where it does not.
CI install. The preview provider cannot run headless or in CI; the guide says CI needs playwright or webdriverio. Playwright's browsers page gives the disk bill as roughly 281 MB for Chromium, 187 MB for Firefox and 180 MB for WebKit, and each Playwright upgrade can need a fresh install. Two flags cut it down: npx playwright install --with-deps chromium installs one engine and its system packages, and --only-shell skips the full Chromium build when everything runs headless.
Diagnostic artefacts. A Node failure gives you a diff and a stack, which is usually all you need. Browser mode adds failure screenshots, written in Vitest 5 to .vitest/attachments/failure-screenshots/. It also adds the new browser.traceView DOM-snapshot replay, and Playwright trace files, which are \"only available when using the Playwright provider\". Playwright Test records a full trace per test, and the configuration it generates sets trace: 'on-first-retry' so the cost is paid only when something has already failed. Budget storage for the upper layers and nothing for the bottom one.
Pick the component with the slowest or flakiest tests. For each test, write down the one thing its assertion must observe, then look it up in the table. Move every test that sits above its row down to the lower layer, extracting a pure function where the logic is trapped behind a click.
\n\nThen search your jsdom projects for getBoundingClientRect, offsetWidth, clientWidth and scrollWidth. Each hit is either a mocked value or a vacuous pass. Move those tests to a browser project and add the greater-than-zero guard.
Capture two numbers before and after: wall-clock time for the component's full test run, and how many of its tests launch a browser. The first should fall. The second should match the number of rows in the table that the component actually needs.
\n\nNo, and the Vitest documentation says so under the heading \"Not a Drop-In Replacement\": it recommends pairing browser mode with a standalone runner such as Playwright. Browser mode is a component-testing layer in a real browser. Downloads, multiple pages, authentication state across navigations and deployed-stack journeys belong to a test that drives the browser from outside.
\n\nDo not count on it. Vitest describes happy-dom as faster than jsdom but lacking some APIs, and its Why Browser Mode page files jsdom and happy-dom together under the same simulation caveat. Choose between them on API coverage and speed for DOM-structure tests. For geometry, move to browser mode.
\n\nURL.createObjectURL in jsdom and stop there?You can, and the test will prove your code calls a function you wrote. It cannot prove the URL resolves to the right bytes or that revocation frees it, because a mock has no Blob URL store behind it.
\n\n\n@vitest/browser-playwright, @vitest/browser-preview), that CI requires playwright or webdriverio because preview \"relies on simulating events\", that headless is not available with preview, the projects configuration running a Node project beside a browser project, the browser lists per provider (safari under WebdriverIO, webkit under Playwright), tests running inside an iframe, the warning against @testing-library/user-event, and the limitation on thread-blocking dialogs. Vitest 5.0.2.browser.instances for Chromium, Firefox and WebKit, and that instances share one Vite server so transform and pre-bundling \"has to happen only once\".userEvent from vitest/browser uses CDP or WebDriver \"instead of faking events\".userEvent with the preview provider \"fallbacks to simulated events via @testing-library/user-event\".page \"references the full page that contains the test iframe\", the orchestrator, which \"you most likely shouldn't touch\".node, jsdom and happy-dom environments, happy-dom being \"considered to be faster than jsdom, but lacks some API\", the @vitest-environment control comment, and that browser is not an environment but a project.browser.traceView as a DOM-snapshot replay added in 5.0.0..vitest/attachments/failure-screenshots/, and the WebdriverIO provider moving to vitest-community, \"addressed on a per-issue basis\".@vitest/browser/context to vitest/browser.Object.defineProperty() workaround. jsdom 30.1.1.waitForEvent('download') pattern started before the click, and that \"downloaded files are deleted when the browser context that produced them is closed\".path() returning a GUID name, saveAs(), failure(), and that suggestedFilename() is browser-computed and \"different browsers can use different logic\".devices.--with-deps and --only-shell. Playwright 1.63.0.trace: 'on-first-retry' configuration.download attribute converting / and \\ to underscores, browsers adjusting names, working only for same-origin, blob: and data: URLs, and a Content-Disposition filename taking priority.Blob.type as the MIME type and Blob.text() for reading contents.