@piwitests/reporter 0.41.0 → 0.42.0

package/dist/global-setup-module.js

@@ -137,6 +137,7 @@ var PIWI_ENV_KEYS = {
   aiScreenshotFallback: "PIWI_AI_SCREENSHOT_FALLBACK"
 };
 var PIWI_DESKTOP_CONFIG_ENV = "PIWI_DESKTOP_CONFIG";
+var PIWI_SHARD_ENV = "PIWI_SHARD";
 function readBool(val) {
   if (val === void 0) return void 0;
   return val === "true";
@@ -489,6 +490,20 @@ function detectCiRunLabel() {
   return null;
 }
 
+// src/internal/support/shard-info.ts
+function parseShardSpec(raw) {
+  const match = raw?.trim().match(/^(\d+)\s*\/\s*(\d+)$/);
+  if (!match) return null;
+  const current = Number(match[1]);
+  const total = Number(match[2]);
+  return current >= 1 && current <= total && total > 1 ? { current, total } : null;
+}
+function resolveShardInfo(config, env = process.env) {
+  const pwShard = config.shard;
+  if (pwShard && pwShard.total > 1) return { current: pwShard.current, total: pwShard.total };
+  return parseShardSpec(env[PIWI_SHARD_ENV]);
+}
+
 // src/internal/collect/metadata-collector.ts
 var import_node_child_process = require("child_process");
 var DETACHED_HEAD = "HEAD";
@@ -688,9 +703,7 @@ function createGlobalSetup(options, userSetup) {
     try {
       const auth = await httpClient.resolveAuth(opts);
       const runLabel = opts.runLabel || detectCiRunLabel();
-      const pwShard = config.shard;
-      const shardIndex = pwShard?.current;
-      const shardTotal = pwShard?.total;
+      const shard = resolveShardInfo(config);
       const response = await httpClient.postJSON(
         "/api/test-runs/setup",
         {
@@ -701,8 +714,8 @@ function createGlobalSetup(options, userSetup) {
           keep: opts.keep === true,
           startTime: (/* @__PURE__ */ new Date()).toISOString(),
           instanceId: computeInstanceId(opts.projectName, runLabel),
-          shardIndex,
-          shardTotal
+          shardIndex: shard?.current,
+          shardTotal: shard?.total
         },
         auth
       );

package/dist/index.js

@@ -143,6 +143,7 @@ var PIWI_SELECTION_ENV = {
   hash: "PIWI_SELECTION_HASH",
   count: "PIWI_SELECTION_COUNT"
 };
+var PIWI_SHARD_ENV = "PIWI_SHARD";
 var PIWI_PROBE_ENV = {
   flag: "PIWI_PROBE",
   plan: "PIWI_PROBE_PLAN",
@@ -2857,6 +2858,13 @@ function maskTokenLike(text) {
   return text.replace(DATA_URI_RE, "data:[masked]").replace(JWT_RE, "[masked-token]").replace(LONG_HEX_RE, "[masked-hex]");
 }
 
+// ../core/src/locator-break.ts
+function sameFilePath(a, b) {
+  const x = a.replace(/\\/g, "/").replace(/^\.\//, "");
+  const y = b.replace(/\\/g, "/").replace(/^\.\//, "");
+  return x === y || x.endsWith("/" + y) || y.endsWith("/" + x);
+}
+
 // ../core/src/step-tree.ts
 var SPAN_TOLERANCE_MS = 1;
 var SETUP_CONTAINER_RE = /^before hooks$/i;
@@ -2878,9 +2886,26 @@ function errorMessage2(step) {
   if (typeof error === "string") return error;
   return str(error?.message);
 }
+function errorLocation(step) {
+  const error = step.error;
+  return typeof error === "string" ? "" : str(error?.location);
+}
+function parseLocation(location) {
+  const m = /^(.+):(\d+):(\d+)$/.exec(location.trim());
+  return m ? { file: m[1], line: Number(m[2]), column: Number(m[3]) } : null;
+}
+function sameCodeLocation(a, b) {
+  const x = typeof a === "string" ? parseLocation(a) : a;
+  const y = typeof b === "string" ? parseLocation(b) : b;
+  if (!x || !y) return false;
+  return x.line === y.line && x.column === y.column && sameFilePath(x.file, y.file);
+}
 function isFailedStep(step) {
   return step.failed === true || errorMessage2(step).trim().length > 0;
 }
+function isRecoveredStep(step) {
+  return step.recovered === true;
+}
 function isCaptureStep(step) {
   const title = str(step.title).trim();
   if (CAPTURE_ATTACH_RE.test(title) || CAPTURE_FIXTURE_RE.test(title)) return true;
@@ -2935,18 +2960,72 @@ function stepPhases(steps, parents = stepParents(steps)) {
     return "body";
   });
 }
-function failingStepIndex(steps, parents = stepParents(steps)) {
+function firstLine(message) {
+  return stripAnsi(str(message)).split("\n")[0].trim();
+}
+function errorHeads(error) {
+  return error.split(/\n---\n/).map(firstLine).filter((head) => head.length > 0);
+}
+function sameError(inner, outer) {
+  const a = firstLine(errorMessage2(inner));
+  const b = firstLine(errorMessage2(outer));
+  if (!a || !b) return true;
+  if (a !== b) return false;
+  const at = errorLocation(inner);
+  const bt = errorLocation(outer);
+  return !at || !bt || sameCodeLocation(at, bt);
+}
+function lastByPhase(indices, phases) {
+  for (const phase of ["body", "setup", "teardown"]) {
+    const inPhase = indices.filter((i) => phases[i] === phase);
+    if (inPhase.length > 0) return inPhase[inPhase.length - 1];
+  }
+  return null;
+}
+function failingChainEnds(steps, parents) {
   const candidates = [];
   steps.forEach((step, i) => {
-    if (isFailedStep(step) && !isCaptureStep(step)) candidates.push(i);
+    if (isFailedStep(step) && !isCaptureStep(step) && !isRecoveredStep(step)) candidates.push(i);
   });
-  if (candidates.length === 0) return null;
-  let current = candidates[0];
-  for (; ; ) {
-    const inner = candidates.find((c) => c > current && isDescendant(c, current, parents));
-    if (inner === void 0) return current;
-    current = inner;
+  const isCandidate = new Set(candidates);
+  const hasFailedAncestor = (i) => {
+    for (let p = parents[i] ?? -1; p !== -1; p = parents[p] ?? -1) if (isCandidate.has(p)) return true;
+    return false;
+  };
+  return candidates.filter((root) => !hasFailedAncestor(root)).map((root) => {
+    let current = root;
+    for (; ; ) {
+      const inner = candidates.filter((c) => c > current && isDescendant(c, current, parents));
+      const carrying = inner.filter((c) => sameError(steps[c], steps[current]));
+      if (carrying.length === 0) return current;
+      current = carrying[carrying.length - 1];
+    }
+  });
+}
+function failingStepIndex(steps, parents = stepParents(steps), error) {
+  const ends = failingChainEnds(steps, parents);
+  if (ends.length === 0) return null;
+  const phases = stepPhases(steps, parents);
+  if (error) {
+    const heads = errorHeads(error);
+    const headOf = (i) => firstLine(errorMessage2(steps[i]));
+    const frame = extractTopFrame(error);
+    if (frame) {
+      const thrownThere = ends.filter(
+        (i) => heads.includes(headOf(i)) && sameCodeLocation(errorLocation(steps[i]) || str(steps[i].location), frame)
+      );
+      const located = lastByPhase(thrownThere, phases);
+      if (located !== null) return located;
+    }
+    for (const head of heads) {
+      const matching = lastByPhase(
+        ends.filter((i) => headOf(i) === head),
+        phases
+      );
+      if (matching !== null) return matching;
+    }
   }
+  return lastByPhase(ends, phases) ?? ends[ends.length - 1];
 }
 function stepHookName(step) {
   const title = str(step.title).trim();
@@ -2959,11 +3038,8 @@ function stepHookName(step) {
   if (category === "hook" && title && !isPhaseContainer(step)) return `hook "${title}"`;
   return null;
 }
-function firstLine(message) {
-  return stripAnsi(str(message)).split("\n")[0].trim();
-}
 function failureHookContext(steps, error, parents = stepParents(steps)) {
-  const index = failingStepIndex(steps, parents);
+  const index = failingStepIndex(steps, parents, error);
   if (index === null) return null;
   const phase = stepPhases(steps, parents)[index];
   if (phase === "body") return null;
@@ -3029,6 +3105,28 @@ function normalizeStepParams(raw) {
   }
   return count > 0 ? out : void 0;
 }
+function locationText(location) {
+  if (!location || typeof location.file !== "string" || !location.file) return void 0;
+  return `${location.file}:${location.line}:${location.column}`;
+}
+function markRecoveredSteps(steps, errors) {
+  const fatal = errors.map((error) => ({
+    head: firstErrorLine(error.message),
+    location: locationText(error.location)
+  }));
+  for (const step of steps) {
+    if (!step.error) continue;
+    const head = firstErrorLine(step.error.message);
+    const thrownAt = step.error.location;
+    const isFatal = fatal.some(
+      (error) => error.head === head && (!error.location || !thrownAt || sameCodeLocation(error.location, thrownAt))
+    );
+    if (!isFatal) step.recovered = true;
+  }
+}
+function firstErrorLine(message) {
+  return stripAnsi(typeof message === "string" ? message : "").split("\n")[0].trim();
+}
 function flattenSteps(steps, depth = 0) {
   const result = [];
   for (const step of steps) {
@@ -3043,17 +3141,21 @@ function flattenSteps(steps, depth = 0) {
     if (params) flat.params = params;
     if (step.error?.message) {
       flat.error = { message: step.error.message };
+      const thrownAt = locationText(step.error.location);
+      if (thrownAt) flat.error.location = thrownAt;
       flat.failed = true;
     }
-    if (step.location) flat.location = `${step.location.file}:${step.location.line}:${step.location.column}`;
+    const location = locationText(step.location);
+    if (location) flat.location = location;
     if (step.startTime) flat.startTime = step.startTime instanceof Date ? step.startTime.getTime() : step.startTime;
     result.push(flat);
     if (step.steps?.length > 0) result.push(...flattenSteps(step.steps, depth + 1));
   }
   return result;
 }
-function collectStepMetrics(steps) {
+function collectStepMetrics(steps, errors) {
   const flatSteps = flattenSteps(steps);
+  if (errors) markRecoveredSteps(flatSteps, errors);
   const totalStepDuration = steps.reduce((sum, s) => sum + (s.duration || 0), 0);
   let slowestStep = null;
   for (const s of flatSteps) {
@@ -3363,6 +3465,20 @@ function readSelectionStamp(env = process.env) {
   return { key, version, resolvedHash, resolvedCount };
 }
 
+// src/internal/support/shard-info.ts
+function parseShardSpec(raw) {
+  const match = raw?.trim().match(/^(\d+)\s*\/\s*(\d+)$/);
+  if (!match) return null;
+  const current = Number(match[1]);
+  const total = Number(match[2]);
+  return current >= 1 && current <= total && total > 1 ? { current, total } : null;
+}
+function resolveShardInfo(config, env = process.env) {
+  const pwShard = config.shard;
+  if (pwShard && pwShard.total > 1) return { current: pwShard.current, total: pwShard.total };
+  return parseShardSpec(env[PIWI_SHARD_ENV]);
+}
+
 // src/internal/support/run-mode.ts
 var PW_UI_FLAGS = ["--ui", "--ui-host", "--ui-port"];
 function isUiMode(argv = process.argv) {
@@ -3554,9 +3670,7 @@ function createGlobalSetup(options, userSetup) {
     try {
       const auth = await httpClient.resolveAuth(opts);
       const runLabel = opts.runLabel || detectCiRunLabel();
-      const pwShard = config.shard;
-      const shardIndex = pwShard?.current;
-      const shardTotal = pwShard?.total;
+      const shard = resolveShardInfo(config);
       const response = await httpClient.postJSON(
         "/api/test-runs/setup",
         {
@@ -3567,8 +3681,8 @@ function createGlobalSetup(options, userSetup) {
           keep: opts.keep === true,
           startTime: (/* @__PURE__ */ new Date()).toISOString(),
           instanceId: computeInstanceId(opts.projectName, runLabel),
-          shardIndex,
-          shardTotal
+          shardIndex: shard?.current,
+          shardTotal: shard?.total
         },
         auth
       );
@@ -3745,6 +3859,7 @@ var LONG_HEX_RE2 = /\b[0-9a-f]{8,}\b/gi;
 var SHORT_HEX_RE = /\b(?=[0-9a-f]*[a-f])(?=[0-9a-f]*[0-9])[0-9a-f]{6,7}\b/gi;
 var URL_RE2 = /\bhttps?:\/\/[^\s'"`)]+/gi;
 var EMAIL_RE = /\b[\w.+-]+@[\w-]+(?:\.[\w-]+)+\b/gi;
+var SELECTOR_OPTION_RE = /\b(name|hasText|hasNotText|has|placeholder|label|title|alt|exact)\s*:\s*(['"`])(?:\\.|(?!\2)[\s\S])*?\2/gi;
 function classifyError(text) {
   if (/strict mode violation/i.test(text)) return "strict-mode";
   if (/\bexpect\(|\bexpect\.|Expected (?:string|substring|pattern|value)|\.toHave|\.toBe|\.toContain|\.toEqual/.test(text))
@@ -3758,10 +3873,13 @@ function classifyError(text) {
 function maskVolatile(text) {
   return text.replace(/^(\s*(?:Received|Expected)[^:\n]*:).*$/gm, "$1 <VALUE>").replace(URL_RE2, "<URL>").replace(EMAIL_RE, "<EMAIL>").replace(UUID_RE, "<UUID>").replace(LONG_HEX_RE2, "<HASH>").replace(SHORT_HEX_RE, "<HASH>").replace(/([A-Za-z])?(\d+)/g, (whole, letter) => letter ? whole : "<N>");
 }
+function maskSelectorOptions(text) {
+  return text.replace(SELECTOR_OPTION_RE, (_m, key) => `${key}: <STR>`);
+}
 function extractErrorSignature(rawError) {
   const text = stripAnsi(rawError);
   const errorType = classifyError(text);
-  const normalizedMessage = maskVolatile(extractMessageHead(text));
+  const normalizedMessage = maskVolatile(maskSelectorOptions(extractMessageHead(text)));
   const selector = extractSelector(text);
   const topFrameFile = extractTopFrameFile(text);
   const signature = (normalizedMessage.split("\n")[0] || "").slice(0, 200) || "Unknown error";
@@ -5466,10 +5584,10 @@ function describeFailureText(raw, ctx) {
   if (!raw || !raw.trim()) return null;
   return describeFailure(parsePlaywrightError(raw, { stepParams: ctx?.stepParams }), ctx);
 }
-function headlineStep(steps) {
+function headlineStep(steps, error) {
   if (!steps || steps.length === 0) return null;
   const parents = stepParents(steps);
-  const failed = failingStepIndex(steps, parents);
+  const failed = failingStepIndex(steps, parents, error);
   if (failed !== null) return steps[failed];
   const phases = stepPhases(steps, parents);
   for (let i = steps.length - 1; i >= 0; i--) {
@@ -5478,17 +5596,17 @@ function headlineStep(steps) {
   }
   return steps[steps.length - 1];
 }
-function lastStepTitle(steps) {
-  const title = headlineStep(steps)?.title;
+function lastStepTitle(steps, error) {
+  const title = headlineStep(steps, error)?.title;
   return typeof title === "string" ? title : null;
 }
-function failingStepParams(steps) {
-  return headlineStep(steps)?.params ?? null;
+function failingStepParams(steps, error) {
+  return headlineStep(steps, error)?.params ?? null;
 }
 function stepHeadlineContext(steps, error) {
   return {
-    lastStepTitle: lastStepTitle(steps),
-    stepParams: failingStepParams(steps),
+    lastStepTitle: lastStepTitle(steps, error),
+    stepParams: failingStepParams(steps, error),
     failedIn: steps && steps.length > 0 ? failureHookContext(steps, error ?? null) : null
   };
 }
@@ -5670,9 +5788,8 @@ var PiwiDashboardReporter = class _PiwiDashboardReporter {
       this.metadata = flakeRunMetadata(stamp, this.metadata);
     }
     this.plannedTests = suite.allTests();
-    const pwShard = config.shard;
-    if (pwShard?.total && pwShard.total > 1) {
-      this.shardInfo = { current: pwShard.current, total: pwShard.total };
+    this.shardInfo = resolveShardInfo(config);
+    if (this.shardInfo) {
       this.logger.info(`Shard ${this.shardInfo.current}/${this.shardInfo.total} detected`);
     }
     this.streamManager?.start(
@@ -5827,7 +5944,7 @@ var PiwiDashboardReporter = class _PiwiDashboardReporter {
       if (frames.length) testCase.testSourceFrames = frames;
     }
     if (this.options.collectPerformanceMetrics && result.steps?.length > 0) {
-      testCase.performanceMetrics = collectStepMetrics(result.steps);
+      testCase.performanceMetrics = collectStepMetrics(result.steps, result.errors);
       const stepEvents = extractTestStepEvents(result.steps, result.startTime);
       const waitEvents = extractWaitEvents(result.steps);
       const allEvents = [...stepEvents, ...waitEvents];
@@ -9938,15 +10055,15 @@ function entryPath(params) {
   const name = `${slug(params.testTitle)}.${slug(params.template)}.${hash}.json`;
   return path25.join(entryDir(params.specFile, params.dir), name);
 }
-function parseLocation(location) {
+function parseLocation2(location) {
   const match = /:(\d+):(\d+)$/.exec(location);
   if (!match) return null;
   return { line: Number(match[1]), col: Number(match[2]) };
 }
 function orderByPosition(locations) {
   return [...new Set(locations)].sort((a, b) => {
-    const pa = parseLocation(a);
-    const pb = parseLocation(b);
+    const pa = parseLocation2(a);
+    const pb = parseLocation2(b);
     if (!pa || !pb) return a < b ? -1 : a > b ? 1 : 0;
     return pa.line - pb.line || pa.col - pb.col;
   });

package/dist/internal/capture/capture-fixtures.js

@@ -2813,6 +2813,7 @@ var LONG_HEX_RE = /\b[0-9a-f]{8,}\b/gi;
 var SHORT_HEX_RE = /\b(?=[0-9a-f]*[a-f])(?=[0-9a-f]*[0-9])[0-9a-f]{6,7}\b/gi;
 var URL_RE = /\bhttps?:\/\/[^\s'"`)]+/gi;
 var EMAIL_RE = /\b[\w.+-]+@[\w-]+(?:\.[\w-]+)+\b/gi;
+var SELECTOR_OPTION_RE = /\b(name|hasText|hasNotText|has|placeholder|label|title|alt|exact)\s*:\s*(['"`])(?:\\.|(?!\2)[\s\S])*?\2/gi;
 function classifyError(text) {
   if (/strict mode violation/i.test(text)) return "strict-mode";
   if (/\bexpect\(|\bexpect\.|Expected (?:string|substring|pattern|value)|\.toHave|\.toBe|\.toContain|\.toEqual/.test(text))
@@ -2826,10 +2827,13 @@ function classifyError(text) {
 function maskVolatile(text) {
   return text.replace(/^(\s*(?:Received|Expected)[^:\n]*:).*$/gm, "$1 <VALUE>").replace(URL_RE, "<URL>").replace(EMAIL_RE, "<EMAIL>").replace(UUID_RE, "<UUID>").replace(LONG_HEX_RE, "<HASH>").replace(SHORT_HEX_RE, "<HASH>").replace(/([A-Za-z])?(\d+)/g, (whole, letter) => letter ? whole : "<N>");
 }
+function maskSelectorOptions(text) {
+  return text.replace(SELECTOR_OPTION_RE, (_m, key) => `${key}: <STR>`);
+}
 function extractErrorSignature(rawError) {
   const text = stripAnsi(rawError);
   const errorType = classifyError(text);
-  const normalizedMessage = maskVolatile(extractMessageHead(text));
+  const normalizedMessage = maskVolatile(maskSelectorOptions(extractMessageHead(text)));
   const selector = extractSelector(text);
   const topFrameFile = extractTopFrameFile(text);
   const signature = (normalizedMessage.split("\n")[0] || "").slice(0, 200) || "Unknown error";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.41.0",
+  "version": "0.42.0",
   "description": "Playwright reporter that streams results, traces and HTML reports to a Piwi Dashboard instance",
   "url": "https://github.com/PiwiTests/platform",
   "homepage": "https://piwitests.dev",

package/templates/skills/investigate-failure/SKILL.md

@@ -27,7 +27,7 @@ Prefer the **Piwi MCP server** if it is connected to this agent (tools named `li
 
 7. **Verify.** Re-run the affected spec(s): `npx playwright test <file>`. Confirm they pass and the new run is green in the dashboard (`get_run_insights` compares against the last green run: regressions cleared, nothing new broken).
 
-8. **Close the loop (optional).** With packages/reporter/admin access, `set_cluster_status` marks the cluster resolved with a note so it drops off the triage queue.
+8. **Close the loop (optional).** With reporter or admin access, `set_cluster_status` marks the cluster resolved with a note so it drops off the triage queue.
 
 ## Guardrails
 

package/templates/skills/setup-piwi/SKILL.md

@@ -47,7 +47,7 @@ change it to import from the fixtures file instead, e.g. `import { test, expect
 
 ## Authentication
 
-If the dashboard has auth enabled, runs need an API key. Have the user create one in the dashboard (**Settings → Users → API keys**; keys start with `pd_`), then put it in `.env` as `PIWI_API_KEY=pd_...` and make sure `.env` is git-ignored. Never hardcode a key into `playwright.config.ts` or commit it. In CI, pass it as a secret (`PIWI_API_KEY`).
+If the dashboard has auth enabled, runs need an API key. Have the user create one in the dashboard (**Settings → Account → API keys**; keys start with `pd_`), then put it in `.env` as `PIWI_API_KEY=pd_...` and make sure `.env` is git-ignored. Never hardcode a key into `playwright.config.ts` or commit it. In CI, pass it as a secret (`PIWI_API_KEY`).
 
 ## Verify it worked
 

package/templates/skills/stabilize-flaky-tests/SKILL.md

@@ -1,36 +1,51 @@
 ---
 name: stabilize-flaky-tests
-description: Find the flakiest Playwright tests from Piwi's flaky analysis and fix the root cause of the intermittency, ranked by impact. Use when the user asks to "fix flaky tests", "reduce flakiness", "why is this test flaky", or wants to clean up an unreliable suite.
+description: Find the flakiest Playwright tests from Piwi's flaky analysis, make each one fail on demand with Piwi's Flake Lab, fix what the reproducing condition points at, and prove the fix under that same condition. Use when the user asks to "fix flaky tests", "reduce flakiness", "why is this test flaky", or wants to clean up an unreliable suite.
 ---
 
 # Stabilize flaky tests with Piwi
 
-Piwi scores every test's flakiness over its whole run history and ranks it by impact, so you spend effort on the tests that actually cost the team — not whichever one failed most recently. This skill picks the worst offenders, fixes the *cause* of the intermittency, and confirms the score improves.
+Piwi scores every test's flakiness over its whole run history and ranks it by impact, so you spend effort on the tests that actually cost the team — not whichever one failed most recently. For each test it also ranks **suspects** from that history (a route that is slower when it fails, a test running alongside, load), and its **Flake Lab** replays each suspect as a condition next to a control until the failure reproduces. A reproduced condition proves the cause, and the same condition later proves the fix. This skill follows that loop: rank, reproduce, fix, verify.
 
 ## How you reach Piwi
 
-Prefer the **Piwi MCP server** if it is connected (`list_flaky_tests`, `get_test_stability_trend`, `get_test_case`, `get_spec_health`). Otherwise use the dashboard's **Flaky** tab for the project and work from what it shows plus the repo.
+Prefer the **Piwi MCP server** if it is connected (`list_flaky_tests`, `get_flake_profile`, `plan_flake_experiment`, `get_test_case`, `get_test_stability_trend`). Otherwise use the dashboard's **Flaky** tab and the test's **Flakiness** tab, and work from what they show plus the repo. The lab itself is a command you run from the project root: `npx @piwitests/reporter flake`. It needs the Piwi capture fixtures in the specs (`piwiFixtures`) and a dashboard URL and reporter API key (`PIWI_DASHBOARD_URL`, `PIWI_API_KEY`, or the project's `.env`).
 
 ## Steps
 
-1. **Rank the flaky tests.** Call `list_flaky_tests` for the project. It returns each test's flaky score, impact ranking, and a **root-cause category**. Take the top few by impact — do not try to fix the whole list at once.
+1. **Rank the flaky tests.** Call `list_flaky_tests` for the project and take the top few by impact. Do not try to fix the whole list at once.
 
-2. **Understand one test's pattern.** For a chosen test, call `get_test_stability_trend` (is it getting worse, or already stable again?) and `get_test_case` (recent pass/fail history). Read a representative failing execution (`get_test_run_case` / `explain_failure`) for the error, steps, console, and network at the moment it flaked.
+2. **Read the suspects.** For a chosen test, call `get_flake_profile`. Each suspect carries raw counts ("slow in 7 of 8 failures and 3 of 44 passes"), the condition that would test it, and, once the lab has run, its latest result (`lab`). `experiments` lists what the lab already found; if an experiment reproduced the test, skip to step 4. Read one failing execution (`get_test_run_case` / `explain_failure`) for the error at the moment it flaked.
 
-3. **Identify the cause.** Common categories and their fixes:
-   - **Timing / race** — replace fixed waits and manual sleeps with Playwright web-first assertions (`await expect(locator).toBeVisible()`), await the network/UI state the test depends on, not a timeout.
-   - **Locator instability** — a selector that resolves ambiguously or intermittently; heal it (see the `apply-locator-healing` skill) or scope it.
-   - **Test-order / shared state** — leaking storage, cookies, or a shared backend row; isolate setup, use a fresh context, or a unique fixture per test.
-   - **Slow / unreliable endpoint** — check `get_network_requests`; if a real endpoint is intermittently slow or 500s, that is a product bug, not a test bug — report it rather than papering over it with retries.
+3. **Reproduce it.** Run the lab on the test (`plan_flake_experiment` gives the exact commands and the arms it will run, with an estimate):
 
-4. **Fix the root cause.** Make the change in the spec (or the app, when the flake is a real defect). Do **not** "fix" flakiness by adding retries or increasing timeouts — that hides it; the goal is a test that passes deterministically.
+   ```bash
+   npx @piwitests/reporter flake <testCaseId>
+   ```
 
-5. **Verify.** Re-run the test several times to shake out intermittency: `npx playwright test <file> --repeat-each=5` (raise the count for stubborn ones). It should pass every time. Over the next runs, confirm the flaky score falls in the dashboard (`get_test_stability_trend`).
+   It runs a control, then one arm per suspect, retries off, and counts only failures with the same error as in CI. Exit code `0` means an arm reproduced the failure ("reproduced by delaying GET /api/cart to 1.8 s: 3/4 against 0/10, p = 0.011"); `1` means nothing did; `2` is an error (read its message: often the fixtures are not in use). Use `--suspect <n>` to test one suspect, `--all` to also try every condition at once. If the output warns that this checkout differs from the commit of the failures, say so in your report.
 
-6. **Report.** For each test you touched: the root-cause category, the change, and the repeat-run result. List any remaining high-impact flaky tests so the user can decide whether to continue.
+   If nothing reproduces, do not guess a fix from the suspects alone. Report the arms and their counts, and fall back to reading the failure and the attempts diff.
+
+4. **Fix what the reproducing condition points at.** The condition names the cause:
+   - **A delayed route** — the test (or the app) acts before that response arrives. Wait for the response or for the UI state it produces (`await page.waitForResponse(...)`, `await expect(locator).toHaveText(...)`), not for a timeout.
+   - **A failed route** — the app does not handle that error. If the endpoint really fails in CI, that is a product finding: report it rather than hiding it in the test.
+   - **Another test alongside or just before** — shared state: a backend row, storage, a fixture both use. Isolate it (unique data per test, a fresh context, its own fixture).
+   - **CPU load** — a race the load exposes; the fix is the same as a delayed route: await the state the test depends on.
+   Make the change in the spec, or in the app when the flake is a real defect.
+
+5. **Verify the fix under the same condition.** Run:
+
+   ```bash
+   npx @piwitests/reporter flake verify <testCaseId>
+   ```
+
+   It reruns the arm that reproduced the failure, and its control, for enough runs to say the fix holds at the rate it failed. Exit code `0` means the fix held; `1` means it still fails (or too few runs passed to say). "It passed ten times in a row" is not a verification; this is.
+
+6. **Report.** For each test you touched: the reproducing condition and its counts, the change, and the verify result. List any remaining high-impact flaky tests, and any test the lab could not reproduce, so the user can decide whether to continue.
 
 ## Guardrails
 
-- Fix the cause, never the symptom — no blanket `test.retry`, no bumped global timeout, no `waitForTimeout` sprinkles.
+- Fix the cause, never the symptom — no blanket `test.retry`, no bumped global or per-test timeout, no `waitForTimeout` sprinkles. A longer timeout can make `flake verify` pass without fixing anything; do not do it.
 - A test that flakes because a *real* endpoint is unreliable is a product finding; surface it instead of hiding it in the test.
-- Stabilize a few high-impact tests well rather than lightly touching many. Prove each one with repeated runs before moving on.
+- Stabilize a few high-impact tests well rather than lightly touching many. Prove each one with `piwi flake verify` before moving on.