# jest-preview: rendering Jest test output in a browser

> jest-preview renders the HTML your Jest assertions run against into a live browser view. It solves a narrow, real problem: debugging DOM-heavy component tests by reading serialized markup.

**nvh95/jest-preview** — Debug your Jest tests. Effortlessly.🛠🖼 

- Repository: https://github.com/nvh95/jest-preview
- Website: https://www.jest-preview.com
- Stars: 2,389 · Forks: 81
- Language: TypeScript
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/nvh95-jest-preview

## The problem jest-preview targets

Component tests fail in a way that is hard to read. Jest prints a DOM tree, and for anything past a handful of nested elements that tree stops being a picture of a UI and becomes a wall of attributes. The README states the motivation plainly: when writing tests with Jest, developers usually debug by reading the HTML code, and sometimes the HTML is too complicated to visualize in the head. jest-preview exists to close that gap by rendering the same HTML in a browser window.

The intended audience is narrow and specific. The README says the package was initially designed to work with Jest and react-testing-library, and that it is framework-agnostic, usable with any frontend framework and testing library. The examples directory in the repository lists Vite React, Create React App, Next.js, Svelte, Angular and Vue. If your tests never render anything, this tool has nothing to show you. If they render a component tree and you have ever pasted a failing DOM snapshot into a file to look at it, that is the workflow it replaces.

## How the preview mechanism works

The repository ships a file named HOW_JEST_PREVIEW_WORKS.md at the top level, which is the place to look for the architecture rather than the README. The README itself describes the user-facing half: a CLI named jest-preview starts a server, and calling preview.debug() inside a test pushes the rendered HTML to that server, which auto reloads the browser. So the loop is test process to server to browser tab.

The other half is Jest's transform configuration. The README's feature list points at a step titled "Configure Jest's transform to intercept CSS and files", which implies that jest-preview installs a transform that catches CSS imports and asset imports during the test run and hands them to the preview server instead of letting Jest choke on them. That is why the feature list can claim support for direct CSS imports, CSS Modules, Sass, Less, global CSS, and CSS-in-JS libraries such as styled-components and Emotion. It also explains the advanced configuration page for custom code transformation: if you already have your own transform chain, the pre-configured one has to be merged with it rather than used as-is.

The design is deliberately unidirectional. Tests push HTML out; the browser displays it. There is no documented channel for the browser to drive the test, so this is a viewer, not an interactive debugger.

## Installing jest-preview and running a first preview

The README does not inline the install commands; it links to an Installation Guide on the project site at jest-preview.com. What the README does give is the two-line usage pattern and the requirement that the server be running. Install the package from npm as a dev dependency, then start the CLI in one terminal.

```bash
npm install --save-dev jest-preview
npx jest-preview
```

The CLI opens a server and a browser tab. Leave it running. In a second terminal, add the debug call to a test that already renders something.

```ts
import preview from 'jest-preview';

describe('App', () => {
  it('should work as expected', () => {
    render(<App />);
    preview.debug();
  });
});
```

Run that test with Jest as usual. According to the README, executing preview.debug() triggers an automatic browser reload, so the tab you left open should repaint with the rendered output of that test. The README notes an alternative import of a bare debug function if you prefer not to keep a default import around.

The part the README does not spell out is the Jest transform step, and it matters. Without configuring Jest's transform, CSS and file imports will not be intercepted, and the preview will show unstyled markup. The feature list is explicit that CSS support depends on that configuration step, so treat it as required rather than optional if your components import stylesheets.

## Where jest-preview stops being the right tool

This is a viewer bolted onto Jest, and several things follow from that.

First, it only shows what a test rendered. If a failure comes from a network response, a timer, or a state transition that never happens, the preview shows the DOM at the moment debug() was called and nothing about why. You still need console output or a real debugger for that.

Second, the README lists multiple previews under upcoming features, which means the current release does not document a way to hold several rendered states side by side. Comparing an empty state against a populated state means running the test twice.

Third, the server is a local development aid. Nothing in the documentation describes a CI mode, and the package's own test script runs the server and the test watcher together with npm-run-all, which is a local workflow shape. Wiring a long-running preview server into a headless pipeline is not something the documentation supports.

