Forem: Steve Zhang

I Built a VS Code Extension That Turns Playwright Into an Interactive REPL

Steve Zhang — Thu, 02 Apr 2026 14:45:52 +0000

Writing Playwright tests follows the same loop: write code, run it, wait for the browser, see it fail, tweak a locator, run again. Each cycle takes seconds. I wanted something more interactive — type a command, see the result immediately.

So I built a VS Code extension that adds an interactive REPL, visual element picker, assertion builder, and recorder on top of Playwright's Test Explorer. Everything shares one persistent browser — no restarts between runs.

The workflow: Record → Pick → Assert → Run

The extension adds three panels to VS Code's bottom bar: REPL, Locator, and Assert.

Launch Browser

Click "Launch Browser" in the Testing sidebar. Chrome opens and stays open between test runs — zero startup overhead on each run.

REPL Panel

Type keyword commands directly:

pw> goto https://demo.playwright.dev/todomvc/
pw> fill "What needs to be done?" Buy groceries
pw> press Enter
pw> snapshot
pw> verify text 1 item left

Instead of writing page.locator('[placeholder="What needs to be done?"]').fill('Buy groceries'), you type fill "What needs to be done?" Buy groceries. Same Playwright engine, simpler syntax.

JavaScript works too:

pw> await page.title()
pw> page.locator('.todo-list li').count()

You get command history (up/down arrows), inline screenshots, execution timing, and meta-commands like .clear and .history.

Pick Locator

Click the pick arrow, hover over any element in the browser. The Locator panel shows:

The generated locator (editable — modify and re-test)
A highlight toggle to verify it targets the right element
The element's ARIA snapshot for accessibility inspection

No more inspecting the DOM to find the right selector.

Assert Builder

This is my favorite feature. Pick an element, and the Assert Builder shows you Playwright matchers — smart-filtered by element type:

Input field → toHaveValue, toBeEnabled, toBeDisabled
Text element → toContainText, toHaveText, toBeVisible
Checkbox → toBeChecked
Any element → toBeAttached, toHaveAttribute, toHaveCount

13 matchers total. Click Verify to run the assertion against the live page. Green or red, instantly. Supports negation (not checkbox) and editable expected values.

No more guessing whether your assertion is correct before running the full test.

Recorder

Hit Record, interact with the browser normally. Every click, fill, and navigation is captured as Playwright JavaScript — ready to paste into your test file.

Run Tests

The Test Explorer runs your existing playwright.config.ts tests. With "Show Browser" enabled, browser-only tests take a fast path: the script is sent directly to the browser via the extension bridge, bypassing worker startup, TypeScript compilation, and fixture setup entirely.

Tests that need Node APIs (fs, net, etc.) fall back to the standard Playwright runner with CDP browser reuse — still fast, just not instant.

How it works

The extension launches Chrome with --remote-debugging-port and a companion Chrome extension (Dramaturg) sideloaded. The REPL, Test Explorer, Recorder, and Picker all share this single browser instance via CDP.

Each keyword command maps directly to a Playwright API call:

"click"     → locator.click()
"goto"      → page.goto()
"fill"      → locator.fill()
"snapshot"  → accessibility tree via CDP

The keyword syntax is just a thin layer on top of the Playwright API — same engine, same locator resolution, same browser automation. No MCP, no daemon, no external process.

For the bridge fast path, the test script is bundled with esbuild and evaluated inside the browser context where page, expect, and all Playwright globals are already available. The result comes back via WebSocket. No test runner process involved at all.

Browser reuse: one browser for everything

This is the architectural decision that makes the whole thing work. Instead of launching a new browser per test run (the Playwright default), the extension keeps one browser open:

REPL sends commands to it
Test Explorer runs tests in it
Recorder captures interactions from it
Picker inspects elements in it

Same browser, same context, same cookies. Switch between REPL exploration and test execution seamlessly.

Built on Playwright Test for VS Code

The extension is built on top of Microsoft's official Playwright Test for VS Code extension (Apache 2.0). Both can coexist — you keep the official one installed and use this alongside it. Same playwright.config.ts, same test files, same Test Explorer interface.

The added layers (REPL, Picker, Assert Builder, Recorder) are what turns it from a test runner into an interactive development environment.

Getting started

Install "Playwright REPL" from the VS Code Marketplace
Open a project with a playwright.config.ts — or clone the demo repo to try it immediately
Click Launch Browser in the Testing sidebar
Open the REPL panel in the bottom bar and type goto https://example.com
Use Pick Locator to inspect elements, Assert Builder to verify values, and Record to capture interactions

Requirements: VS Code 1.93+, Node.js 18+, @playwright/test 1.58+ in your project.

What's next

I'm focused on making the record → assert → test loop as tight as possible. If you have ideas or find bugs, the repo is at github.com/stevez/playwright-repl.

Links:

How Fast Can Browser Automation Be? I Benchmarked 3 Approaches

Steve Zhang — Fri, 20 Mar 2026 03:12:30 +0000

Most browser automation tools run outside the browser — connecting via CDP over a WebSocket, issuing commands, and waiting for responses. What if Playwright ran inside the browser instead?

We benchmarked three ways to run the same Playwright commands and the results were dramatic.

The Setup

We ran the same commands on TodoMVC across three modes:

playwright-cli — Playwright's official CLI. Each command is a separate process.
playwright-repl standalone — Our CLI in default mode. A persistent REPL — start once, run many commands.
playwright-repl bridge — Our CLI connected to the Dramaturg Chrome extension. Playwright runs inside Chrome via playwright-crx.

The Results

Command	`playwright-cli`	Standalone	Bridge
`snapshot`	211ms	4ms	14ms
`click`	1,538ms	1,046ms	30ms
`hover`	1,240ms	1,050ms	28ms
`fill`	1,236ms	1,036ms	7ms
`press`	1,216ms	1,033ms	11ms
`eval`	1,220ms	1,010ms	3ms
`screenshot`	274ms	107ms	129ms
`tab-list`	217ms	4ms	4ms
`cookie-list`	201ms	3ms	2ms

What's Going On?

`playwright-cli`: ~200ms baseline + action overhead

Every playwright-cli command spawns a new Node.js process, connects to the running browser session, executes the command, and exits. That's ~200ms before anything happens. Actions like click and fill add another ~1,000ms of Playwright auto-waiting on top.

Standalone: fast queries, slow actions

playwright-repl starts once and keeps the connection open — no per-command startup cost. Queries like snapshot and tab-list are instant (3-4ms). But actions still take ~1,000ms because they go through the same external CDP pipeline: Node.js → WebSocket → Chrome → execute → wait for navigation/network idle → return.

Bridge: fast everything

This is where it gets interesting. In bridge mode, playwright-repl connects to the Dramaturg Chrome extension, which runs Playwright inside Chrome's service worker via playwright-crx. There's no external CDP connection — everything happens in-process.

A click that takes 1,046ms in standalone takes 30ms in bridge mode. That's 35x faster.

Why? A typical click involves many CDP round-trips under the hood:

Wait for element to be visible (poll via CDP)
Wait for element to be enabled (poll via CDP)
Scroll element into view (CDP)
Calculate click coordinates (CDP)
Perform the click (CDP)
Wait for potential navigation (CDP events)

Each step adds latency when going through an external WebSocket. In bridge mode, each internal call is microseconds — so even a dozen steps stay under 30ms.

Why Queries Are Fast Everywhere

snapshot is 4ms in standalone and 14ms in bridge. Both fast. Why?

Because snapshot is a single CDP call — walk the accessibility tree, return the result. One round-trip is fast regardless of whether it's external or in-process. The difference only shows up when commands involve many CDP round-trips, which is what actions do.

The Real-World Impact

For interactive use, the difference is feel:

playwright-cli: type a command, wait 1-2 seconds, see result → feels sluggish
Standalone REPL: queries are instant, actions take ~1 second → usable
Bridge mode: everything feels instant → flows like a conversation with the browser

For AI agents running via MCP, the difference is throughput. An agent exploring a page might run 50-100 commands. At 1 second per action, that's 1-2 minutes of waiting. At 30ms per action, it's 3 seconds.

Try It

# Install
npm install -g playwright-repl

# Standalone mode
playwright-repl --headed

# Bridge mode (requires Dramaturg extension)
playwright-repl --bridge

Install Dramaturg from the Chrome Web Store for bridge mode.

Let AI Control Your Real Browser — Not a Throwaway One

Steve Zhang — Thu, 19 Mar 2026 21:57:38 +0000

Most browser MCP servers launch a separate browser instance. Clean slate, no cookies, no auth. Want to automate something behind a login? Re-authenticate every time. Want to test your actual session state? Too bad.

What if the AI could just use the browser you already have open?

That's what Dramaturg + @playwright-repl/mcp does. The AI controls your real Chrome tabs — your cookies, your sessions, your localStorage — all intact.

How it works

Claude (or any MCP client)
  ↕ MCP (stdio)
