Environments

describe-me records in Vitest browser mode and in DOM environments such as jsdom. The frames are the same kind of thing in both. What differs is what happens inside the test.

How the plugin picks one #

The plugin reads test.browser.enabled from the Vitest config it receives. When it is set, the plugin wires browser mode. Otherwise it wires a DOM environment. The environment option wins over that check.

If you switch browser mode on some other way, so that the config the plugin receives has no test.browser.enabled, say so:

vitest.config.ts

import { describeMe } from '@describe-me/vitest/plugin'

describeMe({ environment: 'browser' })

What the plugin changes lists every config change in full. The redirect matches the exact module name only. Other ways to mount, such as vitest-browser-react/pure, record no render frame, as Tests that are left out explains.

Browser mode #

• render is async, like the one from vitest-browser-react. await render(…) records a frame after mount, and await screen.rerender(…) records another.
• Every Locator action, such as locator.click() or locator.fill(), records one frame. So does every keyboard-level userEvent method from vitest/browser, such as userEvent.type() or userEvent.keyboard().
• userEvent.click(element) hands the work to locator.click() and still records one frame, not two.
• Each capture waits one settle first: a single setTimeout(0) on real timers, which lets React commit its updates.

The typing frame of SearchBox comes from userEvent.type(). What records a frame lists every method. A frame holds the DOM and its stylesheets, not pixels, as What a frame captures explains.

jsdom #

Installation lists the packages and Getting started shows the config. Your tests stay as they are. This is what changes, and what does not.

Rendering

• render stays synchronous, so const { asFragment } = render(…) keeps working.
• The redirect also reaches a custom render in your own test-utils, because that file imports @testing-library/react itself. A test that renders through test-utils records like any other.
• render, rerender and fireEvent take their frame at once, without settling. Testing Library wraps them in act(), so the DOM is committed when they return. The fireEvent frame of Disclosure is one of them.
• @testing-library/user-event frames are taken as soon as the call resolves, with @testing-library/react loaded. Testing Library runs each event in act() and drains a macrotask before the call returns, so the frame shows the page as the test's next line sees it. See the click through a setup instance. Without @testing-library/react, user-event frames wait one settle, as in browser mode.
• The plugin turns on test.css unless you set it, so imported stylesheets reach the snapshots. What the plugin changes has the details.

Cleanup

• Testing Library's auto-cleanup is off. describe-me unmounts after every test instead, once the closing frame is taken.
• renderHook records no frames, but its tree is unmounted after each test too.
• afterEach(cleanup) in a test file is safe. cleanup takes the closing frame, then unmounts.

Timers and act

• Fake timers are safe. The recorder keeps the real setTimeout, so vi.useFakeTimers() left on never hangs a capture. The closing frame of the Toast timer test comes from a file with fake timers and afterEach(cleanup).
• With auto-cleanup off, Testing Library also skips setting React's IS_REACT_ACT_ENVIRONMENT flag. The setup file sets it where Testing Library would, which is only with Vitest globals (globals: true).
• With @testing-library/react, render, fireEvent and user-event frames add no wait, so React's act warnings match a run without describe-me.
• The recorder still waits one macrotask, with the flag off as in Testing Library's waitFor, in four places:
  • at the end of a test that still holds back a lazy or { pending } render frame
  • before the closing frame that the recorder takes after the test
  • after a step()
  • after a user-event call without @testing-library/react
  An update that lands in one of these waits can warn differently than without describe-me, in either direction.

Packages

• @testing-library/user-event is optional. Without it, there is nothing to patch and nothing fails.
• The plugin treats every environment other than browser mode as a DOM, but only jsdom is tested. happy-dom is untested.

Limitations in jsdom #

jsdom has no layout engine and loads nothing, so what differs is what happens inside the test. The frames are DOM plus stylesheets in both environments, and a real browser lays them out in the viewer.

Positioned popovers