Fourth, CSS-in-JS support is enumerated rather than general. The README says a number of libraries are supported and lists styled-components and Emotion. If your styling library is not on that list, the README does not promise it will work, and the upcoming features list names support for more CSS-in-JS libraries as unfinished work. Check your library against the list before assuming the preview will look right.

## jest-preview against Playwright and Vitest Preview

The closest conceptual alternative is a browser automation tool such as Playwright. The difference is where the test runs. Playwright drives a real browser, so the page under test is a real page, with real layout, real network requests and real event handling. jest-preview runs inside Jest with jsdom-style rendering and forwards the resulting HTML to a browser for display. That means the preview is a picture of the DOM your assertions see, not a picture of a browser rendering that DOM. Layout that depends on real measurement, or behavior that depends on a real event loop, will not appear in the preview. In exchange, jest-preview adds nothing to your test runtime model: your tests stay Jest tests, and you do not maintain a second browser-driven suite.

Vitest Preview is the same author's equivalent for Vitest, linked directly from the README. If your project has already moved to Vitest, that is the package to look at, because jest-preview's transform configuration is written for Jest. The two are not interchangeable configurations; the test runner is the integration point.

## Maintenance, upgrades and the MIT licence

The repository is not archived and the last push was on 2026-04-25. The most recent release, v0.3.3, was published on 2025-12-14, following v0.3.2 on 2025-09-07. Before that, v0.3.1 landed on 2022-08-30 with support for Less CSS. That gap is worth noting when you plan upgrades: this is a small package with an irregular release rhythm, so pin the version in package.json rather than tracking a range if you need predictable behavior in a shared test setup.

The version number is still 0.x, which in npm convention signals that breaking changes can arrive in minor releases. Because jest-preview hooks into Jest's transform pipeline, a breaking change there can surface as failing tests rather than as a visible error in the preview. Read CHANGELOG.md before bumping.

The package is MIT-licensed. For most teams that is the least restrictive of the common options: it permits commercial use and modification, and it requires that the licence text and copyright notice travel with redistributed copies. If you vendor the transform files into an internal package, keep the notice. That is a description of the licence terms, not legal advice for your situation.

## Conclusion

Adopt jest-preview if your team writes Jest tests with react-testing-library or another DOM-based library and regularly debugs failures by reading serialized HTML. Skip it if your tests are mostly unit-level logic with no rendered output, or if you already debug through a real browser session with a tool like Playwright. Before adding it to a shared config, verify three things: that your Jest transform setup can be extended without breaking existing CSS mocks, that your CSS-in-JS library appears in the supported list, and that your CI pipeline does not run the preview server. The package is MIT-licensed and the last push was on 2026-04-25, so the code is current, but the README still lists multiple previews as an upcoming feature.

## FAQ

### How do I use jest-preview with my Jest tests?

Start the preview server with the jest-preview CLI, then call preview.debug() or the bare debug() function inside a test after rendering your component. The README states that executing preview.debug() triggers an automatic browser reload showing the rendered HTML. Jest's transform also has to be configured so CSS and file imports are intercepted.

### Does jest-preview support CSS, Sass and CSS-in-JS?

The README lists direct CSS imports, global CSS, CSS Modules, Sass and Less, plus CSS-in-JS libraries including styled-components and Emotion. Support depends on configuring Jest's transform to intercept CSS and files, which the README describes as a separate installation step.

### Is there a Vitest version of jest-preview?

Yes. The README links to Vitest Preview, by the same author, for projects using Vitest instead of Jest. The two packages integrate with different test runners, so the transform configuration is not shared.

### Can jest-preview show more than one rendered state at a time?

Not according to the current documentation. Multiple previews appear in the README's list of upcoming features, alongside support for more CSS-in-JS libraries, so it is described as unfinished work rather than available behavior.

## Sources

- [License: MIT](https://github.com/nvh95/jest-preview/blob/main/LICENSE)
- [nvh95/jest-preview on GitHub](https://github.com/nvh95/jest-preview)
- [Project website](https://www.jest-preview.com)
- [README](https://github.com/nvh95/jest-preview/blob/main/README.md)
- [Releases](https://github.com/nvh95/jest-preview/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nvh95-jest-preview