playwright-repl MCP server
  ↕ WebSocket
Dramaturg Chrome extension
  ↕ CDP / chrome.debugger
Your real Chrome tabs

The key difference: Playwright runs inside the browser, not outside it. The extension uses playwright-crx to run the full Playwright API directly in Chrome's service worker. No Node.js relay, no separate browser process.

This means:

No re-authentication — Gmail, Notion, your internal tools — already logged in
expect() assertions — something no other browser MCP server supports
You see everything — the AI works in your actual tabs, in real time

Just two tools

While Playwright's official MCP server exposes ~70 tools, @playwright-repl/mcp exposes just two:

run_command — execute a single command (keyword or JavaScript)
run_script — run a multi-line script

The AI figures out what to do with them. Here's what a command looks like:

Keyword syntax (`.pw`)

snapshot                    → accessibility tree
goto https://example.com    → navigate
click "Sign in"             → click by text
fill "Email" "user@test.com"  → fill a form field
verify-text "Welcome"       → assert text is visible

Playwright API (JavaScript)

await page.getByRole('button', { name: 'Sign in' }).click();
await expect(page.getByText('Welcome')).toBeVisible();

Both work through the same run_command tool. The extension auto-detects the format.

AI Agents that actually verify their work

The MCP package includes four agents that go beyond "generate and hope":

Planner — Give it a URL and a goal. It takes snapshots, maps out the page structure, and produces a step-by-step workflow plan with the exact labels and text it found.

Generator — Takes a plan and turns it into a working script. The key word is working — it runs every command in the real browser, assembles the script, executes the full thing via run_script, and iterates until it passes.

Healer — Give it a broken script. Wrong selectors, changed page structure, timing issues. It runs the script, diagnoses failures with snapshots, fixes them, and re-runs until all lines pass.

Converter — Translates between .pw keyword syntax and JavaScript Playwright API. Produces idiomatic output — proper locator strategies, extracted variables, chained methods.

Every agent must run the script before outputting it. No "here's what should work" — it either passes or the agent keeps fixing.

Setup

1. Install

npm install -g @playwright-repl/mcp

Install Dramaturg from the Chrome Web Store.

2. Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "playwright-repl": {
      "command": "playwright-repl-mcp"
    }
  }
}

Or for Claude Code:

claude mcp add playwright-repl playwright-repl-mcp

3. Install the AI agents (optional)

