Oxc Coverage Instrument

Status: v0.3.x, published to crates.io and npm

Who is this for? Only projects using coverage.provider: 'istanbul' in Vitest (or any other source-instrumentation pipeline). If you're on Vitest's default provider: 'v8', this tool does not apply - V8 coverage is collected by the engine at runtime and never goes through a source-rewriting step.

OverviewLink to heading: Overview

  • Istanbul-compatible coverage instrumentation built on the Oxc parser
  • Fills a real gap: any tool on oxc_parser previously had to pull in SWC or Babel to emit coverage
  • Verified against istanbul-lib-instrument on 25 shared fixtures and 1,061 real TS/TSX/JS files from a production React monorepo
  • Ships a Rust crate, Node.js bindings (napi-rs, 7 platform binaries), and a standalone CLI
  • Vitest integration via createOxcInstrumenter - the coverage.instrumenter option shipped experimentally in Vitest 4.1.5, with stabilization planned for 5.0

PerformanceLink to heading: Performance

8-11x faster than babel-plugin-istanbul, 13-15x faster than swc-plugin-coverage-instrument (Rust/WASM), 25-30x faster than istanbul-lib-instrument - measured end-to-end on real libraries (React, lodash, vue, d3, three).

Known Issues & TradeoffsLink to heading: Known Issues & Tradeoffs

  • Two intentional divergences from istanbul: ??=/||=/&&= are instrumented as branches, and inferred function names replace (anonymous_N). Both are supersets - a codebase using logical-assignment heavily will see a lower branch % after switching.
  • Vitest's coverage.instrumenter option is documented and usable in 4.1.5+, but flagged experimental until 5.0 - the surface may shift before then
  • Operator-level branch channel (bO) deferred until a mainstream reporter consumes it
  • Source-instrumentation path only - no V8-coverage equivalent in the Oxc ecosystem yet (see below)

Adoption ConsiderationsLink to heading: Adoption Considerations

  • New Projects: strong drop-in candidate if you're on Vitest 4.1.5+ with the Istanbul provider - wire it in via the experimental custom-instrumenter API today, expect a stable surface in Vitest 5.0
  • Existing Projects: rebaseline branch-coverage thresholds before swapping - the ??= family adds real branches that previously went uncounted
  • Watch oxc#21108 for a possible transfer to the Oxc org

V8 coverage contextLink to heading: V8 coverage context

oxc-coverage-instrument lives on the source-instrumentation path (the Istanbul lineage). The parallel V8-coverage path - runtime collection via the Inspector protocol - is a separate ecosystem worth knowing about when picking a coverage strategy:

  • @vitest/coverage-v8 is the actively maintained V8 provider; since v3.2.0 it uses AST-based remapping that produces Istanbul-equivalent reports, closing the historical "V8 is faster but less precise" gap
  • c8 still works but is in maintenance mode; Vitest docs now point at @vitest/coverage-v8 instead
  • Node 22+ ships --experimental-test-coverage with built-in lcov/text reporters - usable but emits raw V8 output, so third-party tools are still needed for Istanbul normalization
  • The bridge - v8-to-istanbul - is the only converter from V8's raw output to Istanbul format. 40M weekly downloads, but no npm release in 12+ months and minimal PR activity. No Rust-native replacement exists, which is the obvious next gap for the Oxc ecosystem to fill.

ResourcesLink to heading: Resources