qa-core-flaky 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.1 - 2026-10-30
+
+A Windows fix for `rerun`, plus package details and docs.
+
+- **Fixed:** `rerun` now works on Windows. It used to stop with `spawn ... node_modules/.bin/playwright ENOENT`, because Windows cannot start that file. The tool now starts Playwright's own `cli.js` with Node on every OS. On Windows the child processes are no longer detached, so no console windows open during a rerun or a heal call, and cleanup stops the whole process tree with `taskkill /T`. The file filter on Windows now matches a backslash or a forward slash in the path, and the printed command shows that filter correctly. Reported by Abdul Rafay.
+- **Changed:** The package author is now SprintSynergy (https://sprintsynergy.com), and Muhammad Usman is listed as a contributor.
+- **Changed:** The printed rerun command now starts with `npx playwright test` when Playwright is installed in the folder where you run it.
+- **Docs:** The README now shows version 0.1.1 and ends with a line saying who builds and maintains the project. The rerun docs explain how Playwright is found and started.
+- **Tests:** New tests cover Windows file filters, the Playwright lookup, and how the rerun starts Playwright. The HTML example now shows version 0.1.1.
+
 ## 0.1.0 - 2026-10-29
 
 First public release.

package/README.md

@@ -4,7 +4,7 @@ qa-core-flaky triages flaky Playwright tests. It separates a likely real bug fro
 
 ## Status
 
-Version 0.1.0. The commands are `parse`, `causes`, `triage`, and `rerun`.
+Version 0.1.1. The commands are `parse`, `causes`, `triage`, and `rerun`.
 
 ## Install
 
@@ -103,3 +103,5 @@ Tests and CI use the committed report. They do not install browsers and they do
 ## License
 
 MIT. See [LICENSE](LICENSE).
+
+Built by [SprintSynergy](https://sprintsynergy.com) and maintained by [Muhammad Usman](https://linkedin.com/in/sdet-muhammadusman).

package/dist/heal/run.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { rerunChildEnv, stopChildTree } from '../rerun/run.js';
+import { DETACH_CHILDREN, rerunChildEnv, stopChildTree } from '../rerun/run.js';
 /** Flags this tool must never put on a heal command line. */
 export const FORBIDDEN_HEAL_ARGS = ['--apply', '--yes', '--no-verify'];
 const DEFAULT_TIMEOUT_MS = 60_000;
@@ -126,8 +126,9 @@ export function runHealCommand(args, timeoutMs = healTimeoutMs()) {
             shell: false,
             windowsHide: true,
             env: rerunChildEnv(tempRoot),
-            // A new process group so the timeout can kill grandchildren.
-            detached: true,
+            // A new process group so the timeout can kill grandchildren. Not on
+            // Windows, where it opens a console window and taskkill /T is used.
+            detached: DETACH_CHILDREN,
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         bindHealChild(child);

package/dist/rerun/plan.d.ts

@@ -115,7 +115,15 @@ export declare function anchoredGrep(project: string, file: string, titlePath: r
  * `old/tests/login.spec.ts`.
  */
 export declare function fileFilterArg(file: string, line?: number): string;
-/** Exact path, anchored, with an optional `:line`. Slashes are escaped inside `/.../`. */
+/** One path separator in a Windows file filter: a backslash or a forward slash. */
+export declare const WINDOWS_SEPARATOR = "[\\\\/]";
+/**
+ * Exact path, anchored, with an optional `:line`. Slashes are escaped inside `/.../`.
+ * A Windows path matches each separator with `[\\/]`. Playwright 1.60.0 tests
+ * the file filter against the native path, which uses backslashes on Windows,
+ * and then against its `file:///` URL. `[\\/]` matches the native path with
+ * either separator.
+ */
 export declare function exactFileArg(filePath: string, line?: number): string;
 /**
  * The command a person can copy. Every argument is redacted. The file

package/dist/rerun/plan.js

@@ -143,9 +143,22 @@ export function anchoredGrep(project, file, titlePath) {
 export function fileFilterArg(file, line) {
     return exactFileArg(file.replaceAll('\\', '/'), line);
 }
-/** Exact path, anchored, with an optional `:line`. Slashes are escaped inside `/.../`. */
+/** One path separator in a Windows file filter: a backslash or a forward slash. */
+export const WINDOWS_SEPARATOR = '[\\\\/]';
+/** A drive path (`C:\` or `C:/`), or a UNC or extended path (`\\server`, `\\?\`). */
+const WINDOWS_ABSOLUTE = /^(?:[A-Za-z]:[\\/]|[\\/]{2}[^\\/])/;
+/**
+ * Exact path, anchored, with an optional `:line`. Slashes are escaped inside `/.../`.
+ * A Windows path matches each separator with `[\\/]`. Playwright 1.60.0 tests
+ * the file filter against the native path, which uses backslashes on Windows,
+ * and then against its `file:///` URL. `[\\/]` matches the native path with
+ * either separator.
+ */
 export function exactFileArg(filePath, line) {
-    const wrapped = `/^${escapeSlash(filePath)}$/`;
+    const body = WINDOWS_ABSOLUTE.test(filePath)
+        ? filePath.split(/[\\/]/).map(escapeSlash).join(WINDOWS_SEPARATOR)
+        : escapeSlash(filePath);
+    const wrapped = `/^${body}$/`;
     if (line === undefined)
         return wrapped;
     return `${wrapped}:${line}`;
@@ -167,7 +180,11 @@ export function formatPrintedCommand(args, record, prefix = []) {
     const visibleTitle = title?.replaceAll('\\/', '/');
     const titleChanged = visibleTitle !== undefined && redact(visibleTitle) !== visibleTitle;
     const kept = titleChanged ? args.filter((part, index) => part !== '-g' && args[index - 1] !== '-g') : args;
-    const shown = [...prefix, ...kept].map((part) => shellQuote(redact(part))).join(' ');
+    const fileAt = kept.lastIndexOf('--') + 1;
+    const shown = [...prefix, ...kept]
+        .map((part, index) => index === prefix.length + fileAt && fileAt > 0 ? redactFileFilter(part, redact) : redact(part))
+        .map(shellQuote)
+        .join(' ');
     if (!titleChanged)
         return shown;
     return `${shown} (the title was redacted, so -g is omitted here)`;
@@ -212,6 +229,25 @@ export function splitRerunSentence(nextStep) {
         return { lead: nextStep, command: nextStep };
     return { lead: nextStep.slice(0, at + marker.length), command };
 }
+/**
+ * Redact a Windows file filter for printing. The native path is rebuilt from
+ * the filter, redacted the same way as any Windows path, and escaped again
+ * with `[\\/]` separators. The printed filter keeps the escapes and the
+ * separators the process received. Only the home becomes `<home>`.
+ * Any other argument is redacted as written.
+ */
+function redactFileFilter(part, redact) {
+    const match = /^\/\^(.*)\$\/(:\d+)?$/s.exec(part);
+    const body = match?.[1];
+    if (body === undefined || !part.includes(WINDOWS_SEPARATOR))
+        return redact(part);
+    const native = body
+        .split(WINDOWS_SEPARATOR)
+        .map((segment) => segment.replace(/\\(n|.)/gs, (_all, char) => (char === 'n' ? '\n' : char)))
+        .join('\\');
+    const shown = redact(native).split(/[\\/]/).map(escapeSlash).join(WINDOWS_SEPARATOR);
+    return `/^${shown}$/${match?.[2] ?? ''}`;
+}
 function escapeSlash(value) {
     return escapeRegex(value)
         .replaceAll('/', '\\/')

package/dist/rerun/run.d.ts

@@ -1,6 +1,11 @@
 import { type ChildProcess } from 'node:child_process';
 import type { TestRecord } from '../model.js';
 import { type PlannedRun, type RerunPlan } from './plan.js';
+/**
+ * Children get their own process group on macOS and Linux only. On Windows,
+ * a detached child opens a new console window.
+ */
+export declare const DETACH_CHILDREN: boolean;
 /** Signals that stop a rerun. The child process group is killed before the temp directory is removed. */
 export declare const STOP_SIGNALS: readonly ["SIGINT", "SIGTERM", "SIGHUP"];
 /** How long to wait after SIGTERM before SIGKILL. */
@@ -49,8 +54,12 @@ export declare function releaseRun(state: ReleaseState): Promise<void>;
 export declare function onStopSignal(signal: NodeJS.Signals, release: () => void | Promise<void>, reraise: (signal: NodeJS.Signals) => void): Promise<void>;
 export declare function killProcessGroup(pid: number, child?: ChildProcess): Promise<void>;
 /**
- * Spawn a detached child with temp env inside `dir`.
+ * Spawn a child with temp env inside `dir`.
  * The caller owns stdout piping and cleanup.
+ * On macOS and Linux the child gets its own process group, so cleanup can stop
+ * its descendants. On Windows a detached child gets a new console window, and
+ * `windowsHide` does not stop the windows its own children open, so the child
+ * stays attached and cleanup uses `taskkill /T` instead.
  */
 export declare function launchRerunChild(input: {
     command: string;
@@ -79,6 +88,34 @@ export declare function resolveProjectFile(file: string, cwd: string, config?: s
  * A missing id is an error. Extra tests are an error. Nothing is merged on failure.
  */
 export declare function selectRecords(run: PlannedRun, records: readonly TestRecord[], times: number): TestRecord[];
+/**
+ * Playwright's own JavaScript entry points, in lookup order. The rerun runs
+ * them with the Node that runs this tool. It does not start the
+ * `node_modules/.bin/playwright` shim, because that file is a shell script
+ * on Windows, and Node refuses to start `playwright.cmd` without a shell.
+ * A shell would read `^`, `$`, and `|` in the filters.
+ */
+export declare const PLAYWRIGHT_CLI_PATHS: readonly (readonly string[])[];
+/**
+ * Playwright's `cli.js` in `startDir`, then each parent, the same way Node
+ * resolves a package. `playwright/cli.js` is checked before
+ * `@playwright/test/cli.js` in each folder. Stops at the filesystem root.
+ */
+export declare function findPlaywrightCli(startDir: string): string | undefined;
+/**
+ * With `--config`, start at the config folder and walk parents, the same way
+ * Node resolves a package. Without `--config`, look only in the working directory.
+ */
+export declare function playwrightCli(cwd: string, config?: string): string;
+/**
+ * The launcher a person reads in front of each printed command.
+ * `npx playwright test` when Playwright is installed in the working
+ * directory, because `npx` finds it there on every OS. Otherwise `node` and
+ * the path to Playwright's `cli.js`, relative to the working directory, so a
+ * kit that keeps `node_modules` in a subfolder still has a command that runs.
+ * The process itself is started with the same Node and `cli.js` either way.
+ */
+export declare function printedLauncher(cwd: string, config?: string): string;
 /**
  * Signal one spawned child, then every descendant.
  * Descendants are collected before the signal. Each one is signaled, and so

package/dist/rerun/run.js

@@ -6,6 +6,12 @@ import { parsePlaywrightJson } from '../parsers/playwright-json.js';
 import { redactHomeText } from '../report-path.js';
 import { commitFor, mergeRerunRecords, tagRerunAttempts } from './merge.js';
 import { exactFileArg, formatPrintedCommand } from './plan.js';
+import { shellQuote } from './quote.js';
+/**
+ * Children get their own process group on macOS and Linux only. On Windows,
+ * a detached child opens a new console window.
+ */
+export const DETACH_CHILDREN = process.platform !== 'win32';
 /** Signals that stop a rerun. The child process group is killed before the temp directory is removed. */
 export const STOP_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'];
 /** How long to wait after SIGTERM before SIGKILL. */
@@ -87,6 +93,10 @@ export async function onStopSignal(signal, release, reraise) {
     reraise(signal);
 }
 export async function killProcessGroup(pid, child) {
+    if (process.platform === 'win32') {
+        await taskkillTree(pid);
+        return;
+    }
     const tracked = signalTree(pid, 'SIGTERM', child);
     const gone = await waitUntilGone(pid, SIGNAL_WAIT_MS, child, tracked);
     if (!gone) {
@@ -95,14 +105,19 @@ export async function killProcessGroup(pid, child) {
     }
 }
 /**
- * Spawn a detached child with temp env inside `dir`.
+ * Spawn a child with temp env inside `dir`.
  * The caller owns stdout piping and cleanup.
+ * On macOS and Linux the child gets its own process group, so cleanup can stop
+ * its descendants. On Windows a detached child gets a new console window, and
+ * `windowsHide` does not stop the windows its own children open, so the child
+ * stays attached and cleanup uses `taskkill /T` instead.
  */
 export function launchRerunChild(input) {
     return spawn(input.command, input.args, {
         cwd: input.cwd,
         env: rerunChildEnv(input.dir),
-        detached: true,
+        detached: DETACH_CHILDREN,
+        windowsHide: true,
         stdio: ['ignore', input.stdout ?? 'pipe', 'pipe'],
     });
 }
@@ -150,7 +165,8 @@ export async function executePlan(input) {
                 break;
             const record = input.records.find((item) => item.id === run.testId) ??
                 input.records.find((item) => item.file === run.file && item.project === run.project);
-            safePrint(input.print, formatPrintedCommand(args, record, input.runner ? [] : launcherPrefix(input.cwd, flagValue(args, '--config'))));
+            const shown = formatPrintedCommand(args, record);
+            safePrint(input.print, input.runner ? shown : `${printedLauncher(input.cwd, flagValue(args, '--config'))} ${shown}`);
             if (state.stopping)
                 break;
             let result;
@@ -270,7 +286,7 @@ async function prepareArgs(run, args, cwd, requireFile, rerunDir) {
     // A spec under testDir is not in the working directory. Check the local
     // binary before that lookup, so a missing install is reported as itself.
     if (requireFile && !config)
-        playwrightBin(cwd);
+        playwrightCli(cwd);
     const absolute = await resolveProjectFile(run.file, cwd, config, path.join(rerunDir, 'tmp'));
     if (!absolute) {
         if (requireFile) {
@@ -302,7 +318,7 @@ export async function resolveProjectFile(file, cwd, config, cacheRoot) {
         // The spec is under testDir, which is not the folder where triage ran.
         // Playwright has to load before that root is known. A missing install
         // is not a missing test file.
-        if (!findPlaywrightBin(configDir))
+        if (!findPlaywrightCli(configDir))
             throw missingPlaywrightError(configDir);
         const loaded = await loadRootDir(resolvedConfig, cacheRoot);
         if (loaded)
@@ -359,7 +375,8 @@ function readRootDirFromChild(configFile, cacheDir) {
             // parents. That is the config folder, not the triage folder, so a kit
             // that holds node_modules still loads when triage ran in the parent.
             cwd: path.dirname(configFile),
-            detached: true,
+            detached: DETACH_CHILDREN,
+            windowsHide: true,
             env: {
                 ...process.env,
                 QA_CORE_FLAKY_CONFIG: configFile,
@@ -478,19 +495,41 @@ function withOutput(args, outputDir) {
     copy.splice(at, 0, '--output', outputDir);
     return copy;
 }
-function launcherPrefix(cwd, config) {
-    return [playwrightBin(cwd, config), 'test'];
+/**
+ * Playwright's own JavaScript entry points, in lookup order. The rerun runs
+ * them with the Node that runs this tool. It does not start the
+ * `node_modules/.bin/playwright` shim, because that file is a shell script
+ * on Windows, and Node refuses to start `playwright.cmd` without a shell.
+ * A shell would read `^`, `$`, and `|` in the filters.
+ */
+export const PLAYWRIGHT_CLI_PATHS = [
+    ['playwright', 'cli.js'],
+    ['@playwright/test', 'cli.js'],
+];
+function cliInFolder(dir) {
+    for (const parts of PLAYWRIGHT_CLI_PATHS) {
+        const file = path.join(dir, 'node_modules', ...parts);
+        try {
+            if (fs.statSync(file).isFile())
+                return file;
+        }
+        catch {
+            // Not installed in this folder.
+        }
+    }
+    return undefined;
 }
 /**
- * `node_modules/.bin/playwright` in `startDir`, then each parent, the same
- * way Node resolves a package. Stops at the filesystem root.
+ * Playwright's `cli.js` in `startDir`, then each parent, the same way Node
+ * resolves a package. `playwright/cli.js` is checked before
+ * `@playwright/test/cli.js` in each folder. Stops at the filesystem root.
  */
-function findPlaywrightBin(startDir) {
+export function findPlaywrightCli(startDir) {
     let dir = path.resolve(startDir);
     for (;;) {
-        const bin = path.join(dir, 'node_modules', '.bin', 'playwright');
-        if (fs.existsSync(bin))
-            return bin;
+        const cli = cliInFolder(dir);
+        if (cli)
+            return cli;
         const parent = path.dirname(dir);
         if (parent === dir)
             return undefined;
@@ -498,38 +537,61 @@ function findPlaywrightBin(startDir) {
     }
 }
 function missingPlaywrightError(start) {
-    const bin = path.join(start, 'node_modules', '.bin', 'playwright');
-    return new Error(redactHomeText(`Local Playwright was not found at ${bin}. Install playwright in this project before rerun.`));
+    const modules = path.join(start, 'node_modules');
+    return new Error(redactHomeText(`Local Playwright was not found in ${modules}. The rerun looks for playwright/cli.js and @playwright/test/cli.js. Install @playwright/test in this project before rerun.`));
 }
 /**
  * With `--config`, start at the config folder and walk parents, the same way
  * Node resolves a package. Without `--config`, look only in the working directory.
  */
-function playwrightBin(cwd, config) {
+export function playwrightCli(cwd, config) {
     if (!config) {
         const start = path.resolve(cwd);
-        const bin = path.join(start, 'node_modules', '.bin', 'playwright');
-        if (!fs.existsSync(bin))
+        const cli = cliInFolder(start);
+        if (!cli)
             throw missingPlaywrightError(start);
-        return bin;
+        return cli;
     }
     const start = path.dirname(path.resolve(cwd, config));
-    const bin = findPlaywrightBin(start);
-    if (!bin)
+    const cli = findPlaywrightCli(start);
+    if (!cli)
         throw missingPlaywrightError(start);
-    return bin;
+    return cli;
+}
+/**
+ * The launcher a person reads in front of each printed command.
+ * `npx playwright test` when Playwright is installed in the working
+ * directory, because `npx` finds it there on every OS. Otherwise `node` and
+ * the path to Playwright's `cli.js`, relative to the working directory, so a
+ * kit that keeps `node_modules` in a subfolder still has a command that runs.
+ * The process itself is started with the same Node and `cli.js` either way.
+ */
+export function printedLauncher(cwd, config) {
+    let cli;
+    try {
+        cli = playwrightCli(cwd, config);
+    }
+    catch {
+        return 'npx playwright test';
+    }
+    const local = path.join(path.resolve(cwd), 'node_modules') + path.sep;
+    if (cli.startsWith(local))
+        return 'npx playwright test';
+    const relative = path.relative(path.resolve(cwd), cli).split(path.sep).join('/');
+    return `node ${shellQuote(redactHomeText(relative))} test`;
 }
 function defaultRunner(args, cwd, stdoutFile, setPid, dir, state) {
     return new Promise((resolve, reject) => {
-        let bin;
+        let cli;
         try {
-            bin = playwrightBin(cwd, flagValue(args, '--config'));
+            cli = playwrightCli(cwd, flagValue(args, '--config'));
         }
         catch (error) {
             reject(error instanceof Error ? error : new Error('Local Playwright was not found.'));
             return;
         }
-        const child = launchRerunChild({ command: bin, args: ['test', ...args], cwd, dir });
+        // Node runs Playwright's cli.js directly on every OS. No shell and no shim.
+        const child = launchRerunChild({ command: process.execPath, args: [cli, 'test', ...args], cwd, dir });
         state.child = child;
         if (child.pid !== undefined)
             setPid(child.pid);
@@ -586,7 +648,7 @@ export async function stopChildTree(child) {
     if (pid === undefined || pid <= 1)
         return;
     if (process.platform === 'win32') {
-        spawn('taskkill', ['/T', '/F', '/PID', String(pid)], { stdio: 'ignore', windowsHide: true });
+        await taskkillTree(pid);
         return;
     }
     let tracked = signalTree(pid, 'SIGKILL', child);
@@ -596,6 +658,24 @@ export async function stopChildTree(child) {
         await waitUntilGone(pid, SIGNAL_WAIT_MS, child, tracked);
     }
 }
+/**
+ * Stop a process and every descendant on Windows, and wait for taskkill to
+ * finish so the temp folder is no longer in use when it is removed.
+ */
+function taskkillTree(pid) {
+    if (!Number.isInteger(pid) || pid <= 1)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        try {
+            const killer = spawn('taskkill', ['/T', '/F', '/PID', String(pid)], { stdio: 'ignore', windowsHide: true });
+            killer.once('error', () => resolve());
+            killer.once('close', () => resolve());
+        }
+        catch {
+            resolve();
+        }
+    });
+}
 function signalPid(pid, signal) {
     if (!Number.isInteger(pid) || pid <= 1)
         return;

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "qa-core-flaky",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Triage flaky Playwright tests: real bug or flaky, likely cause, and a suggested fix to review.",
   "type": "module",
   "license": "MIT",
-  "author": "SprintSynergy",
+  "author": {
+    "name": "SprintSynergy",
+    "url": "https://sprintsynergy.com"
+  },
+  "contributors": [
+    {
+      "name": "Muhammad Usman",
+      "url": "https://linkedin.com/in/sdet-muhammadusman"
+    }
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sprintsynergyhq/qa-core-flaky.git"