mkdir -p .claude/agents
cp node_modules/@playwright-repl/mcp/agents/*.agent.md .claude/agents/

4. That's it

The extension connects automatically. No side panel needed. Just make sure Chrome is running.

Example prompts

Go to https://demo.playwright.dev/todomvc, add three todos, complete one, and verify the Active filter only shows the remaining two.

@playwright-repl-planner explore https://demo.playwright.dev/todomvc and plan a test for adding and completing todos

@playwright-repl-generator create a .pw script that adds 3 todos, completes one, and verifies the Active filter

@playwright-repl-healer this script is failing on line 5 — the selector changed after a site update: [paste script]

@playwright-repl-converter convert this .pw script to JavaScript: [paste script]

Human + AI, side by side

The extension isn't just a bridge for the AI — it's a full REPL you can use alongside it:

Watch commands execute in real time as the AI works
Intervene manually — type snapshot to check state, or navigate to a different page
Record your own interactions — click Record, interact with the page, get .pw commands or JS code
Switch tabs — the toolbar dropdown lets you redirect both the AI and your commands to any open tab

vs. other browser MCP servers

	playwright-repl	Playwright MCP	Playwriter
MCP tools	2	~70	1
Your real session	Yes	No	Yes
Playwright inside browser	Yes	No	No
`expect()` assertions	Yes	No	No
Full Playwright API	Yes	Yes	Yes
Human REPL alongside AI	Yes	No	No

Try it

> snapshot
> click "Sign in"
> fill "Email" "user@test.com"
> verify-text "Dashboard"

Your browser. Your sessions. AI that verifies its own work.

I Put Playwright Inside a Chrome Side Panel — Console, Recorder, and Debugger Included

Steve Zhang — Mon, 16 Mar 2026 13:57:28 +0000

When I started building Dramaturg, I just wanted a quick way to run Playwright commands without setting up a Node.js project. Type click "Submit", see it happen. Simple.

But then I kept going. And going. And now it has a full JS debugger — breakpoints, step-through, scope inspection — all running inside a Chrome side panel.

What is Dramaturg?

It's a Chrome extension that gives you a Playwright-powered REPL directly in your browser. No backend server, no IDE, no npx playwright test. Just open the side panel and start automating.

It has two input modes:

Keyword mode (.pw) — human-friendly commands:

goto https://demo.playwright.dev/todomvc
fill "What needs to be done?" "Buy groceries"
verify-text "1 item left"

JavaScript mode — full Playwright API:

await page.goto('https://example.com');
const title = await page.title();
console.log(title);
await expect(page.locator('h1')).toBeVisible();

Both modes run against your real browser session — cookies, auth, extensions, everything. This is the biggest difference from tools like Playwright MCP that launch isolated browser instances.

The debugger that nobody asked for (but I needed)

Once I had JS mode working, I found myself writing multi-line scripts and wanting to step through them. So I built a debugger.

Set breakpoints by clicking the gutter. Hit Debug instead of Run. The script pauses, and you get:

Step Over / Step Into / Step Out / Continue — floating toolbar, just like VS Code
Variables tab — auto-expands local, block, closure, and script scope variables
Expandable object tree — arrays, objects, Maps, Promises — drill into any value

All powered by Chrome's Debugger API (CDP). The extension creates a debug session against its own service worker, sets breakpoints, and catches Debugger.paused events. No external debugger needed.

Here's what it looks like paused inside a function:

function greet(name) {
  const message = "Hello, " + name + "!";    // ← breakpoint here
  console.log(message);
  return message.length;
}
const result = greet("World");

The Variables tab shows:

▾ Local
    name: "World"
    message: "Hello, World!"
▾ Script
    result: 13

How it works under the hood

The extension runs playwright-crx in a service worker — this is a Chromium-specific build of Playwright that uses chrome.debugger instead of CDP WebSocket. Commands execute directly in the browser process.

For the debugger, the flow is:

User clicks Debug → extension creates a CDP debug session targeting its own service worker
Breakpoints are set via Debugger.setBreakpoint
Code executes via Runtime.evaluate with awaitPromise: true
Debugger.paused event fires → extension reads callFrames[0].scopeChain
Scope variables displayed in the Variables tab via Runtime.getProperties

The key trick: the script runs in the service worker context, where page, expect, and crxApp are globals. So await page.click('button') actually drives the attached browser tab.

Console — Chrome DevTools, but for Playwright

The console works like Chrome DevTools — type a command, see the result inline. But instead of raw JavaScript, you can use Playwright's keyword commands.

> snapshot

Returns the page's accessibility tree as an expandable tree view — click to drill into nodes, no more scrolling through walls of text.

> goto https://example.com
  Navigated to "Example Domain"
> await page.title()
  "Example Domain"
> await page.evaluate(() => document.querySelectorAll('a').length)
  1

The console auto-detects what you're typing:

click "Submit" → runs as a .pw keyword command
await page.locator('h1').textContent() → runs as Playwright API

Results show as expandable object trees — arrays, objects, Maps, Promises — just like Chrome DevTools. Click to expand nested properties.

Recorder — watch commands write themselves

Click the Record button, then interact with the page normally. Every click, form fill, and navigation is captured and written to the editor in real time.

Recording works in both modes:

In .pw mode → generates keyword commands: click "Submit", fill "Email" "test@example.com"
In JS mode → generates Playwright API: await page.getByRole('button', { name: 'Submit' }).click()

Stop recording, clean up the script if needed, hit Run. Instant test.

Pick Element — point and click locators

Finding the right selector is half the battle. Click the Pick Element button (crosshair icon), then hover over any element on the page. You'll see:

A blue highlight overlay around the element

Click to pick it. The console shows locators and assertions in both formats:

locator
  js:  await page.getByRole('link', { name: 'Get started' }).highlight();
  pw:  highlight link "Get started"

assertion
  js:  await expect(page.getByRole('link', { name: 'Get started' })).toContainText('Get started');
  pw:  verify-element link "Get started"

Copy whichever format you need — ready to paste into your script or test.

More features

Snapshot tree — snapshot renders the accessibility tree as an expandable tree view (not raw text).
Autocompletion — ghost-text suggestions for both .pw commands and Playwright API methods.
Side panel or popup — opens as a side panel by default; switch to popup window in Options if you prefer a floating window.
MCP server — pair with @playwright-repl/mcp to let Claude or other AI agents drive your browser.

Why not just use Playwright Test?

You absolutely should for production tests. Dramaturg is for the exploration phase:

Quickly test a selector before putting it in your test suite
Debug a flaky test by stepping through it interactively
Record a user flow and convert it to a test
Let an AI agent generate and run tests on your real session

Think of it as Chrome DevTools Console, but with Playwright superpowers.

Try it

Chrome Web Store: Dramaturg
GitHub: playwright-repl
CLI: npm install -g playwright-repl

playwright-repl: Browser Automation From Your Terminal, No Code Required

Steve Zhang — Sun, 15 Feb 2026 03:56:40 +0000

I've been using playwright-cli — Microsoft's command-line tool that gives AI agents browser automation skills via the Playwright MCP daemon. It's brilliant for agents: one command, one process, one result. But for humans, every command spawns a brand-new Node.js process — connect to the daemon, send one message, disconnect, exit. That's 50–100ms overhead per command.

I wanted something faster. Something interactive. Something designed for humans instead of AI agents — a persistent session with instant feedback.

So I built playwright-repl — a REPL that reuses playwright-cli's command vocabulary and MCP daemon architecture, but replaces the one-shot client with a persistent socket connection. Same wire protocol, same daemon, same browser commands — just a better interface for interactive use.

What does it look like?

$ playwright-repl --headed

pw> goto https://demo.playwright.dev/todomvc/
pw> fill "What needs to be done?" "Buy groceries"
pw> press Enter
pw> fill "What needs to be done?" "Write tests"
pw> press Enter
pw> check "Buy groceries"
pw> verify-text "1 item left"
✓ Text "1 item left" is visible

No imports. No async/await. No page.locator(). Just type what you want the browser to do.

Why not just use Playwright's codegen?

Playwright's codegen is great for generating test code. But sometimes you don't want code — you want to explore.

Debugging a login flow? Type commands and see what happens.
Building a demo? Record the session and replay it.
Running a smoke test in CI? Pipe a .pw file and check the exit code.

playwright-repl sits between "clicking around manually" and "writing a full test suite." It's the exploratory middle ground.

Text locators: just say what you see

The thing I'm most proud of is text locators. Instead of inspecting elements for CSS selectors or waiting for a snapshot to get element refs, you just use the text you see on screen:

pw> click "Get Started"
pw> fill "Email" "test@example.com"
pw> fill "Password" "secret123"
pw> click "Sign In"
pw> check "Remember me"
pw> select "Country" "Japan"

Under the hood, it tries multiple strategies — getByText, getByRole('button'), getByRole('link'), getByLabel, getByPlaceholder — with a fallback chain. Case differences don't matter because role matching is case-insensitive.

You can also use element refs from snapshot output if you prefer precision:

pw> snapshot
- heading "todos" [ref=e1]
- textbox "What needs to be done?" [ref=e8]

pw> click e8
pw> fill e8 "Buy groceries"

Record and replay

This is where it gets really useful. Record your browser session as a .pw file:

pw> .record smoke-test
⏺ Recording to smoke-test.pw

pw> goto https://demo.playwright.dev/todomvc/
pw> fill "What needs to be done?" "Buy groceries"
pw> press Enter
pw> verify-text "1 item left"
pw> .save
✓ Saved 4 commands to smoke-test.pw

The .pw file is just plain text:

# CI smoke test
goto https://demo.playwright.dev/todomvc/
fill "What needs to be done?" "Buy groceries"
press Enter
verify-text "1 item left"

Replay it any time:

# Headless (CI mode)
playwright-repl --replay smoke-test.pw --silent

# With a visible browser
playwright-repl --replay smoke-test.pw --headed

# Step through interactively
playwright-repl --replay smoke-test.pw --step --headed

These .pw files are human-readable, diffable, and version-controllable. Commit them alongside your code. Run them in CI. Share them with teammates who don't write JavaScript.

Assertions built in

No test framework needed. Verify state inline:

pw> verify-text "1 item left"
✓ Text "1 item left" is visible

pw> verify-element heading "todos"
✓ Element heading "todos" is visible

pw> verify-value "Email" "test@example.com"
✓ Value matches

If an assertion fails, you get a clear error — and in replay mode, the process exits with code 1. That's all CI needs.

50+ commands, short aliases

Every command has a short alias for quick typing:

You type	It does
`g https://example.com`	Navigate to URL
`s`	Accessibility tree snapshot
`c e5`	Click element ref e5
`f "Email" "me@test.com"`	Fill a form field
`p Enter`	Press a key
`ss`	Take a screenshot
`vt "hello"`	Verify text is visible
`back`	Go back in history

The full list includes interaction (click, fill, type, press, hover, drag), inspection (snapshot, screenshot, eval, console, network), storage (cookies, localStorage, sessionStorage), tabs, dialogs, network routing, and more.

How it works under the hood

playwright-repl stands on the shoulders of playwright-cli and the Playwright MCP architecture. It reuses:

The MCP daemon from playwright@1.59+ — browser launch, CDP communication, all 50+ tool handlers
The command vocabulary from playwright-cli — click, fill, snapshot, screenshot, etc.
The wire protocol — newline-delimited JSON over Unix socket / Windows named pipe

The REPL is just a thin, persistent client that:

Parses your input (alias resolution + argument parsing)
Sends a JSON message over the socket (identical format to playwright-cli)
Displays the result

Because the socket stays open, there's zero startup overhead per command. The daemon doesn't care whether the message came from playwright-cli, the REPL, or an AI agent — the wire messages are identical. playwright-repl adds the human-friendly layer on top: text locators, recording, replay, assertions, and aliases.

Use it in CI

# .github/workflows/smoke.yml
jobs:
  smoke-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npx playwright install chromium
      - run: npx playwright-repl --replay tests/smoke.pw --silent

The --silent flag suppresses the banner. The process exits 0 on success, 1 on failure. That's it.

Get started

npm install -g playwright-repl
npx playwright install
playwright-repl --headed

Then type goto https://demo.playwright.dev/todomvc/ and start exploring.

Chrome DevTools extension

We're also building playwright-repl-extension — a Chrome DevTools panel that brings the same REPL experience into the browser. Open DevTools, switch to the "Playwright" tab, and type commands directly. It also includes an action recorder that captures your clicks and form fills as .pw commands.

The extension is standalone (no Node.js daemon needed) — it uses Chrome's chrome.debugger API to drive the inspected page via CDP.

GitHub: stevez/playwright-repl-extension

E2E Coverage in Next.js: Dev Mode vs Production Mode

Steve Zhang — Thu, 01 Jan 2026 20:42:28 +0000

nextcov supports collecting coverage from both next dev and next build && next start. This article explains the differences and when to use each mode.

Dev Mode

In dev mode, nextcov collects coverage directly from Next.js's webpack dev server.

How It Works

Next.js dev server starts with --inspect=9230
Next.js spawns a worker process on port 9231 (inspect port + 1)
nextcov connects to the worker via CDP (Chrome DevTools Protocol)
Coverage is collected using Profiler.startPreciseCoverage() API
Source maps are inline (webpack eval) — no build artifacts needed

Running Dev Mode

# Start Next.js dev server with inspector enabled
NODE_OPTIONS='--inspect=9230' npm run dev &

# Run tests
npx playwright test

Dev Mode Characteristics

No build required — start testing immediately
Inline source maps — webpack eval scripts contain embedded source maps
CDP port: cdpPort + 1 (9231) — connects to the worker process
Hot reload — changes are reflected without restart
Slower — on-demand compilation adds overhead
Client coverage — Playwright connects to the browser via CDP

Production Mode

In production mode, nextcov uses Node.js native V8 coverage with pre-built bundles.

How It Works

Build Next.js with source maps enabled (E2E_MODE=true)
Start the production server with NODE_V8_COVERAGE and --inspect
nextcov connects via CDP on port 9230
Coverage is collected using Node.js native V8 coverage
Source maps are external (.map files) generated during build

Running Production Mode

# Build with source maps
E2E_MODE=true npm run build

# Start server with coverage enabled
NODE_V8_COVERAGE=.v8-coverage NODE_OPTIONS='--inspect=9230' npm start &

# Run tests
npx playwright test

Production Mode Characteristics

Build required — must run next build first
External source maps — .map files in build output
CDP port: cdpPort (9230) — connects directly to the server
No hot reload — restart required for changes
Faster — pre-compiled bundles execute quickly
Client coverage — Playwright connects to the browser via CDP

Comparison

Aspect	Dev Mode	Production Mode
Command	`next dev`	`next build && next start`
Source Maps	Inline (webpack eval)	External (.map files)
Build Required	No	Yes
Hot Reload	Yes	No
Coverage Method	CDP Profiler API	Node.js native V8 coverage
CDP Port	`cdpPort + 1` (9231)	`cdpPort` (9230)
Performance	Slower (compilation)	Faster
Recommended For	Development iteration	CI/CD, final coverage

Auto-Detection

nextcov automatically detects the mode — no configuration needed. Just use the same globalSetup and globalTeardown for both.

📊 Auto-detecting server mode...
  Trying dev mode (worker port 9231)...
  ✓ Dev mode detected (webpack eval scripts found)
  ✓ Server coverage collection started

Or for production mode:

📊 Auto-detecting server mode...
  Trying dev mode (worker port 9231)...
  ⚠️ Failed to connect to CDP (dev mode): Error: connect ECONNREFUSED
  ℹ️ Production mode will be used (NODE_V8_COVERAGE + port 9230)

Same Output, Different Paths

Both modes produce identical Istanbul-compatible output:

coverage/e2e/
├── coverage-final.json   # Merges with Vitest coverage
├── lcov.info             # For CI tools
└── index.html            # Interactive report

This means you can:

Use dev mode during development for fast iteration
Use production mode in CI for accurate final reports
Merge both with Vitest coverage using nextcov merge

Summary

Use Case	Mode	Command
Local development	Dev	`next dev --inspect=9230`
CI/CD pipeline	Production	`next build && next start --inspect=9230`
Quick coverage check	Dev	No build required
Production validation	Production	Uses production bundle

Both modes work seamlessly with nextcov — just run your tests and coverage is collected automatically.

References

nextcov — E2E coverage for Next.js with Playwright
nextcov README: Dev Mode — Full documentation

This is part 6 of a series on test coverage for modern React applications:

nextcov - Collecting Test Coverage for Next.js Server Components
Why Istanbul Coverage Doesn't Work with Next.js App Router
V8 Coverage vs Istanbul: Performance and Accuracy
V8 Coverage Limitations and How to Work Around Them
How to Merge Vitest Unit, Component, and E2E Test Coverage
E2E Coverage in Next.js: Dev Mode vs Production Mode (this article)

How to Merge Vitest Unit, Component, and E2E Test Coverage

Steve Zhang — Thu, 01 Jan 2026 20:19:54 +0000

📝 UPDATE (January 2025):

As of nextcov@1.1.0:

Directive stripping is now OFF by default - Use --strip-directives if you need it

ast-v8-to-istanbul@0.3.10 fix - Ternary and && patterns in JSX now have proper branch coverage, so coverage merging should have fewer mismatches

Modern React applications often have multiple test types running in different environments. Each produces its own coverage report. This article shows how to merge them into a single, accurate coverage report.

Tech Stack

This article assumes the following setup:

Layer	Technology
Application	React + Next.js / Vite / Webpack
Unit Tests	Vitest (jsdom environment)
Component Tests	Vitest Browser Mode + Playwright
E2E Tests	Playwright + nextcov
Coverage Provider	V8

The Problem: Separate Coverage Reports

A typical Next.js project might have:

coverage/
├── unit/           # From vitest unit tests (jsdom)
├── component/      # From vitest browser tests
└── e2e/            # From playwright + nextcov

Each directory contains a coverage-final.json file with coverage data for the same source files. But the coverage numbers don't add up correctly if you try to merge them naively.

Why Naive Merging Fails

Consider a simple component:

// src/components/Input.tsx
'use client'

import React from 'react'

export function Input({ error }: { error?: string }) {
  return (
    <div>
      <input />
      {error && <p>{error}</p>}
    </div>
  )
}

When Vitest runs unit tests, it counts the 'use client' directive and import statement as executable statements. When V8 coverage runs during E2E tests, these lines don't exist in the bundled code.

If you merge these reports without accounting for this difference, you get inflated statement counts or incorrect coverage percentages.

Setting Up Separate Coverage Directories

Unit Test Configuration

// vitest.config.mts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react-swc'
import tsconfigPaths from 'vite-tsconfig-paths'

export default defineConfig({
  plugins: [tsconfigPaths(), react()],
  test: {
    globals: true,
    environment: 'jsdom',
    setupFiles: ['./vitest.setup.ts'],
    include: ['src/**/__tests__/**/*.test.{ts,tsx}'],
    exclude: ['src/**/*.browser.test.{ts,tsx}'],
    coverage: {
      enabled: true,
      provider: 'v8',
      reportsDirectory: './coverage/unit',
      include: ['src/**/*.{ts,tsx}'],
      exclude: [
        'src/**/__tests__/**',
        'src/**/*.test.{ts,tsx}',
        'src/**/*.browser.test.{ts,tsx}',
      ],
      reporter: ['text', 'json', 'html'],
    },
  },
})

