@rpcbase/test 0.176.0 → 0.178.0

package/README.md

@@ -0,0 +1,103 @@
+# @rpcbase/test helpers
+
+`@rpcbase/test` ships the shared Playwright wiring we use across RPCBase packages: a preconfigured `test`/`expect`, automatic V8 coverage collection, and the `rb-test` CLI.
+
+## 1. Declare your coverage config
+
+Create `spec/coverage.ts` (or `.js` / `.json`) in your package:
+
+```ts
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const workspaceRoot = path.resolve(fileURLToPath(new URL("../", import.meta.url)))
+
+export default {
+  workspaceRoot,
+  libDirs: ["lib"],
+  testResultsDir: "test-results",
+  thresholds: {
+    statements: 75,
+    lines: 75,
+    functions: 75,
+    branches: 60,
+  },
+}
+```
+
+Only `RB_DISABLE_COVERAGE=1` skips the hooks; every other option lives inside this config file.
+
+### Per-folder thresholds
+
+Need stricter coverage in a sub-tree? Extend the same `thresholds` object with glob keys (mirroring Jest's `coverageThreshold` syntax):
+
+```ts
+export default {
+  workspaceRoot,
+  thresholds: {
+    global: {
+      statements: 90,
+      lines: 85,
+      functions: 85,
+      branches: 70,
+    },
+    "lib/core/**": {
+      statements: 98,
+      lines: 95,
+    },
+    "lib/components/**": {
+      functions: 92,
+    },
+  },
+}
+```
+
+- When `thresholds` only has metric keys, it behaves exactly like before.
+- Adding `thresholds.global` lets you keep a default floor while overriding specific directories.
+- Globs run against POSIX-style paths relative to `workspaceRoot`, but absolute paths work too if you prefer.
+- Metrics you omit inside an override inherit from the global thresholds (or the 75/75/75/60 defaults).
+- If a glob matches no files you'll get a warning and the override is skipped, so typos are easy to spot.
+
+## 2. Import `test` / `expect` directly
+
+```ts
+// spec/my-component.spec.ts
+import { test, expect } from "@rpcbase/test"
+
+test("renders", async ({ page }) => {
+  await page.goto("/playground")
+  await expect(page.locator("button"))..toBeVisible()
+})
+```
+
+The exported `test` already records coverage via CDP and writes per-test payloads automatically.
+
+## 3. Build your Playwright config via the shared wrapper
+
+```ts
+// playwright.config.ts
+import { defineConfig, devices } from "@rpcbase/test"
+
+export default defineConfig({
+  testDir: "./spec",
+  reporter: [["list"]],
+  use: {
+    baseURL: "http://localhost:9198",
+    launchOptions: { headless: true },
+  },
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+})
+```
+
+Whenever coverage is enabled, the wrapper appends the shared reporter so Istanbul aggregation + threshold enforcement run after the suite.
+
+## 4. Run tests with `rb-test`
+
+Each package keeps its `npm test` script as `tsc --noEmit && rb-test`. The CLI wraps Playwright’s binary, applies the repo defaults, and prints failures cleanly inside the Codex harness.
+
+Need to debug without coverage? Set `RB_DISABLE_COVERAGE=1 npm test` and the hooks short-circuit.

package/index.d.ts

@@ -0,0 +1,63 @@
+export * from "playwright/test"
+
+interface CoverageThresholds {
+  branches: number
+  functions: number
+  lines: number
+  statements: number
+}
+
+type CoverageThresholdMap = {
+  global?: Partial<CoverageThresholds>
+  [pattern: string]: Partial<CoverageThresholds> | number | undefined
+}
+
+type CoverageThresholdOption = Partial<CoverageThresholds> | CoverageThresholdMap
+
+interface CoverageThresholdTarget {
+  id: string
+  pattern: string
+  thresholds: CoverageThresholds
+}
+
+interface CoverageHarnessOptions {
+  workspaceRoot: string
+  libDirs?: string[]
+  testResultsDir?: string
+  coverageReportSubdir?: string
+  coverageFileName?: string
+  envPrefix?: string
+  thresholds?: CoverageThresholdOption
+  disabledEnvVar?: string
+}
+
+interface CoverageConfig extends CoverageHarnessOptions {
+  libRoots: string[]
+  testResultsRoot: string
+  coverageReportDir: string
+  coverageFileName: string
+  thresholds: CoverageThresholds
+  thresholdTargets: CoverageThresholdTarget[]
+  coverageEnabled: boolean
+  disabledEnvVar: string
+}
+
+interface CoverageHarness {
+  config: CoverageConfig
+  globalSetup(...args: any[]): Promise<void>
+  extendTest<T>(baseTest: T): T
+  reporterEntry(): [string, Record<string, unknown>?]
+}
+
+export function clearDatabase(dbName: string): Promise<void>
+export function createCoverageHarness(options: CoverageHarnessOptions): CoverageHarness
+export function createCoverageConfig(options: CoverageHarnessOptions): CoverageConfig
+
+export type {
+  CoverageHarness,
+  CoverageHarnessOptions,
+  CoverageConfig,
+  CoverageThresholds,
+  CoverageThresholdOption,
+  CoverageThresholdTarget,
+}

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "@rpcbase/test",
-  "version": "0.176.0",
+  "version": "0.178.0",
   "type": "module",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
   "bin": {
     "rb-test": "./src/cli.js"
   },
@@ -36,9 +44,16 @@
     }
   },
   "dependencies": {
-    "@playwright/test": "1.55.0",
+    "@playwright/test": "1.56.1",
+    "esbuild": "0.24.0",
+    "istanbul-lib-coverage": "3.2.2",
+    "istanbul-lib-report": "3.0.1",
+    "istanbul-reports": "3.1.6",
     "lodash": "4.17.21",
-    "mongoose": "8.18.0"
+    "mongoose": "8.18.0",
+    "picomatch": "2.3.1",
+    "v8-to-istanbul": "9.2.0"
   },