Tooltips, menus and dropdowns placed by floating-ui, Popper, Radix and similar libraries show up in the top-left corner. The library computes the position from getBoundingClientRect(), which returns zeros in jsdom, and writes it into the DOM as top and left or a transform. The viewer replays those numbers.

Layout, scrolling and observers

Anything the test measures, scrolls or observes behaves differently. getBoundingClientRect() returns zeros, and user-event cannot tell whether another element covers the one it clicks. jsdom has no ResizeObserver or IntersectionObserver unless the test stubs them. Record tests that depend on layout in browser mode.

Fonts in the test

Web fonts never load during a jsdom test, so the test measures text in fallback fonts. The viewer shows the real ones, as Fonts explains. Postcard in browser mode and Postcard in jsdom look the same, although the jsdom test never loaded its Lora caption font.

A stylesheet <link> that a font loader adds never loads either. Each capture makes rrweb-snapshot set a 5 s timer for such a link. The timer does nothing when it fires, and the capture does not wait for it.

Constructable stylesheets

jsdom cannot fill a stylesheet built with new CSSStyleSheet(), so styles added through adoptedStyleSheets are missing in the test and in the frame. The adoptedStyleSheets line of StyledText in browser mode is orange, and in StyledText in jsdom it is not. Record components that adopt stylesheets in browser mode.

Canvas

Without the canvas package, getContext() returns null in jsdom, so the test cannot draw. Snapshots hold no canvas pixels in either environment, so a <canvas> is blank in the viewer.

fireEvent inside your own act()

fireEvent records its frame as soon as it returns. Inside an act() of your own, React flushes only when that act() ends, so the frame shows the DOM from before the update.

Limits in both environments #

Concurrent tests are never recorded. Tests that run concurrently, through test.concurrent, describe.concurrent or sequence.concurrent, would share one recorder. They run and report as usual, and the setup file warns once per test file:

describe-me: concurrent tests are not recorded (src/Menu.test.tsx)

Hover and focus are recorded. Each frame records which elements were in :hover, :focus, :focus-visible and :focus-within, and the viewer replays their rules, as in the frame of a ghost button on hover.

• Both environments. :focus is the focused element, and :focus-within is that element and its ancestors.
• Browser mode. The browser decides :focus-visible and :hover. A hover shows only while hover() is the test's last pointer gesture, because a click leaves the pointer over its target.
• DOM environments.
  • hover() and fireEvent.mouseEnter, mouseOver, pointerEnter and pointerOver hover the element and its ancestors.
  • unhover(), fireEvent.mouseLeave, mouseOut, pointerLeave and pointerOut, and click, dblClick, tripleClick and pointer end it.
  • :focus-visible goes to a focused text field, which is a text input, a textarea or a contenteditable element, and to any focused element after tab, keyboard or type, until the next click, dblClick, tripleClick or pointer.
• Not recorded. :active, and a hover your own code fakes, for example with dispatchEvent(new MouseEvent('mouseover')). The frame shows only what such code changed in the DOM.
• Live mounts the real component, so its hover and focus follow your own pointer and keyboard.

Which one to use #

The frames look alike either way, because the viewer lays them out in a real browser. The difference is inside the test, as Limitations in jsdom lists. Live mounts a jsdom test in the viewer's browser too, with real layout and web fonts.

Using both

This repository keeps the two apart. Each of its example projects runs one environment, with its own Vitest config and its own .describe-me/.

In one project, give each config its own outDir, then open each output with its own viewer:

vitest.jsdom.config.ts

import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react'
import { describeMe } from '@describe-me/vitest/plugin'

export default defineConfig({
  plugins: [react(), describeMe({ outDir: '.describe-me-jsdom' })],
  test: { environment: 'jsdom' },
})

pnpm vitest run --config vitest.jsdom.config.ts
pnpm describe-me dev --data .describe-me-jsdom

One run with a browser project and a jsdom project in test.projects is not tested. Inline jsdom projects are, by pnpm check-projects. Monorepos covers how test.projects paths reach describe-me.