Key settings:

reportsDirectory: './coverage/unit' — Output to a dedicated directory
provider: 'v8' — Use V8 coverage (not Istanbul)
reporter: ['json'] — Must include json to generate coverage-final.json

Component Test Configuration

// vitest.component.config.mts
import { defineConfig } from 'vitest/config'
import react from '@vitejs/plugin-react-swc'
import tsconfigPaths from 'vite-tsconfig-paths'
import { playwright } from '@vitest/browser-playwright'

export default defineConfig({
  plugins: [tsconfigPaths(), react()],
  test: {
    globals: true,
    setupFiles: ['./vitest.browser.setup.ts'],
    include: ['src/**/*.browser.test.{ts,tsx}'],
    coverage: {
      enabled: true,
      provider: 'v8',
      reportsDirectory: './coverage/component',
      include: ['src/**/*.{ts,tsx}'],
      exclude: [
        'src/**/__tests__/**',
        'src/**/*.test.{ts,tsx}',
        'src/**/*.browser.test.{ts,tsx}',
      ],
      reporter: ['text', 'json', 'html'],
    },
    browser: {
      enabled: true,
      provider: playwright(),
      instances: [{ browser: 'chromium' }],
      headless: true,
    },
  },
})

Key differences from unit tests:

include: ['src/**/*.browser.test.{ts,tsx}'] — Different file pattern
reportsDirectory: './coverage/component' — Separate output directory
browser.enabled: true — Runs in a real browser

Package.json Scripts

{
  "scripts": {
    "test:unit": "vitest run",
    "test:component": "vitest run --config vitest.component.config.mts",
    "test": "npm run test:unit && npm run test:component",
    "coverage:merge": "nextcov merge coverage/unit coverage/component coverage/e2e -o coverage/merged"
  }
}

The Directive Stripping Problem

Before diving into merge tools, you need to understand why naive merging fails.

When running tests in different environments, V8 coverage produces inconsistent statement counts:

Vitest unit tests (jsdom): Counts import statements and directives ('use client', 'use server') as executable
Vitest browser tests: Also counts imports as executable statements
E2E coverage (bundled code): These statements don't exist in the bundle

Without normalization:

# Vitest unit coverage (counts directives)
Input.tsx: 10 statements, 8 covered (80%)

# E2E coverage (no directives in bundle)
Input.tsx: 8 statements, 6 covered (75%)

# Naive merge (wrong!)
Input.tsx: 10 statements, 14 covered (140%?!)

The solution is to strip import statements and directives before merging, normalizing all sources to the same baseline.

Why Not Use Vitest's Multi-Project Setup?

You might think Vitest's multi-project setup could solve this — run unit and component tests as separate projects and let Vitest merge the coverage automatically.

Unfortunately, there's currently a bug in Vitest where multi-project setups don't properly merge coverage reports. Until this is fixed, you need external tools to merge coverage from different test environments.

Option 1: vitest-coverage-merge (Vitest Only)

For merging just Vitest unit and component test coverage, use vitest-coverage-merge:

npm install -D vitest-coverage-merge

npx vitest-coverage-merge coverage/unit coverage/component -o coverage/merged

What vitest-coverage-merge Does

Loads coverage files from each directory's coverage-final.json
Normalizes by stripping ESM import statements and React/Next.js directives
Intelligently merges while preferring browser test structures
Generates reports (HTML, LCOV, JSON)

This tool specifically addresses the environment-based coverage differences between jsdom and real browser tests — unlike Vitest's built-in --merge-reports which only handles sharded test runs.

Package.json Scripts (Vitest Only)

{
  "scripts": {
    "test:unit": "vitest run",
    "test:component": "vitest run --config vitest.component.config.mts",
    "test": "npm run test:unit && npm run test:component",
    "coverage:merge": "vitest-coverage-merge coverage/unit coverage/component -o coverage/merged"
  }
}

Option 2: nextcov merge (Including E2E)

For merging Vitest coverage with E2E coverage from Playwright + nextcov, use nextcov merge:

npx nextcov merge coverage/unit coverage/component coverage/e2e -o coverage/merged

What nextcov merge Does

Loads coverage files from each directory's coverage-final.json
Optionally strips directives ('use client', 'use server', import statements) when using --strip-directives
Selects the best structure for each file (prefers sources without directive inflation)
Merges execution counts using a "max" strategy
Generates reports (HTML, LCOV, JSON, text-summary)

Enabling Directive Stripping

By default, nextcov merge does NOT strip directives. If you have coverage mismatches due to 'use client', 'use server', or import statements (common when merging Vitest coverage with E2E coverage), you can enable stripping:

npx nextcov merge coverage/unit coverage/component coverage/e2e --strip-directives

Adding E2E Coverage

For complete coverage, add E2E test coverage with nextcov:

Playwright Configuration

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test'
import type { NextcovConfig } from 'nextcov'

