playwright-mutation-gate 0.1.0 → 0.2.1

package/README.md

@@ -166,7 +166,35 @@ Options:
   -h, --help                display help for command
 ```
 
-The package is CLI-only for now. Programmatic API is planned for v0.2.
+## Programmatic API
+
+Since v0.2 the package also exposes a library entry, so a tool can run the gate
+in-process and inspect the structured report instead of shelling out to the CLI
+and parsing `--json`.
+
+```ts
+import { runSpec, summarize } from 'playwright-mutation-gate';
+
+const spec = await runSpec('tests/checkout.spec.ts', {
+  testIds: ['authedTest'],            // extra test builders, same as --test-id
+  playwrightArgs: ['--project=chromium', '--retries=0'],
+});
+const summary = summarize([spec], { requireSentinel: true });
+
+if (!summary.gatePassed) {
+  const hollow = spec.results.filter((r) => r.verdict === 'survived');
+  console.error(`${hollow.length} assertion(s) do not gate the result`);
+  process.exit(1);
+}
+```
+
+`runSpec(specPath, opts?)` returns a `SpecResult` (per-assertion `verdict`:
+`killed` / `survived` / `cannot-mutate` / `error`, plus unmarked/stray/malformed
+markers). `summarize(specs, opts)` folds one or more results into a `Summary`
+with the `gatePassed` verdict. `jsonReport` and `renderTable` produce the CLI's
+two output formats. Advanced: `planSpecMutations` and `invertAssertLine` expose
+the mutation planner and the single-line inverter directly. Full types ship with
+the package.
 
 ## Limitations
 

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { runSpec, sweepStaleMutationFiles, DEFAULT_TIMEOUT_MS, type SpecResult, type MutationResult, type Verdict, type RunOptions, } from './run.js';
+export { summarize, jsonReport, renderTable, type Summary, type GateOptions, type RenderOptions, } from './report.js';
+export { planSpecMutations, MARKER, type SpecPlan, type Mutation, type PlanOptions, } from './mutate.js';
+export { invertAssertLine, type InvertResult } from './invert.js';

package/dist/index.js

@@ -0,0 +1,15 @@
+// Programmatic entry point.
+//
+// The CLI (`dist/cli.js`) is one consumer of this library; another is any tool
+// that wants to run the gate in-process and inspect the report itself — e.g. a
+// custom test-pipeline that already knows which specs changed and wants the
+// structured `SpecResult`/`Summary` without shelling out and parsing `--json`.
+//
+// Curated surface: run a spec, summarize/render the results, and (advanced) plan
+// or invert individual mutations. The tokenizer (`lex.ts`) and the on-disk
+// mutant-file mechanics stay internal — `runSpec` orchestrates them for you.
+export { runSpec, sweepStaleMutationFiles, DEFAULT_TIMEOUT_MS, } from './run.js';
+export { summarize, jsonReport, renderTable, } from './report.js';
+// Advanced: build or inspect the mutation plan directly.
+export { planSpecMutations, MARKER, } from './mutate.js';
+export { invertAssertLine } from './invert.js';

package/dist/invert.d.ts

@@ -0,0 +1,16 @@
+export type InvertResult = {
+    ok: string;
+} | {
+    cannotMutate: string;
+};
+/**
+ * Invert the assertion on a single line of a Playwright spec:
+ * `expect(x).toY()` <-> `expect(x).not.toY()`.
+ *
+ * Purely string-based. Supported chain shape:
+ * `[await] expect[.soft|.poll](...) [.resolves|.rejects] [.not] .toXxx(`
+ * The matcher call must start on this line; its arguments may continue on
+ * following lines. Everything else returns `cannotMutate` with a reason
+ * rather than guessing.
+ */
+export declare function invertAssertLine(line: string): InvertResult;

package/dist/lex.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared single-pass lexer for the string-based spec analysis. Classifies
+ * every char of a source (a whole file or a single line) so the scanners in
+ * invert.ts and mutate.ts agree about what is code. One implementation on
+ * purpose: two hand-rolled lexers had already diverged once.
+ */
+/** Char inside a string, template literal, block comment or regex literal. */
+export declare const NON_CODE = 0;
+/** Executable source. */
+export declare const CODE = 1;
+/** Char of a `//` comment that starts in code context. */
+export declare const LINE_COMMENT = 2;
+/**
+ * Classify every char of `src` as CODE, LINE_COMMENT or NON_CODE. Handles
+ * strings with escapes, template literals with nested `${}` expressions,
+ * `//` and block comments, and regex literals (heuristic: see startsRegex).
+ */
+export declare function lex(src: string): Uint8Array;
+/**
+ * Find the `)` matching the `(` at `open`, counting only CODE chars.
+ * Returns -1 when it does not close within `src`.
+ */
+export declare function findCloseMasked(src: string, kind: Uint8Array, open: number): number;

package/dist/mutate.d.ts

@@ -0,0 +1,66 @@
+export declare const MARKER = "// @primary-assert";
+export type Mutation = {
+    testTitle: string;
+    /** 1-based line of the test() declaration, for file:line targeting. */
+    testLine: number;
+    /** 1-based line of the `// @primary-assert` marker. */
+    markerLine: number;
+    /** 1-based line of the assertion that was inverted. */
+    assertLine: number;
+    /** Full spec source with exactly this one assertion inverted. */
+    mutatedSource: string;
+} | {
+    testTitle: string;
+    testLine: number;
+    markerLine: number;
+    /** 1-based line of the assertion candidate; null when none was located. */
+    assertLine: number | null;
+    cannotMutate: string;
+};
+export interface PlanOptions {
+    /**
+     * Extra identifiers to treat as test builders, on top of `test` and the
+     * auto-detected `.extend` chains and renamed imports. For custom fixtures
+     * imported by their own name from another module (`import { authedTest }
+     * from './fixtures'`), which cannot be detected without resolving the import.
+     */
+    testIds?: string[];
+}
+export interface SpecPlan {
+    /** One entry per marked test: either a mutated copy or a cannot-mutate reason. */
+    mutations: Mutation[];
+    /** Runnable tests with no marker (sentinel accounting). skip/fixme/fail are exempt. */
+    unmarkedTests: {
+        title: string;
+        line: number;
+    }[];
+    /** 1-based lines of valid markers that sit outside every test() block. */
+    strayMarkerLines: number[];
+    /**
+     * 1-based lines of test.only() declarations. Any .only filters out every
+     * other test in the file, so the runner refuses the whole spec.
+     */
+    onlyTestLines: number[];
+    /** 1-based lines mentioning @primary-assert that do not form a valid marker. */
+    malformedMarkerLines: number[];
+}
+/**
+ * Parse a spec source and plan its mutations: one inverted copy per marked
+ * test. Anything the gate cannot honestly mutate is reported with a reason,
+ * never skipped silently.
+ */
+export declare function planSpecMutations(source: string, opts?: PlanOptions): SpecPlan;
+/**
+ * Name for a mutated copy: the marker segment goes right after the first
+ * dot-segment of the basename, so the ENTIRE original tail is preserved and
+ * the copy matches whatever testMatch convention picked up the original
+ * (`checkout.e2e.ts` -> `checkout.pmg-mutation-0.e2e.ts`).
+ */
+export declare function mutationFilePath(specPath: string, index: number, tag?: string): string;
+/**
+ * Write the mutated copy next to the original spec (same dir keeps relative
+ * imports and the Playwright testDir working) and return its path. The name
+ * carries the process id so overlapping gate runs in one checkout cannot
+ * collide. The caller owns cleanup.
+ */
+export declare function writeMutationFile(specPath: string, index: number, mutatedSource: string): string;

package/dist/report.d.ts

@@ -0,0 +1,31 @@
+import type { SpecResult } from './run.js';
+export interface GateOptions {
+    /** When true (default), tests without a @primary-assert marker fail the gate. */
+    requireSentinel: boolean;
+}
+export interface Summary {
+    killed: number;
+    survived: number;
+    cannotMutate: number;
+    errors: number;
+    unmarkedTests: number;
+    strayMarkers: number;
+    malformedMarkers: number;
+    /**
+     * Green means proven: every marked assertion was killed under inversion and
+     * nothing was left unverified. Any survived, cannot-mutate or error verdict
+     * fails the gate, as do marker mistakes (stray or malformed markers) and,
+     * under require-sentinel, tests with no marker at all.
+     */
+    gatePassed: boolean;
+}
+export declare function summarize(specs: SpecResult[], opts: GateOptions): Summary;
+export declare function jsonReport(specs: SpecResult[], opts: GateOptions): string;
+export interface RenderOptions extends GateOptions {
+    color: boolean;
+}
+/**
+ * Human-readable report: per spec, one row per verdict plus sentinel findings,
+ * then a one-line summary and the gate outcome.
+ */
+export declare function renderTable(specs: SpecResult[], opts: RenderOptions): string;

package/dist/run.d.ts

@@ -0,0 +1,68 @@
+import { type Mutation, type SpecPlan } from './mutate.js';
+export type Verdict = 'killed' | 'survived' | 'cannot-mutate' | 'error';
+export interface MutationResult {
+    testTitle: string;
+    testLine: number;
+    /** 1-based line of the mutated assertion; null when none was located. */
+    assertLine: number | null;
+    verdict: Verdict;
+    /** Present for cannot-mutate and error verdicts. */
+    reason?: string;
+}
+export interface SpecResult {
+    specPath: string;
+    results: MutationResult[];
+    unmarkedTests: SpecPlan['unmarkedTests'];
+    strayMarkerLines: number[];
+    malformedMarkerLines: number[];
+}
+export interface RunOptions {
+    /** Directory Playwright is spawned from; defaults to process.cwd(). */
+    cwd?: string;
+    /** Hard cap for one mutation run; the child is killed past it. Default 5 min. */
+    timeoutMs?: number;
+    /** Extra args appended to every `playwright test` invocation. */
+    playwrightArgs?: string[];
+    /** Command that launches Playwright; default ['npx', 'playwright', 'test']. */
+    playwrightCommand?: string[];
+    /** Extra identifiers to treat as test builders (custom fixtures). */
+    testIds?: string[];
+}
+export declare const DEFAULT_TIMEOUT_MS: number;
+type RunVerdict = {
+    verdict: 'killed' | 'survived';
+} | {
+    verdict: 'cannot-mutate';
+    reason: string;
+} | {
+    verdict: 'error';
+    reason: string;
+};
+/**
+ * Decide a verdict from a Playwright JSON report. The exit code alone cannot
+ * be trusted: Playwright exits 1 for a failed test, for "no tests found" and
+ * for many crashes alike, and only the report tells those apart.
+ */
+export declare function verdictFromReport(raw: string): RunVerdict;
+/**
+ * Run one planned mutation: write the inverted copy next to the spec, run
+ * Playwright against exactly that copy and test line, and read the verdict
+ * from the JSON report. The copy and the report directory are always removed.
+ */
+export declare function runMutation(specPath: string, index: number, mutation: Extract<Mutation, {
+    mutatedSource: string;
+}>, opts?: RunOptions): Promise<RunVerdict>;
+/**
+ * Delete leftover mutation copies in a directory: files whose pid token
+ * points at a process that no longer exists. Copies of live concurrent gate
+ * runs are left alone. Returns the paths that were removed.
+ */
+export declare function sweepStaleMutationFiles(dir: string): string[];
+/**
+ * Gate one spec file end to end: plan its mutations, sweep stale copies from
+ * earlier crashed runs, run every mutable mutation and collect verdicts.
+ * A spec containing test.only is refused outright: .only filters out every
+ * other test, so verdicts from such a run would be fiction.
+ */
+export declare function runSpec(specPath: string, opts?: RunOptions): Promise<SpecResult>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playwright-mutation-gate",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Mutation testing for Playwright assertions: invert each test's primary assertion and fail the run if the test stays green.",
   "keywords": [
     "playwright",
@@ -16,6 +16,15 @@
   "license": "MIT",
   "author": "Vladyslav Dmitriiev <vladyslav.dmitriiev@pm.me>",
   "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "playwright-mutation-gate": "dist/cli.js"
   },