+  "peerDependencies": {},
   "devDependencies": {}
 }

package/src/cli.js

@@ -3,6 +3,12 @@
 import { spawn } from "child_process"
 import fs from "fs"
 import path from "path"
+import { createRequire } from "module"
+import { fileURLToPath } from "url"
+
+
+const require = createRequire(import.meta.url)
+const moduleDir = path.dirname(fileURLToPath(import.meta.url))
 
 
 const isAider = process.env.IS_AIDER === "yes"
@@ -20,7 +26,7 @@ function runTests() {
       path.join(process.cwd(), "playwright.config.ts"),
     )
       ? path.join(process.cwd(), "playwright.config.ts")
-      : path.join(__dirname, "playwright.config.ts")
+      : path.join(moduleDir, "playwright.config.ts")
 
     const hasCustomConfig = userArgs.some((arg) => {
       if (arg === "--config" || arg === "-c") {
@@ -41,11 +47,19 @@ function runTests() {
     const stdoutBuffer = []
     const stderrBuffer = []
 
+    ensureJsxRuntimeShim(process.cwd())
+    const launcher = resolvePlaywrightLauncher()
+    const nodeOptions = appendNodeRequire(process.env.NODE_OPTIONS, path.join(moduleDir, "register-tty.cjs"))
+    const env = {
+      ...process.env,
+      NODE_OPTIONS: nodeOptions,
+    }
     const playwright = spawn(
-      "./node_modules/.bin/playwright",
-      playwrightArgs,
+      launcher.command,
+      [...launcher.args, ...playwrightArgs],
       {
         shell: false,
+        env,
       },
     )
 
@@ -94,3 +108,69 @@ function runTests() {
 runTests()
   .then(() => process.exit(0))
   .catch(() => process.exit(1))
+
+function resolvePlaywrightLauncher() {
+  const cliPath = resolveCliPath()
+  if (cliPath) {
+    return {
+      command: process.execPath,
+      args: [cliPath],
+    }
+  }
+
+  const localBin = path.resolve(process.cwd(), "node_modules/.bin/playwright")
+  if (fs.existsSync(localBin)) {
+    return {
+      command: localBin,
+      args: [],
+    }
+  }
+
+  return {
+    command: "playwright",
+    args: [],
+  }
+}
+
+function resolveCliPath() {
+  const searchRoots = [process.cwd(), moduleDir]
+
+  for (const base of searchRoots) {
+    try {
+      const pkgPath = require.resolve("@playwright/test/package.json", { paths: [base] })
+      const cliPath = path.join(path.dirname(pkgPath), "cli.js")
+      if (fs.existsSync(cliPath)) {
+        return cliPath
+      }
+    } catch (_error) {
+      // continue searching
+    }
+  }
+
+  return null
+}
+
+function ensureJsxRuntimeShim(projectRoot) {
+  const shimDir = path.join(projectRoot, "node_modules", "playwright")
+  fs.mkdirSync(shimDir, { recursive: true })
+  const shims = [
+    { file: "jsx-runtime.js", target: "react/jsx-runtime" },
+    { file: "jsx-dev-runtime.js", target: "react/jsx-dev-runtime" },
+  ]
+
+  for (const { file, target } of shims) {
+    const filePath = path.join(shimDir, file)
+    if (!fs.existsSync(filePath)) {
+      const content = `export * from "${target}";\nexport { default } from "${target}";\n`
+      fs.writeFileSync(filePath, content, "utf8")
+    }
+  }
+}
+
+function appendNodeRequire(existing, modulePath) {
+  const flag = `--require=${modulePath}`
+  if (!existing || existing.length === 0) {
+    return flag
+  }
+  return `${existing} ${flag}`
+}

package/src/coverage/config-loader.js

@@ -0,0 +1,121 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+import os from "node:os"
+import crypto from "node:crypto"
+import { pathToFileURL } from "node:url"
+
+import { build } from "esbuild"
+
+
+const COVERAGE_CANDIDATES = [
+  "spec/coverage.ts",
+  "spec/coverage.mts",
+  "spec/coverage.cts",
+  "spec/coverage.js",
+  "spec/coverage.mjs",
+  "spec/coverage.cjs",
+  "spec/coverage.json",
+]
+
+export async function loadCoverageOptions() {
+  const projectRoot = process.cwd()
+  const resolved = await findCoverageFile(projectRoot)
+
+  if (!resolved) {
+    throw new Error(
+      "Coverage config not found. Create one of: spec/coverage.{ts,js,json} with your coverage settings.",
+    )
+  }
+
+  const raw = await importCoverageModule(resolved)
+  if (!raw || typeof raw !== "object") {
+    throw new Error(`Coverage config at ${resolved} must export an object.`)
+  }
+
+  return normalizeOptions(raw, resolved)
+}
+
+async function findCoverageFile(root) {
+  for (const relative of COVERAGE_CANDIDATES) {
+    const candidate = path.resolve(root, relative)
+    try {
+      await fs.access(candidate)
+      return candidate
+    } catch {
+      // continue
+    }
+  }
+  return null
+}
+
+async function importCoverageModule(filePath) {
+  const ext = path.extname(filePath)
+
+  if (ext === ".json") {
+    const raw = await fs.readFile(filePath, "utf8")
+    return JSON.parse(raw)
+  }
+
+  if ([".ts", ".mts", ".cts"].includes(ext)) {
+    const compiledUrl = await compileTsModule(filePath)
+    return loadModule(compiledUrl)
+  }
+
+  const moduleUrl = pathToFileURL(filePath).href
+  return loadModule(moduleUrl)
+}
+
+async function compileTsModule(filePath) {
+  const stat = await fs.stat(filePath)
+  const hash = crypto
+    .createHash("sha1")
+    .update(filePath)
+    .update(String(stat.mtimeMs))
+    .digest("hex")
+
+  const outDir = path.join(os.tmpdir(), "rpcbase-test")
+  await fs.mkdir(outDir, { recursive: true })
+  const outfile = path.join(outDir, `coverage-${hash}.mjs`)
+
+  await build({
+    entryPoints: [filePath],
+    outfile,
+    platform: "node",
+    format: "esm",
+    bundle: false,
+    sourcemap: "inline",
+    logLevel: "silent",
+  })
+
+  return pathToFileURL(outfile).href
+}
+
+async function loadModule(url) {
+  const imported = await import(url)
+  if (imported && typeof imported.default === "object") {
+    return imported.default
+  }
+  return imported
+}
+
+function normalizeOptions(rawOptions, filePath) {
+  const options = { ...rawOptions }
+  const configDir = path.dirname(filePath)
+
+  const workspaceRoot = path.resolve(
+    options.workspaceRoot ? path.resolve(configDir, options.workspaceRoot) : process.cwd(),
+  )
+
+  const libDirs = Array.isArray(options.libDirs) && options.libDirs.length > 0
+    ? options.libDirs.map((entry) => path.resolve(workspaceRoot, entry))
+    : [path.resolve(workspaceRoot, "lib")]
+
+  return {
+    workspaceRoot,
+    libDirs,
+    testResultsDir: options.testResultsDir ?? "test-results",
+    coverageReportSubdir: options.coverageReportSubdir ?? "coverage",
+    coverageFileName: options.coverageFileName ?? "v8-coverage.json",
+    thresholds: options.thresholds ?? {},
+  }
+}

package/src/coverage/config.js

@@ -0,0 +1,130 @@
+import path from "node:path"
+
+
+const DEFAULT_THRESHOLDS = {
+  branches: 60,
+  functions: 75,
+  lines: 75,
+  statements: 75,
+}
+
+const THRESHOLD_KEYS = Object.keys(DEFAULT_THRESHOLDS)
+
+function resolveDir(root, target, fallback) {
+  if (!target) {
+    return path.resolve(root, fallback)
+  }
+
+  if (path.isAbsolute(target)) {
+    return target
+  }
+
+  return path.resolve(root, target)
+}
+
+export function createCoverageConfig(options = {}) {
+  const { workspaceRoot } = options
+  if (!workspaceRoot) {
+    throw new Error("createCoverageConfig requires a workspaceRoot")
+  }
+
+  const resolvedWorkspaceRoot = path.resolve(workspaceRoot)
+
+  const libDirs = Array.isArray(options.libDirs) && options.libDirs.length > 0
+    ? options.libDirs
+    : ["lib"]
+
+  const libRoots = libDirs.map((dir) =>
+    path.isAbsolute(dir) ? path.normalize(dir) : path.resolve(resolvedWorkspaceRoot, dir),
+  )
+
+  const testResultsRoot = resolveDir(resolvedWorkspaceRoot, options.testResultsDir, "test-results")
+  const coverageReportDir = resolveDir(testResultsRoot, options.coverageReportSubdir, "coverage")
+  const coverageFileName = options.coverageFileName ?? "v8-coverage.json"
+  const disabledEnvVar = options.disabledEnvVar ?? "RB_DISABLE_COVERAGE"
+  const coverageEnabled = process.env[disabledEnvVar] !== "1"
+
+  const { global: thresholds, targets: thresholdTargets } = normalizeThresholdOptions(options.thresholds)
+
+  return {
+    workspaceRoot: resolvedWorkspaceRoot,
+    libRoots,
+    testResultsRoot,
+    coverageReportDir,
+    coverageFileName,
+    thresholds,
+    thresholdTargets,
+    coverageEnabled,
+    disabledEnvVar,
+  }
+}
+
+function normalizeThresholdOptions(rawThresholds) {
+  const globalThresholds = { ...DEFAULT_THRESHOLDS }
+  const targets = []
+
+  if (!isPlainObject(rawThresholds)) {
+    return { global: globalThresholds, targets }
+  }
+
+  for (const key of THRESHOLD_KEYS) {
+    const value = rawThresholds[key]
+    if (isThresholdValue(value)) {
+      globalThresholds[key] = value
+    }
+  }
+
+  if (Object.prototype.hasOwnProperty.call(rawThresholds, "global")) {
+    if (!isPlainObject(rawThresholds.global)) {
+      throw new Error("coverage thresholds: the `global` override must be an object of metric values")
+    }
+    Object.assign(globalThresholds, pickThresholdOverrides(rawThresholds.global))
+  }
+
+  for (const [pattern, overrides] of Object.entries(rawThresholds)) {
+    if (pattern === "global" || THRESHOLD_KEYS.includes(pattern)) {
+      continue
+    }
+
+    if (!isPlainObject(overrides)) {
+      throw new Error(
+        `coverage thresholds: override for "${pattern}" must be an object containing coverage metrics`,
+      )
+    }
+
+    targets.push({
+      id: pattern,
+      pattern,
+      thresholds: {
+        ...globalThresholds,
+        ...pickThresholdOverrides(overrides),
+      },
+    })
+  }
+
+  return { global: globalThresholds, targets }
+}
+
+function pickThresholdOverrides(source) {
+  const overrides = {}
+  if (!isPlainObject(source)) {
+    return overrides
+  }
+
+  for (const key of THRESHOLD_KEYS) {
+    const value = source[key]
+    if (isThresholdValue(value)) {
+      overrides[key] = value
+    }
+  }
+
+  return overrides
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+}
+
+function isThresholdValue(value) {
+  return typeof value === "number" && Number.isFinite(value)
+}

package/src/coverage/files.js

@@ -0,0 +1,55 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+
+export async function findCoverageFiles(config, root = config.testResultsRoot) {
+  const files = []
+
+  async function walk(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true })
+    await Promise.all(
+      entries.map(async (entry) => {
+        const entryPath = path.join(current, entry.name)
+        if (entry.isDirectory()) {
+          await walk(entryPath)
+        } else if (entry.isFile() && entry.name === config.coverageFileName) {
+          files.push(entryPath)
+        }
+      }),
+    )
+  }
+
+  try {
+    const stats = await fs.stat(root)
+    if (!stats.isDirectory()) {
+      return []
+    }
+  } catch {
+    return []
+  }
+
+  await walk(root)
+  return files.sort()
+}
+
+export async function removeCoverageFiles(config, root = config.testResultsRoot) {
+  async function walk(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true })
+    await Promise.all(
+      entries.map(async (entry) => {
+        const entryPath = path.join(current, entry.name)
+        if (entry.isDirectory()) {
+          await walk(entryPath)
+        } else if (entry.isFile() && entry.name === config.coverageFileName) {
+          await fs.rm(entryPath, { force: true })
+        }
+      }),
+    )
+  }
+
+  try {
+    await walk(root)
+  } catch {
+    // ignore cleanup errors
+  }
+}

package/src/coverage/fixtures.js

@@ -0,0 +1,33 @@
+import { createCoverageTracker } from "./v8-tracker.js"
+
+
+function noopTracker() {
+  return {
+    async stop() {
+      // no-op
+    },
+  }
+}
+
+export function createCoverageFixtures(baseTest, config) {
+  return baseTest.extend({
+    page: async ({ page }, use, testInfo) => {
+      let tracker = noopTracker()
+
+      if (config.coverageEnabled) {
+        try {
+          tracker = await createCoverageTracker(page, config)
+        } catch (error) {
+          console.warn("[coverage] failed to initialize V8 coverage:", error)
+        }
+      }
+
+      try {
+        // eslint-disable-next-line react-hooks/rules-of-hooks
+        await use(page)
+      } finally {
+        await tracker.stop(testInfo)
+      }
+    },
+  })
+}

package/src/coverage/global-setup.js

@@ -0,0 +1,15 @@
+import fs from "node:fs/promises"
+
+import { removeCoverageFiles } from "./files.js"
+
+
+export function createCoverageGlobalSetup(config) {
+  return async function globalSetup() {
+    if (!config.coverageEnabled) {
+      return
+    }
+
+    await removeCoverageFiles(config)
+    await fs.rm(config.coverageReportDir, { recursive: true, force: true })
+  }
+}

package/src/coverage/index.js

@@ -0,0 +1,30 @@
+import { fileURLToPath } from "node:url"
+
+import { createCoverageConfig } from "./config.js"
+import { createCoverageGlobalSetup } from "./global-setup.js"
+import { createCoverageFixtures } from "./fixtures.js"
+
+
+export function createCoverageHarness(options = {}) {
+  const config = createCoverageConfig(options)
+  const globalSetup = createCoverageGlobalSetup(config)
+
+  return {
+    config,
+    globalSetup,
+    extendTest(baseTest) {
+      return createCoverageFixtures(baseTest, config)
+    },
+    reporterEntry() {
+      const reporterPath = fileURLToPath(new URL("./reporter.js", import.meta.url))
+      return [reporterPath, { coverageConfig: config }]
+    },
+  }
+}
+
+export { CoverageReporter } from "./reporter.js"
+export { createCoverageConfig } from "./config.js"
+export { generateCoverageReport } from "./report.js"
+export { createCoverageFixtures } from "./fixtures.js"
+export { createCoverageGlobalSetup } from "./global-setup.js"
+export { findCoverageFiles, removeCoverageFiles } from "./files.js"

package/src/coverage/report.js

@@ -0,0 +1,192 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+import * as libCoverage from "istanbul-lib-coverage"
+import { createContext } from "istanbul-lib-report"
+import reports from "istanbul-reports"
+import picomatch from "picomatch"
+import v8ToIstanbul from "v8-to-istanbul"
+
+import { findCoverageFiles } from "./files.js"
+
+
+const TEXT_REPORT_FILENAME = "coverage.txt"
+
+export class CoverageThresholdError extends Error {
+  constructor(message) {
+    super(message)
+    this.name = "CoverageThresholdError"
+  }
+}
+
+export async function generateCoverageReport(config) {
+  const coverageFiles = await findCoverageFiles(config)
+
+  if (coverageFiles.length === 0) {
+    console.warn("[coverage] no V8 coverage artifacts were generated")
+    return
+  }
+
+  const coverageLib = resolveCoverageLib()
+  const coverageMap = coverageLib.createCoverageMap({})
+
+  for (const file of coverageFiles) {
+    const payload = await readCoverageFile(file)
+    if (!payload) {
+      continue
+    }
+
+    for (const script of payload.scripts) {
+      await mergeScriptCoverage(coverageMap, script)
+    }
+  }
+
+  if (coverageMap.files().length === 0) {
+    console.warn("[coverage] no library files matched the coverage filters")
+    return
+  }
+
+  await fs.rm(config.coverageReportDir, { recursive: true, force: true })
+  await fs.mkdir(config.coverageReportDir, { recursive: true })
+
+  const context = createContext({
+    dir: config.coverageReportDir,
+    coverageMap,
+    defaultSummarizer: "pkg",
+  })
+
+  reports.create("text", { maxCols: process.stdout.columns ?? 120 }).execute(context)
+  reports.create("text", { file: TEXT_REPORT_FILENAME }).execute(context)
+
+  console.log(`[coverage] Full text report saved to ${path.join(config.coverageReportDir, TEXT_REPORT_FILENAME)}`)
+
+  const summary = coverageMap.getCoverageSummary()
+  enforceThresholds(summary, config.thresholds, "global")
+
+  const targets = Array.isArray(config.thresholdTargets) ? config.thresholdTargets : []
+  if (targets.length > 0) {
+    const fileSummaries = buildFileSummaries(coverageMap, config.workspaceRoot)
+    for (const target of targets) {
+      const matcher = createGlobMatcher(target.pattern)
+      const matchResult = collectTargetSummary(fileSummaries, matcher, coverageLib)
+
+      if (matchResult.matched === 0) {
+        console.warn(
+          `[coverage] threshold pattern "${target.pattern}" did not match any files — skipping`,
+        )
+        continue
+      }
+
+      enforceThresholds(matchResult.summary, target.thresholds, target.pattern)
+    }
+  }
+}
+
+async function mergeScriptCoverage(coverageMap, script) {
+  const scriptPath = script.absolutePath
+  if (!scriptPath) {
+    return
+  }
+
+  const source = script.source && script.source.length > 0
+    ? script.source
+    : await fs.readFile(scriptPath, "utf8")
+
+  const converter = v8ToIstanbul(scriptPath, 0, { source })
+  await converter.load()
+  converter.applyCoverage(script.functions)
+  coverageMap.merge(converter.toIstanbul())
+}
+
+async function readCoverageFile(file) {
+  try {
+    const raw = await fs.readFile(file, "utf8")
+    return JSON.parse(raw)
+  } catch (error) {
+    console.warn(`[coverage] failed to parse ${file}:`, error)
+    return null
+  }
+}
+
+function enforceThresholds(summary, thresholds, label = "global") {
+  const failures = []
+
+  for (const metric of Object.keys(thresholds)) {
+    const minimum = thresholds[metric]
+    const actual = summary[metric]?.pct ?? 0
+    if (actual < minimum) {
+      failures.push({ metric, actual, minimum })
+    }
+  }
+
+  if (failures.length === 0) {
+    return
+  }
+
+  const details = failures
+    .map(({ metric, actual, minimum }) => `${metric}: ${actual.toFixed(2)}% < ${minimum}%`)
+    .join("; ")
+
+  throw new CoverageThresholdError(`[coverage] thresholds not met (target: ${label}) — ${details}`)
+}
+
+function resolveCoverageLib() {
+  const candidate = libCoverage
+  if (typeof candidate.createCoverageMap === "function") {
+    return candidate
+  }
+
+  if (candidate.default && typeof candidate.default.createCoverageMap === "function") {
+    return candidate.default
+  }
+
+  throw new Error("istanbul-lib-coverage exports are unavailable")
+}
+
+function buildFileSummaries(coverageMap, workspaceRoot) {
+  const normalizedRoot = path.resolve(workspaceRoot)
+  return coverageMap.files().map((filePath) => {
+    const normalizedAbsolute = path.resolve(filePath)
+    const summary = coverageMap.fileCoverageFor(filePath).toSummary()
+    const relativePath = path.relative(normalizedRoot, normalizedAbsolute)
+    const candidates = new Set([toPosix(normalizedAbsolute)])
+
+    if (relativePath && !relativePath.startsWith("..")) {
+      const relativePosix = toPosix(relativePath)
+      candidates.add(relativePosix)
+      candidates.add(`./${relativePosix}`)
+      candidates.add(`/${relativePosix}`)
+    }
+
+    return {
+      summary,
+      candidates: Array.from(candidates),
+    }
+  })
+}
+
+function collectTargetSummary(fileSummaries, matcher, coverageLib) {
+  const summary = coverageLib.createCoverageSummary()
+  let matched = 0
+
+  for (const file of fileSummaries) {
+    if (file.candidates.some((candidate) => matcher(candidate))) {
+      summary.merge(file.summary)
+      matched += 1
+    }
+  }
+
+  return { summary, matched }
+}
+
+function createGlobMatcher(pattern) {
+  const normalized = toPosix(String(pattern ?? "")).trim()
+  if (!normalized) {
+    return () => false
+  }
+  return picomatch(normalized, { dot: true })
+}
+
+function toPosix(input) {
+  return input.split(path.sep).join("/")
+}

package/src/coverage/reporter.js

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises"
+
+import { CoverageThresholdError, generateCoverageReport } from "./report.js"
+import { removeCoverageFiles } from "./files.js"
+
+
+class CoverageReporter {
+  constructor(options = {}) {
+    this.config = options.coverageConfig
+    if (!this.config) {
+      throw new Error("CoverageReporter requires a coverageConfig option")
+    }
+  }
+
+  async onBegin() {
+    if (!this.config.coverageEnabled) {
+      return
+    }
+
+    await removeCoverageFiles(this.config)
+    await fs.rm(this.config.coverageReportDir, { recursive: true, force: true })
+  }
+
+  async onEnd(result) {
+    if (!this.config.coverageEnabled) {
+      return
+    }
+
+    try {
+      await generateCoverageReport(this.config)
+    } catch (error) {
+      if (error instanceof CoverageThresholdError) {
+        console.error(error.message)
+        setFailureExitCode(result)
+        return
+      }
+
+      throw error
+    }
+  }
+}
+
+export { CoverageReporter }
+export default CoverageReporter
+
+function setFailureExitCode(result) {
+  if (result && typeof result === "object") {
+    result.status = "failed"
+    if (typeof result.exitCode !== "number" || result.exitCode === 0) {
+      result.exitCode = 1
+    }
+  }
+
+  if (!process.exitCode || process.exitCode === 0) {
+    process.exitCode = 1
+  }
+}

package/src/coverage/v8-tracker.js

@@ -0,0 +1,172 @@
+import fs from "node:fs/promises"
+import path from "node:path"
+
+
+const VITE_FS_PREFIX = "/@fs/"
+
+export async function createCoverageTracker(page, config) {
+  const session = await page.context().newCDPSession(page)
+  const scriptMeta = new Map()
+  const sourceCache = new Map()
+
+  await session.send("Debugger.enable")
+  session.on("Debugger.scriptParsed", (event) => {
+    if (!event.url) {
+      return
+    }
+
+    const normalized = normalizeScriptUrl(event.url, config)
+    const trackable = normalized && isInsideLib(normalized.absolutePath, config.libRoots)
+
+    scriptMeta.set(event.scriptId, {
+      normalized: trackable ? normalized : null,
+      url: event.url,
+    })
+
+    if (trackable && !sourceCache.has(event.scriptId)) {
+      sourceCache.set(event.scriptId, fetchScriptSource(session, event.scriptId))
+    }
+  })
+
+  await session.send("Profiler.enable")
+  await session.send("Profiler.startPreciseCoverage", { callCount: false, detailed: true })
+
+  return {
+    async stop(testInfo) {
+      try {
+        const payload = await collectCoveragePayload(session, scriptMeta, sourceCache, testInfo, config)
+
+        if (payload.scripts.length === 0) {
+          return
+        }
+
+        const outputFile = testInfo.outputPath(config.coverageFileName)
+        await fs.mkdir(path.dirname(outputFile), { recursive: true })
+        await fs.writeFile(outputFile, JSON.stringify(payload, null, 2), "utf8")
+      } finally {
+        await shutdownSession(session)
+      }
+    },
+  }
+}
+
+async function collectCoveragePayload(session, scriptMeta, sourceCache, testInfo, config) {
+  const { result } = await session.send("Profiler.takePreciseCoverage")
+  await session.send("Profiler.stopPreciseCoverage")
+
+  const scripts = []
+
+  for (const script of result) {
+    const meta = scriptMeta.get(script.scriptId)
+    if (!meta || !meta.normalized) {
+      continue
+    }
+
+    const source = await resolveScriptSource(session, sourceCache, script.scriptId)
+    scripts.push({
+      absolutePath: meta.normalized.absolutePath,
+      relativePath: meta.normalized.relativePath,
+      source,
+      functions: script.functions,
+      url: meta.url,
+    })
+  }
+
+  return {
+    testId: testInfo.titlePath.join(" › "),
+    scripts,
+  }
+}
+
+async function resolveScriptSource(session, cache, scriptId) {
+  const cached = cache.get(scriptId)
+  if (cached) {
+    return cached
+  }
+
+  const promise = fetchScriptSource(session, scriptId)
+  cache.set(scriptId, promise)
+  return promise
+}
+
+async function fetchScriptSource(session, scriptId) {
+  const sourceResponse = await session.send("Debugger.getScriptSource", { scriptId })
+  return sourceResponse?.scriptSource ?? ""
+}
+
+async function shutdownSession(session) {
+  await Promise.allSettled([
+    session.send("Profiler.stopPreciseCoverage").catch(() => undefined),
+    session.send("Profiler.disable").catch(() => undefined),
+    session.send("Debugger.disable").catch(() => undefined),
+  ])
+  await session.detach().catch(() => undefined)
+}
+
+function normalizeScriptUrl(rawUrl, config) {
+  if (!rawUrl || rawUrl.startsWith("node:")) {
+    return null
+  }
+
+  const cleaned = stripQuery(rawUrl)
+  let pathname = cleaned
+
+  try {
+    const parsed = new URL(cleaned)
+    pathname = parsed.pathname
+  } catch {
+    // keep as-is for relative paths
+  }
+
+  if (!pathname) {
+    return null
+  }
+
+  let absolutePath
+
+  const decoded = decodeURIComponent(pathname)
+  if (decoded.startsWith(VITE_FS_PREFIX)) {
+    absolutePath = path.normalize(decoded.slice(VITE_FS_PREFIX.length))
+  } else if (decoded.startsWith("/")) {
+    absolutePath = path.resolve(config.workspaceRoot, `.${decoded}`)
+  } else {
+    return null
+  }
+
+  return createNormalizedPath(absolutePath, config.workspaceRoot)
+}
+
+function createNormalizedPath(absolutePath, workspaceRoot) {
+  if (!absolutePath.startsWith(workspaceRoot)) {
+    return null
+  }
+
+  const relativePath = path.relative(workspaceRoot, absolutePath)
+  return {
+    absolutePath,
+    relativePath,
+  }
+}
+
+function stripQuery(url) {
+  const queryIndex = url.indexOf("?")
+  const hashIndex = url.indexOf("#")
+
+  const endIndex = Math.min(
+    queryIndex === -1 ? Number.POSITIVE_INFINITY : queryIndex,
+    hashIndex === -1 ? Number.POSITIVE_INFINITY : hashIndex,
+  )
+
+  if (!Number.isFinite(endIndex)) {
+    return url
+  }
+
+  return url.slice(0, endIndex)
+}
+
+function isInsideLib(absolutePath, libRoots) {
+  return libRoots.some((libRoot) => {
+    const relative = path.relative(libRoot, absolutePath)
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))
+  })
+}