export const nextcov: NextcovConfig = {
  cdpPort: 9230,
  outputDir: 'coverage/e2e',
  sourceRoot: './src',
  include: ['src/**/*.{ts,tsx}'],
  exclude: [
    'src/**/__tests__/**',
    'src/**/*.test.{ts,tsx}',
    'src/**/*.browser.test.{ts,tsx}',
  ],
  reporters: ['html', 'lcov', 'json', 'text-summary'],
}

export default defineConfig({
  testDir: './e2e',
  reporter: [['list'], ['html'], ['./e2e/coverage-reporter.ts']],
  use: {
    baseURL: 'http://localhost:3000',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
})

Package.json Scripts

{
  "scripts": {
    "build:e2e": "cross-env E2E_MODE=true npm run build",
    "start:e2e": "cross-env E2E_MODE=true NODE_V8_COVERAGE=.v8-coverage NODE_OPTIONS=--inspect=9230 next start",
    "e2e": "npm run e2e:clean && npm run e2e:run",
    "e2e:clean": "rimraf coverage/e2e",
    "e2e:run": "start-server-and-test start:e2e http://localhost:3000 playwright-test",
    "coverage:merge": "nextcov merge coverage/unit coverage/component coverage/e2e -o coverage/merged"
  }
}

See Article 1 for detailed E2E coverage setup.

Merge Strategy Details

Max Strategy (Default)

For each coverage item (statement, branch, function), nextcov takes the maximum count across all sources:

Unit tests:   line 10 executed 5 times
Component:    line 10 executed 3 times
E2E:          line 10 executed 2 times
────────────────────────────────────────
Merged:       line 10 executed 5 times (max)

This is conservative — it reflects the highest observed coverage without double-counting.

Structure Selection

When merging, nextcov must choose which source's "structure" to use (which statements exist, where branches are). It prefers:

Sources without L1:0 directive statements (E2E-style coverage)
Sources with more coverage items (more complete analysis)
Later sources when equal (E2E is typically last)

This ensures the merged report doesn't show inflated statement counts from directive-tracking sources.

Complete Example

Here's a full working setup:

Directory Structure

project/
├── src/
│   ├── components/
│   │   ├── Input.tsx
│   │   └── __tests__/
│   │       ├── Input.test.tsx          # Unit tests
│   │       └── Input.browser.test.tsx  # Component tests
├── e2e/
│   └── form.spec.ts                 # E2E tests
├── coverage/
│   ├── unit/
│   ├── component/
│   ├── e2e/
│   └── merged/
├── vitest.config.mts
├── vitest.component.config.mts
├── playwright.config.ts
└── package.json

Running Tests and Merging

# Run all tests with coverage
npm run test:unit
npm run test:component
npm run e2e

# Merge all coverage
npx nextcov merge coverage/unit coverage/component coverage/e2e -o coverage/merged

# Or use the npm script
npm run coverage:merge

Output

📊 nextcov merge
   Inputs: coverage/unit, coverage/component, coverage/e2e
   Output: coverage/merged
   Reporters: html, lcov, json, text-summary
   Strip directives: no

   Loading: coverage/unit/coverage-final.json
   Loading: coverage/component/coverage-final.json
   Loading: coverage/e2e/coverage-final.json

=============================== Coverage summary ===============================
Statements   : 89.07% ( 595/668 )
Branches     : 78.06% ( 338/433 )
Functions    : 92.9% ( 131/141 )
Lines        : 88.71% ( 574/647 )
================================================================================

✅ Merged coverage report generated
   Output: coverage/merged

Choosing Report Formats

By default, nextcov generates all report formats. You can customize this:

# Only HTML and LCOV (for CI integration)
npx nextcov merge coverage/unit coverage/e2e --reporters html,lcov

# Only JSON (for further processing)
npx nextcov merge coverage/unit coverage/e2e --reporters json

Available reporters:

html — Interactive HTML report
lcov — LCOV format for CI tools (Codecov, Coveralls)
json — JSON format (coverage-final.json)
text-summary — Console summary

Troubleshooting

"No coverage-final.json found"

Ensure your Vitest config includes json in the reporters:

coverage: {
  reporter: ['text', 'json', 'html'],  // Must include 'json'
}

Coverage percentages seem wrong after merge

This usually means directive stripping is needed. Check:

Are you using V8 coverage (provider: 'v8') in all sources?
Do your source files have 'use client' or 'use server' directives?
Try running with --strip-directives to normalize the coverage data

Some files missing from merged report

Files only appear if they're in at least one source. If E2E tests don't exercise a file, it won't appear in E2E coverage. The merge will still include it from unit/component coverage.

Summary

Step	Command	Output
Unit tests	`npm run test:unit`	`coverage/unit/`
Component tests	`npm run test:component`	`coverage/component/`
E2E tests	`npm run e2e`	`coverage/e2e/`
Merge all	`npx nextcov merge coverage/unit coverage/component coverage/e2e`	`coverage/merged/`

Key points:

Use separate reportsDirectory for each test type
Always include json reporter to generate coverage-final.json
Use vitest-coverage-merge for Vitest-only merging, or nextcov merge to include E2E coverage
Use --strip-directives if you have directive mismatches between coverage sources

References

vitest-coverage-merge — Merge Vitest unit and component test coverage
nextcov — E2E coverage for Next.js with Playwright
Vitest Coverage — Official Vitest coverage documentation
@vitest/browser — Browser testing with Vitest

This is part 5 of a series on test coverage for modern React applications:

nextcov - Collecting Test Coverage for Next.js Server Components
Why Istanbul Coverage Doesn't Work with Next.js App Router
V8 Coverage vs Istanbul: Performance and Accuracy
V8 Coverage Limitations and How to Work Around Them
How to Merge Vitest Unit, Component, and E2E Test Coverage (this article)
E2E Coverage in Next.js: Dev Mode vs Production Mode

V8 Coverage Limitations and How to Work Around Them

Steve Zhang — Thu, 01 Jan 2026 19:38:05 +0000

🎉 UPDATE: This limitation has been FIXED!

As of ast-v8-to-istanbul@0.3.10, V8 coverage now properly tracks branch coverage for ternary operators and logical AND patterns in JSX. The fix was in the getSourceLines function that previously failed to correctly match sources in multi-source source maps.

What this means for you:

Vitest users: Update to the latest version (it uses ast-v8-to-istanbul internally)

nextcov users: Update to v1.1.0+

eslint-plugin-v8-coverage: No longer needed - you can remove it from your project

The workarounds described in this article are no longer necessary, but remain valid coding patterns if you prefer them for readability.

V8 native coverage is powerful — it works with any bundler, has minimal overhead, and can collect coverage across multiple processes. But it has one specific limitation you need to understand when testing React applications.

The JSX Blind Spots

V8 coverage has blind spots for ternary operators and logical AND that return JSX inside {} (JSX expression containers):

Ternary Returning JSX

function UserStatus({ isLoggedIn }) {
  return (
    <div>
      {isLoggedIn ? <WelcomeMessage /> : <LoginPrompt />}
    </div>
  );
}

V8 doesn't recognize this as a branch at all — it reports 0 branches for this line. Even if your test only renders with isLoggedIn={true}, V8 won't warn you that <LoginPrompt /> was never rendered.

Logical AND Returning JSX

function ErrorDisplay({ error }) {
  return (
    <div>
      {error && <ErrorMessage message={error} />}
    </div>
  );
}

Same as the ternary case — V8 reports 0 branches for this line. Even if your test only passes error={null}, V8 won't warn you that <ErrorMessage /> was never rendered.

What Works Correctly

V8 tracks branches correctly for:

Ternary/logical AND returning strings (not JSX):

{isLoggedIn ? 'Welcome!' : 'Please log in'}  // ✓ V8 tracks this
{error && 'Error occurred'}  // ✓ V8 tracks this

If/else statements:

if (isLoggedIn) {
  return <WelcomeMessage />;
} else {
  return <LoginPrompt />;
}  // ✓ V8 tracks this

Ternary outside JSX expression container:

return isLoggedIn ? <WelcomeMessage /> : <LoginPrompt />;  // ✓ V8 tracks this

The Specific Blind Spots

The blind spot occurs only when:

Using a ternary ? : or logical AND &&
Inside a JSX expression container {}
Returning JSX elements (not strings or primitives)

// ✗ Blind spots - V8 cannot track branch coverage
<div>{condition ? <ComponentA /> : <ComponentB />}</div>
<div>{condition && <ComponentA />}</div>

// ✓ Works - returning strings
<div>{condition ? 'yes' : 'no'}</div>
<div>{condition && 'yes'}</div>

// ✓ Works - using if/else
if (condition) return <ComponentA />;
return <ComponentB />;

Detecting Blind Spots

Using nextcov check

The nextcov check command scans your codebase for these patterns:

npx nextcov check src/

Example output:

V8 Coverage Blind Spots Found:
────────────────────────────────────────────────────────────

src/components/UserStatus.tsx:5:7
  ⚠ JSX ternary operator (V8 cannot track branch coverage)

src/components/ErrorDisplay.tsx:4:7
  ⚠ JSX logical AND (V8 cannot track branch coverage)

────────────────────────────────────────────────────────────
Found 2 issues in 2 files

Using ESLint

For real-time detection during development, use eslint-plugin-v8-coverage:

npm install -D eslint-plugin-v8-coverage

// eslint.config.js
import v8Coverage from 'eslint-plugin-v8-coverage'

export default [
  v8Coverage.configs.recommended,
]

This flags JSX ternary and logical AND patterns as errors, reminding you to ensure both branches are tested.

Workarounds

1. Write Explicit Tests for Both Branches

The simplest solution: ensure your tests cover both cases.

// UserStatus.test.tsx
it('shows welcome message when logged in', () => {
  render(<UserStatus isLoggedIn={true} />);
  expect(screen.getByText('Welcome!')).toBeInTheDocument();
});

it('shows login prompt when not logged in', () => {
  render(<UserStatus isLoggedIn={false} />);
  expect(screen.getByText('Please log in')).toBeInTheDocument();
});

Even though V8 won't track the branch coverage accurately, your tests will fail if either branch is broken.

2. Extract Conditional to a Variable

Move the conditional outside the JSX expression container:

// Before: V8 blind spot (0 branches reported)
function Input({ error, helperText }) {
  return (
    <div>
      <input />
      {error && <p className="text-red-600">{error}</p>}
      {helperText && !error && <p className="text-gray-500">{helperText}</p>}
    </div>
  );
}

// After: V8 tracks branches correctly (7 branches vs 4 before)
function Input({ error, helperText }) {
  const errorElement = error ? (
    <p className="text-red-600">{error}</p>
  ) : null;

  const helperElement = helperText && !error ? (
    <p className="text-gray-500">{helperText}</p>
  ) : null;

  return (
    <div>
      <input />
      {errorElement}
      {helperElement}
    </div>
  );
}

By extracting the ternary to a variable outside the JSX {}, V8 can properly track the branch. The variable reference {errorElement} inside JSX is just a simple expression, not a conditional.

In the example above, the "before" version reports only 4 branches total (none for lines with &&). After extracting to variables, V8 reports 7 branches and correctly tracks coverage for the conditionals.

Double AND pattern:

// Before: V8 blind spot (0 branches for this line)
{user && user.isAdmin && <AdminPanel />}

// After: V8 tracks branches correctly
const adminPanel = user && user.isAdmin ? <AdminPanel /> : null;
// ...
{adminPanel}

The key insight: convert && chains that return JSX into explicit ternary expressions (? : null) outside the JSX container.

3. Use Early Returns with if/else

For simpler components, use if/else statements instead of JSX ternaries:

// Before: V8 blind spot
function UserStatus({ isLoggedIn }) {
  return (
    <div>
      {isLoggedIn ? <WelcomeMessage /> : <LoginPrompt />}
    </div>
  );
}

// After: V8 tracks branches correctly
function UserStatus({ isLoggedIn }) {
  if (isLoggedIn) {
    return (
      <div>
        <WelcomeMessage />
      </div>
    );
  }

  return (
    <div>
      <LoginPrompt />
    </div>
  );
}

V8 correctly tracks if/else statement branches, so coverage reports will be accurate.

4. Accept the Limitation

Sometimes the cleanest code uses JSX ternaries, and that's fine. Just be aware:

V8 coverage numbers for branch coverage may be inflated
Write tests that explicitly cover both branches
Use the ESLint plugin or nextcov check to identify these patterns

Other V8 Limitations

Source Map Dependency

V8 coverage reports byte ranges in bundled code. Without source maps, you can't map back to original files:

// next.config.ts
const nextConfig = {
  productionBrowserSourceMaps: !!process.env.E2E_MODE,
  webpack: (config) => {
    if (process.env.E2E_MODE) {
      config.devtool = 'source-map'
    }
    return config
  },
}

Bundler Transformations

Code transformations can affect coverage accuracy:

Tree shaking removes unused code — can't measure coverage for code that doesn't exist in the bundle
Code splitting may load chunks conditionally — coverage depends on which chunks are loaded during tests
Minification without source maps makes coverage meaningless

Multi-Process Coordination

V8 coverage is collected per-process. For Next.js applications, you need to coordinate coverage from:

Next.js server process (Server Components, Server Actions)
Browser process (Client Components)
Test runner process

Tools like nextcov handle this coordination automatically.

Summary

Limitation	Impact	Workaround
Ternary/logical AND returning JSX inside `{}`	Branch coverage not tracked	Write explicit tests for both branches, use ESLint plugin
Source map dependency	Coverage on bundled code only	Enable source maps for test builds
Bundler transformations	Some code may be excluded	Understand your bundler's behavior
Multi-process coordination	Coverage incomplete	Use tools like nextcov

V8 coverage is the practical choice for modern Next.js applications, but understanding its limitations helps you write more comprehensive tests and interpret coverage reports accurately.

References

nextcov — E2E coverage for Next.js with Playwright
eslint-plugin-v8-coverage — Detect V8 coverage blind spots
V8 Blog: JavaScript Code Coverage — How V8 coverage works at the engine level

This is part 4 of a series on test coverage for modern React applications:

nextcov - Collecting Test Coverage for Next.js Server Components
Why Istanbul Coverage Doesn't Work with Next.js App Router
V8 Coverage vs Istanbul: Performance and Accuracy
V8 Coverage Limitations and How to Work Around Them (this article)
How to Merge Vitest Unit, Component, and E2E Test Coverage
E2E Coverage in Next.js: Dev Mode vs Production Mode

Update History

January 2025: The V8 coverage limitation described in this article has been fixed in ast-v8-to-istanbul@0.3.10. The nextcov check command no longer scans for these patterns, and eslint-plugin-v8-coverage has been deprecated.

V8 Coverage vs Istanbul: Performance and Accuracy

Steve Zhang — Thu, 01 Jan 2026 17:09:26 +0000

When it comes to JavaScript code coverage, Istanbul has been the industry standard for over a decade. But V8 native coverage is gaining traction, especially for modern frameworks. How do they compare in terms of performance and accuracy?

How They Work: Fundamentally Different Approaches

Istanbul: Instrumentation-Based

Istanbul works by transforming your source code before execution. It injects counter variables that track which lines, branches, and functions are executed.

// Original code
function greet(name) {
  if (name) {
    return `Hello, ${name}!`;
  }
  return 'Hello, stranger!';
}

// After Istanbul instrumentation
function greet(name) {
  cov_abc123.f[0]++;           // Function counter
  cov_abc123.s[0]++;           // Statement counter
  if (name) {
    cov_abc123.b[0][0]++;      // Branch counter (true)
    cov_abc123.s[1]++;
    return `Hello, ${name}!`;
  } else {
    cov_abc123.b[0][1]++;      // Branch counter (false)
  }
  cov_abc123.s[2]++;
  return 'Hello, stranger!';
}

This transformation happens at build time via Babel (babel-plugin-istanbul) or other AST transformers.

V8: Runtime Coverage

V8 coverage works at the JavaScript engine level. V8 (the engine powering Node.js and Chrome) has built-in support for tracking code execution — no source code transformation needed.

# Enable V8 coverage in Node.js
NODE_V8_COVERAGE=./coverage node app.js

V8 tracks execution by recording which byte ranges of each script were executed. The output is a list of ranges with execution counts:

{
  "scriptId": "123",
  "url": "file:///app.js",
  "functions": [{
    "functionName": "greet",
    "ranges": [
      { "startOffset": 0, "endOffset": 150, "count": 1 },
      { "startOffset": 50, "endOffset": 80, "count": 1 },
      { "startOffset": 80, "endOffset": 120, "count": 0 }
    ]
  }]
}

Performance Comparison

Build Time

Istanbul:

Requires a separate instrumentation pass during build
Must transform every file, even those not tested
Adds overhead to build time

V8:

Zero build time overhead
No transformation needed
Code runs exactly as in production

Runtime Performance

Istanbul:

Instrumented code runs slower due to counter increments
Additional memory usage from counter objects

V8:

Minimal runtime overhead (coverage is optimized at the engine level)
Near-production performance during tests

Accuracy Comparison

Istanbul is always more accurate because it instruments your original source code before any transformation. Every line, branch, and statement is tracked exactly as you wrote it.

V8 coverage works on bundled/transformed code and relies on source maps to map back to your original files. This introduces potential inaccuracies:

Source map mappings aren't always perfect
Bundler transformations can merge or split code
Some patterns become untrackable after transformation

V8 also has specific blind spots with JSX patterns like ternary operators and logical AND expressions. We'll cover these in detail in the next article: V8 Coverage Limitations and How to Work Around Them.

When to Use Each

Use Istanbul When:

You need precise branch coverage — Every if/else, ternary, and logical operator is tracked
JSX branch coverage matters — Istanbul can track JSX conditional rendering
You're using Babel anyway — Adding istanbul plugin is trivial
Unit tests only — No multi-process complexity

Use V8 When:

Performance is critical — Near-zero overhead
Testing bundled code — Works on any output (SWC, esbuild, webpack)
E2E/integration tests — Can collect coverage across processes
Modern tooling — Works with SWC, which Istanbul doesn't support
Next.js App Router — The only option that works with Server Actions

You Can't Mix V8 and Istanbul Coverage

A common misconception: since tools like @vitest/coverage-v8 and nextcov output Istanbul-format reports, you might think you can mix V8-based and Istanbul instrumentation-based coverage.

You can't.

Even though the output format is the same (Istanbul JSON), the underlying data is fundamentally different:

Istanbul instrumentation tracks counters injected into your original source code
V8 coverage tracks byte ranges in bundled/transformed code, mapped back via source maps

When you try to merge them, the line/branch mappings don't align. The same line of code may have different coverage data structures depending on how it was collected.

The rule: Pick one approach and stick with it across all your test types.

If you use @vitest/coverage-v8 for unit tests, use nextcov for E2E tests — they can merge
If you use @vitest/coverage-istanbul for unit tests, you cannot merge with nextcov's E2E coverage

Conclusion

Neither Istanbul nor V8 coverage is universally better — they have different strengths:

Aspect	Istanbul	V8
Build overhead	Higher	None
Runtime overhead	Higher	Lower
Branch accuracy	Better	Good (with blind spots)
Bundler compatibility	Babel only	Any
Multi-process	No	Yes

For modern Next.js applications, V8 coverage is often the only practical choice because Istanbul doesn't work with SWC and Server Actions. Use @vitest/coverage-v8 for unit tests and nextcov for E2E tests — they can be merged into a unified report.

References

nextcov — Collect V8 coverage from both server and browser during Playwright E2E tests for Next.js applications
@vitest/coverage-v8 — V8 coverage provider for Vitest
Jest Issue #11188: V8 Coverage Tradeoffs — Documents V8 coverage limitations (implicit else, block-level tracking)

This is part 3 of a series on test coverage for modern React applications:

nextcov - Collecting Test Coverage for Next.js Server Components
Why Istanbul Coverage Doesn't Work with Next.js App Router
V8 Coverage vs Istanbul: Performance and Accuracy (this article)
V8 Coverage Limitations and How to Work Around Them
How to Merge Vitest Unit, Component, and E2E Test Coverage
E2E Coverage in Next.js: Dev Mode vs Production Mode

Why Istanbul Coverage Doesn't Work with Next.js App Router

Steve Zhang — Thu, 01 Jan 2026 04:06:46 +0000

If you've tried to set up code coverage for a Next.js 13+ application with the App Router, you've likely hit a wall. The traditional approach — using Istanbul with babel-plugin-istanbul — simply doesn't work anymore. Here's why, and what you can do about it.

The Traditional Approach: Istanbul + Babel

For years, Istanbul has been the standard for JavaScript code coverage. It works by instrumenting your code at build time — injecting counter variables that track which lines, branches, and functions are executed.

// Original code
function add(a, b) {
  return a + b;
}

// After Istanbul instrumentation
function add(a, b) {
  cov_1234.f[0]++;  // Function counter
  cov_1234.s[0]++;  // Statement counter
  return a + b;
}

This approach requires a Babel plugin (babel-plugin-istanbul) to transform your code during the build process. It worked great with Create React App, older Next.js versions, and any project using Babel as its compiler.

The Problem: Next.js Moved to SWC

Starting with Next.js 12, and becoming the default in Next.js 13+, the framework switched from Babel to SWC (Speedy Web Compiler) for transpilation. SWC is written in Rust and is significantly faster than Babel.

But here's the catch: Istanbul's instrumentation plugin only works with Babel.

When you try to add a .babelrc file to enable Istanbul, Next.js detects it and falls back to Babel — but this:

Disables SWC's performance benefits
Can break other SWC-dependent features
Often causes configuration conflicts with Next.js's internal setup

The App Router Makes It Worse

Next.js 13 introduced the App Router with React Server Components (RSC). You might think: "I'll just add a .babelrc and force Babel mode." But the App Router creates a critical problem:

Server Actions Break with Babel

When you enable Babel in a Next.js project that uses Server Actions, the build fails. Server Actions require special compiler handling that SWC provides but Babel doesn't support correctly.

// app/actions.ts
'use server'

export async function submitForm(formData: FormData) {
  await db.insert(formData);
}

Try to build this with a .babelrc file present:

$ npm run build
# Build fails with Server Action compilation errors

This isn't a configuration issue — it's a fundamental incompatibility. Next.js's Server Action transformation relies on SWC-specific features that babel-plugin-istanbul can't work with.

The Catch-22

You're stuck in an impossible situation:

Istanbul requires Babel → Add .babelrc to enable instrumentation
Server Actions require SWC → Build fails with Babel enabled
No coverage for Server Actions → Can't measure what your E2E tests exercise

The Common Workaround: Skip E2E Coverage Entirely

Many teams simply give up on E2E coverage and rely only on unit tests:

Unit tests (Vitest/Jest) → Istanbul coverage ✓
E2E tests (Playwright/Cypress) → No coverage ✗

Problems:

Server Components remain completely untested for coverage
No visibility into what E2E tests actually exercise
Coverage reports show artificially low numbers

The Solution: V8 Native Coverage

The fundamental issue is that Istanbul requires pre-instrumentation of source code. But there's another approach: runtime coverage collection.

V8, the JavaScript engine that powers Node.js and Chrome, has built-in coverage support. It tracks code execution at the engine level — no instrumentation needed.

How V8 Coverage Works

For Node.js (server): Set NODE_V8_COVERAGE=./coverage environment variable
For Chrome (browser): Use Chrome DevTools Protocol (CDP) to enable coverage
After tests: Read the coverage data from V8's native format

This approach works with any bundler, any compiler (Babel, SWC, esbuild), and any framework. The code runs exactly as it would in production — V8 just tracks what gets executed.

The Critical Role of Source Maps

There's one catch: V8 coverage reports line/column positions in the bundled code, not your original TypeScript/JSX files. To get meaningful coverage reports, you need source maps.

// next.config.ts
const nextConfig = {
  productionBrowserSourceMaps: !!process.env.E2E_MODE,
  webpack: (config, { isServer }) => {
    if (process.env.E2E_MODE) {
      config.devtool = 'source-map'
    }
    return config
  },
}

export default nextConfig

Then build with the environment variable:

E2E_MODE=true npm run build

With source maps, the coverage tool can:

Map bundled code positions back to original source files
Show coverage for your TypeScript/JSX, not minified JavaScript
Produce reports that reference your actual codebase

This is why nextcov requires source maps in your production build — without them, you'd only see coverage for unreadable bundled code.

V8 Coverage with Next.js

For Next.js applications, you need to collect coverage from multiple processes:

Process	Coverage Method
Next.js Server (RSC, Server Actions)	`NODE_V8_COVERAGE` env var
Browser (Client Components)	Playwright CDP integration
Test Runner	Orchestrates collection

This is exactly what nextcov does. It:

Collects V8 coverage from both server and browser during Playwright E2E tests
Uses source maps to map bundled code back to original TypeScript/JSX
Converts V8 format to Istanbul format for familiar reports
Merges with unit test coverage for a complete picture

Getting Started with V8 Coverage

If you're ready to move beyond Istanbul for your Next.js App Router application:

npm install nextcov --save-dev
npx nextcov init

The init command sets up everything you need:

Global setup/teardown for Playwright
CDP connection to Next.js server
Source map processing
Report generation

Then run your E2E tests:

# Build with source maps
E2E_MODE=true npm run build

# Start server with coverage and run tests
NODE_V8_COVERAGE=.v8-coverage NODE_OPTIONS='--inspect=9230' npm start &
npx playwright test

Conclusion

Istanbul served us well for over a decade, but the JavaScript ecosystem has evolved. With:

SWC replacing Babel as the default compiler
Server Actions requiring SWC-specific transformations that break Babel

...it's time for a new approach.

V8 native coverage works with modern tooling, not against it. It collects accurate coverage data from both client and server without requiring any code transformation.

If you're building with Next.js App Router and want complete coverage visibility, check out nextcov.

This is part 2 of a series on test coverage for modern React applications:

nextcov - Collecting Test Coverage for Next.js Server Components
Why Istanbul Coverage Doesn't Work with Next.js App Router (this article)
V8 Coverage vs Istanbul: Performance and Accuracy
V8 Coverage Limitations and How to Work Around Them
How to Merge Vitest Unit, Component, and E2E Test Coverage
E2E Coverage in Next.js: Dev Mode vs Production Mode

nextcov - Collecting Test Coverage for Next.js Server Components

Steve Zhang — Thu, 01 Jan 2026 01:51:51 +0000

📝 UPDATE (January 2025):

As of nextcov@1.1.0 with ast-v8-to-istanbul@0.3.10:

JSX branch coverage now works! Ternary (? :) and logical AND (&&) patterns in JSX now have proper branch coverage tracking

The nextcov check command now only checks project configuration (not JSX patterns)

These were not V8 limitations but bugs in the V8-to-Istanbul conversion that are now fixed

If you've ever tried to get test coverage for React Server Components, you know the frustration. Unit testing frameworks like Jest and Vitest can't render server components — they require the full Next.js runtime. So you write E2E tests with Playwright, but then you're left wondering: "What's actually being covered?"

nextcov solves this problem by collecting V8 coverage from both client and server during Playwright E2E tests, then merging it with your unit and component test coverage for a complete picture.

The Testing Landscape in 2025

Modern Next.js applications have three layers that need testing:

Layer	What to Test	Best Tool
Utilities & Hooks	Pure functions, custom hooks	Vitest (unit tests)
Client Components	React components with user interaction	Vitest Browser Mode (component tests)
Server Components	RSC, server actions, full pages	Playwright (E2E tests)

Vitest Browser Mode — Great for Client Components

Vitest's Browser Mode is excellent for component testing. It runs tests in a real browser, giving you accurate DOM behavior and event handling. Combined with @vitest/coverage-v8, you get proper coverage for your client components.

But there's a limitation: Vitest Browser Mode only works for client components. Server components require the full Next.js runtime — they can't be rendered in isolation.

The Server Component Gap

React Server Components (RSC) are notoriously difficult to test:

They run only on the server — Can't be rendered in jsdom or even a real browser
Async components fetch data directly — Mocking becomes complex and unreliable
Tight coupling with Next.js runtime — Server actions, cookies, headers require the full framework

The practical solution? Test server components through E2E tests with Playwright, where they run in their natural environment.

But this creates a coverage gap. You have coverage from unit tests, coverage from component tests... but nothing from E2E tests.

nextcov Fills the Gap

nextcov completes the coverage picture by collecting V8 coverage during Playwright E2E tests:

Test Type	Coverage Tool	What It Covers
Unit (Vitest)	@vitest/coverage-v8	Utilities, hooks, logic
Component (Vitest Browser)	@vitest/coverage-v8	Client components
E2E (Playwright)	nextcov	Server components, pages, user flows

And the best part? nextcov merges all three into a single unified report.

Real Results

In a production Next.js application:

Coverage Type	Lines
Unit Tests	~45%
Component Tests	~35%
E2E Tests (nextcov)	~46%
Merged	~88%

Each test type contributes coverage that others can't reach. The merged report shows exactly what's tested and what's not.

How It Works

Unlike traditional coverage tools that work within a single Node.js process, nextcov coordinates coverage collection across three separate environments:

Test Runner (Playwright) — orchestrates tests
Next.js Server (Node.js) — runs server components
Browser (Chromium) — runs client components

For the browser, nextcov uses Playwright's CDP integration to collect V8 coverage. For the server, it uses Node.js's built-in NODE_V8_COVERAGE environment variable, triggered via Chrome DevTools Protocol.

This multi-process approach is what makes nextcov unique compared to tools like c8 or @vitest/coverage-v8, which only work within a single process.

Quick Start

# Install
npm install nextcov --save-dev

# Interactive setup
npx nextcov init

The init command creates all the necessary configuration files:

e2e/global-setup.ts — Initialize coverage collection
e2e/global-teardown.ts — Finalize and generate reports
e2e/fixtures/test-fixtures.ts — Playwright fixture for per-test coverage
Updates to playwright.config.ts and next.config.ts

Then run your E2E tests with coverage:

# Build with source maps
E2E_MODE=true npm run build

# Start server with coverage enabled and run tests
NODE_V8_COVERAGE=.v8-coverage NODE_OPTIONS='--inspect=9230' npm start &
npx playwright test

Merging All Coverage

The real power comes from merging E2E coverage with your unit and component test coverage:

# Merge all coverage sources
npx nextcov merge coverage/unit coverage/component coverage/e2e -o coverage/merged

This produces a unified HTML report showing the complete coverage picture — what's covered by unit tests, component tests, E2E tests, and what's still missing.

Checking Project Configuration

nextcov includes a check command to validate your project configuration for common issues that affect V8 coverage:

npx nextcov check

The check command detects:

Missing or outdated browserslist — Can cause phantom branches from transpiled ?. and ?? operators
Babel configuration — May transpile modern syntax and break V8 coverage mapping
Source maps not enabled — Required for mapping bundled code back to source
Missing dependencies — Playwright or Vitest not installed

Example output:

Project Configuration:
────────────────────────────────────────────────────────────
  ⚠ Missing browserslist - ?? and ?. operators may be transpiled, causing phantom branches
  ⚠ Source maps not enabled in next.config - add productionBrowserSourceMaps: true
    next.config.ts

Note: Prior to v1.1.0, the check command also scanned for JSX patterns (ternary and logical AND) that V8 couldn't track. As of v1.1.0 with ast-v8-to-istanbul@0.3.10, these patterns now have proper branch coverage, so JSX scanning has been removed.

The Complete Testing Strategy

Here's the recommended approach for Next.js applications:

Unit tests (Vitest) — Test utilities, hooks, and pure logic
Component tests (Vitest Browser Mode) — Test client components in isolation
E2E tests (Playwright + nextcov) — Test server components, pages, and user flows
Merge coverage — Get the complete picture with nextcov merge

This gives you fast feedback from unit and component tests during development, comprehensive E2E tests for critical user flows, and a unified coverage report that shows exactly what's tested.

Features

Next.js + Vite support — Works with both frameworks
Client + Server coverage — Browser and Node.js in one report
Dev mode support — Works with next dev (no production build required)
Auto-detection — Automatically detects dev vs production mode
Source map support — Maps bundled code back to original TypeScript/JSX
Multi-source merge — Combine unit, component, and E2E coverage
Config validation — Check project configuration with nextcov check
Multiple reporters — HTML, LCOV, JSON, text-summary

Try It Out

GitHub: https://github.com/stevez/nextcov
npm: https://www.npmjs.com/package/nextcov
Example Project: https://github.com/stevez/nextcov-example

If you're building a Next.js application and want complete test coverage visibility across unit, component, and E2E tests, give nextcov a try.

This is part 1 of a series on test coverage for modern React applications:

nextcov - Collecting Test Coverage for Next.js Server Components (this article)
Why Istanbul Coverage Doesn't Work with Next.js App Router
V8 Coverage vs Istanbul: Performance and Accuracy
V8 Coverage Limitations and How to Work Around Them
How to Merge Vitest Unit, Component, and E2E Test Coverage
E2E Coverage in Next.js: Dev Mode vs Production Mode

Forem: Steve Zhang

I Built a VS Code Extension That Turns Playwright Into an Interactive REPL

The workflow: Record → Pick → Assert → Run

Launch Browser

REPL Panel

Pick Locator

Assert Builder

Recorder

Run Tests

How it works

Browser reuse: one browser for everything

Built on Playwright Test for VS Code

Getting started

What's next

How Fast Can Browser Automation Be? I Benchmarked 3 Approaches

The Setup

The Results

What's Going On?

playwright-cli: ~200ms baseline + action overhead

Standalone: fast queries, slow actions

Bridge: fast everything

Why Queries Are Fast Everywhere

The Real-World Impact

Try It

Let AI Control Your Real Browser — Not a Throwaway One

How it works

Just two tools

Keyword syntax (.pw)

Playwright API (JavaScript)

AI Agents that actually verify their work

Setup

1. Install

2. Configure Claude Desktop

3. Install the AI agents (optional)

4. That's it

Example prompts

Human + AI, side by side

vs. other browser MCP servers

Try it

I Put Playwright Inside a Chrome Side Panel — Console, Recorder, and Debugger Included

What is Dramaturg?

The debugger that nobody asked for (but I needed)

How it works under the hood

Console — Chrome DevTools, but for Playwright

Recorder — watch commands write themselves

Pick Element — point and click locators

More features

Why not just use Playwright Test?

Try it

playwright-repl: Browser Automation From Your Terminal, No Code Required

What does it look like?

Why not just use Playwright's codegen?

Text locators: just say what you see

Record and replay

Assertions built in

50+ commands, short aliases

How it works under the hood

Use it in CI

Get started

Chrome DevTools extension

Links

E2E Coverage in Next.js: Dev Mode vs Production Mode

Dev Mode

How It Works

Running Dev Mode

Dev Mode Characteristics

Production Mode

How It Works

Running Production Mode

Production Mode Characteristics

Comparison

Auto-Detection

Same Output, Different Paths

Summary

References

How to Merge Vitest Unit, Component, and E2E Test Coverage

Tech Stack

The Problem: Separate Coverage Reports

Why Naive Merging Fails

Setting Up Separate Coverage Directories

`playwright-cli`: ~200ms baseline + action overhead

Keyword syntax (`.pw`)