package/src/index.js

@@ -1,2 +1,50 @@
-// export * from "./defineConfig"
-export * from "./clearDatabase.js"
+import { test as baseTest, expect as baseExpect, defineConfig as playwrightDefineConfig, devices } from "@playwright/test"
+
+import { loadCoverageOptions } from "./coverage/config-loader.js"
+import { createCoverageHarness } from "./coverage/index.js"
+
+
+export { clearDatabase } from "./clearDatabase.js"
+export * from "./coverage/index.js"
+
+const coverageOptions = await loadCoverageOptions()
+const coverageHarness = createCoverageHarness(coverageOptions)
+
+export const test = coverageHarness.extendTest(baseTest)
+export const expect = baseExpect
+export { devices }
+
+export function defineConfig(userConfig = {}) {
+  const normalized = { ...userConfig }
+  const reporters = ensureReporterArray(normalized.reporter)
+
+  if (coverageHarness.config.coverageEnabled) {
+    const coverageReporter = coverageHarness.reporterEntry()
+    if (!reporters.some(([name]) => name === coverageReporter[0])) {
+      reporters.push(coverageReporter)
+    }
+  }
+
+  normalized.reporter = reporters
+
+  return playwrightDefineConfig(normalized)
+}
+
+function ensureReporterArray(reporter) {
+  if (!reporter) {
+    return [["list"]]
+  }
+
+  if (!Array.isArray(reporter)) {
+    return [normalizeReporterEntry(reporter)]
+  }
+
+  return reporter.map((entry) => normalizeReporterEntry(entry))
+}
+
+function normalizeReporterEntry(entry) {
+  if (Array.isArray(entry)) {
+    return entry
+  }
+  return [entry]
+}

package/src/register-tty.cjs

@@ -0,0 +1,33 @@
+function ensureTTY(stream, fallbackColumns = 80, fallbackRows = 24) {
+  if (!stream || stream.isTTY) {
+    return
+  }
+
+  try {
+    stream.isTTY = true
+  } catch (error) {
+    // ignore property assignment errors
+  }
+
+  if (typeof stream.getWindowSize === "function") {
+    const [columns, rows] = stream.getWindowSize()
+    if (Number.isFinite(columns)) {
+      stream.columns = columns
+    }
+    if (Number.isFinite(rows)) {
+      stream.rows = rows
+    }
+  } else {
+    if (stream.columns == null) {
+      const columnsEnv = Number.parseInt(process.env.COLUMNS ?? "", 10)
+      stream.columns = Number.isFinite(columnsEnv) ? columnsEnv : fallbackColumns
+    }
+    if (stream.rows == null) {
+      const rowsEnv = Number.parseInt(process.env.LINES ?? "", 10)
+      stream.rows = Number.isFinite(rowsEnv) ? rowsEnv : fallbackRows
+    }
+  }
+}
+
+ensureTTY(process.stdout)
+ensureTTY(process.stderr)