@piwitests/reporter 0.36.0 → 0.38.0

package/dist/internal/capture/pick-on-failure.d.ts

@@ -38,7 +38,11 @@ interface UserPickResult {
     /** Stable parents the human blessed in the anchor step, when any. */
     anchors?: PickedAnchorInfo[];
 }
-/** Parse a Playwright locator expression into `{ method, args }` (leaf of any chain). Exported for tests. */
+/**
+ * Parse a Playwright locator expression into `{ method, args }` for its leaf —
+ * the last locating call, which identifies the resolved element, mirroring the
+ * server's `extractLeafSelector`. Exported for tests.
+ */
 declare function parseLeafLocatorExpression(rawExpr: string): {
     method: string;
     args: unknown[];

package/dist/internal/capture/pick-on-failure.js

@@ -43,6 +43,288 @@ __export(pick_on_failure_exports, {
 module.exports = __toCommonJS(pick_on_failure_exports);
 var path2 = __toESM(require("path"));
 
+// ../core/src/locator-chain.ts
+var LOCATING_METHODS = /* @__PURE__ */ new Set([
+  "getByRole",
+  "getByTestId",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "locator",
+  "frameLocator"
+]);
+var NARROWING_METHODS = /* @__PURE__ */ new Set([
+  "filter",
+  "first",
+  "last",
+  "nth",
+  "and",
+  "or",
+  "visible",
+  "contentFrame",
+  "owner"
+]);
+var LOCATOR_CHAIN_METHODS = /* @__PURE__ */ new Set([...LOCATING_METHODS, ...NARROWING_METHODS]);
+var LocatorParseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LocatorParseError";
+  }
+};
+var SIMPLE_ESCAPES = {
+  n: "\n",
+  t: "	",
+  r: "\r",
+  b: "\b",
+  f: "\f",
+  v: "\v",
+  "0": "\0"
+};
+var Parser = class {
+  constructor(src) {
+    this.src = src;
+    this.i = 0;
+  }
+  parseTopLevel() {
+    const chain = this.parseChain();
+    this.skipSpace();
+    if (this.i < this.src.length) this.fail("unexpected text");
+    return chain;
+  }
+  fail(message) {
+    throw new LocatorParseError(`${message} at "${this.src.slice(this.i, this.i + 20)}"`);
+  }
+  skipSpace() {
+    while (this.i < this.src.length && /\s/.test(this.src[this.i])) this.i++;
+  }
+  peek() {
+    return this.src[this.i];
+  }
+  expect(ch) {
+    this.skipSpace();
+    if (this.src[this.i] !== ch) this.fail(`expected "${ch}"`);
+    this.i++;
+  }
+  identifier() {
+    const m = /^[A-Za-z_$][\w$]*/.exec(this.src.slice(this.i));
+    if (!m) this.fail("expected a name");
+    this.i += m[0].length;
+    return m[0];
+  }
+  /**
+   * A chain of calls joined by `.`. With `lenient`, parsing stops before the
+   * first link that doesn't parse instead of failing, so a chain followed by
+   * other text (an error message) is read up to where it ends. `spans` receives
+   * where each top-level call starts and ends.
+   */
+  parseChain(opts = {}) {
+    this.skipSpace();
+    const calls = [];
+    for (; ; ) {
+      const before = this.i;
+      if (calls.length > 0) this.i++;
+      this.skipSpace();
+      const start = this.i;
+      try {
+        calls.push(this.parseCall(calls.length === 0));
+      } catch (error) {
+        if (!opts.lenient || calls.length === 0) throw error;
+        this.i = before;
+        break;
+      }
+      opts.spans?.push({ start, end: this.i });
+      const end = this.i;
+      this.skipSpace();
+      if (this.peek() !== ".") {
+        this.i = end;
+        break;
+      }
+    }
+    return { calls };
+  }
+  /** Where the parser stopped. */
+  get position() {
+    return this.i;
+  }
+  parseCall(first) {
+    this.skipSpace();
+    const method = this.identifier();
+    if (!LOCATOR_CHAIN_METHODS.has(method)) this.fail(`unsupported method ${method}()`);
+    if (first && !LOCATING_METHODS.has(method)) this.fail(`${method}() needs a locator before it`);
+    this.expect("(");
+    const args = [];
+    this.skipSpace();
+    if (this.peek() === ")") {
+      this.i++;
+      return { method, args };
+    }
+    for (; ; ) {
+      args.push(this.parseValue());
+      this.skipSpace();
+      if (this.peek() === ",") {
+        this.i++;
+        this.skipSpace();
+        if (this.peek() === ")") {
+          this.i++;
+          break;
+        }
+        continue;
+      }
+      this.expect(")");
+      break;
+    }
+    return { method, args };
+  }
+  parseValue() {
+    this.skipSpace();
+    const ch = this.peek();
+    if (ch === "'" || ch === '"' || ch === "`") return { type: "string", value: this.parseString() };
+    if (ch === "/") return this.parseRegex();
+    if (ch === "{") return this.parseObject();
+    if (ch !== void 0 && /[-\d]/.test(ch)) {
+      const m = /^-?\d+(?:\.\d+)?/.exec(this.src.slice(this.i));
+      if (!m) this.fail("expected a number");
+      this.i += m[0].length;
+      return { type: "number", value: Number(m[0]) };
+    }
+    const rest = this.src.slice(this.i);
+    if (/^true\b/.test(rest)) {
+      this.i += 4;
+      return { type: "boolean", value: true };
+    }
+    if (/^false\b/.test(rest)) {
+      this.i += 5;
+      return { type: "boolean", value: false };
+    }
+    if (/^[A-Za-z_$]/.test(rest)) return { type: "chain", chain: this.parseChain() };
+    return this.fail("expected a value");
+  }
+  /** A quoted string, decoding the escapes `JSON.stringify` and JavaScript produce. */
+  parseString() {
+    const quote = this.src[this.i];
+    let out = "";
+    this.i++;
+    while (this.i < this.src.length) {
+      const c = this.src[this.i];
+      if (c === quote) {
+        this.i++;
+        return out;
+      }
+      if (c !== "\\") {
+        out += c;
+        this.i++;
+        continue;
+      }
+      const next = this.src[this.i + 1];
+      if (next === void 0) break;
+      const simple = SIMPLE_ESCAPES[next];
+      if (simple !== void 0) {
+        out += simple;
+        this.i += 2;
+        continue;
+      }
+      const hex = next === "u" && this.src[this.i + 2] === "{" ? /^u\{([0-9a-fA-F]{1,6})\}/.exec(this.src.slice(this.i + 1)) : next === "u" ? /^u([0-9a-fA-F]{4})/.exec(this.src.slice(this.i + 1)) : next === "x" ? /^x([0-9a-fA-F]{2})/.exec(this.src.slice(this.i + 1)) : null;
+      if (hex) {
+        out += String.fromCodePoint(parseInt(hex[1], 16));
+        this.i += 1 + hex[0].length;
+        continue;
+      }
+      if (next === "u" || next === "x") this.fail("malformed escape");
+      out += next;
+      this.i += 2;
+    }
+    return this.fail("unterminated string");
+  }
+  parseRegex() {
+    let j = this.i + 1;
+    let inClass = false;
+    while (j < this.src.length) {
+      const c = this.src[j];
+      if (c === "\\") {
+        j += 2;
+        continue;
+      }
+      if (c === "[") inClass = true;
+      else if (c === "]") inClass = false;
+      else if (c === "/" && !inClass) break;
+      j++;
+    }
+    if (j >= this.src.length) this.fail("unterminated regex");
+    const source = this.src.slice(this.i + 1, j);
+    const flags = /^[a-z]*/.exec(this.src.slice(j + 1))[0];
+    this.i = j + 1 + flags.length;
+    return { type: "regex", source, flags };
+  }
+  parseObject() {
+    this.expect("{");
+    const entries = [];
+    for (; ; ) {
+      this.skipSpace();
+      if (this.peek() === "}") {
+        this.i++;
+        break;
+      }
+      const ch = this.peek();
+      const key = ch === "'" || ch === '"' ? this.parseString() : this.identifier();
+      this.expect(":");
+      entries.push([key, this.parseValue()]);
+      this.skipSpace();
+      if (this.peek() === ",") {
+        this.i++;
+        continue;
+      }
+      this.expect("}");
+      break;
+    }
+    return { type: "object", entries };
+  }
+};
+function parseLocatorChain(expr) {
+  const trimmed = expr.trim().replace(/^(?:await\s+)?(?:this\.)?page\./, "");
+  if (!trimmed) throw new LocatorParseError("empty expression");
+  return new Parser(trimmed).parseTopLevel();
+}
+function tryParseLocatorChain(expr) {
+  try {
+    return parseLocatorChain(expr);
+  } catch {
+    return null;
+  }
+}
+function parseLeafLocatorCall(expr) {
+  const chain = tryParseLocatorChain(expr);
+  if (!chain) return null;
+  for (let i = chain.calls.length - 1; i >= 0; i--) {
+    if (LOCATING_METHODS.has(chain.calls[i].method)) return chain.calls[i];
+  }
+  return null;
+}
+function locatorCallValues(call, opts = {}) {
+  const value = (arg) => {
+    switch (arg.type) {
+      case "string":
+      case "number":
+      case "boolean":
+        return arg.value;
+      case "regex":
+        return opts.regexAsText ? `/${arg.source}/${arg.flags}` : void 0;
+      case "object": {
+        const out = {};
+        for (const [key, v] of arg.entries) {
+          const plain = value(v);
+          if (plain !== void 0) out[key] = plain;
+        }
+        return out;
+      }
+      case "chain":
+        return void 0;
+    }
+  };
+  return call.args.map(value).filter((v) => v !== void 0);
+}
+
 // ../picker-dom/src/overlay-element.ts
 function installPickerOverlay(arg) {
   const g = globalThis;
@@ -1118,86 +1400,9 @@ function renderFailing(failed) {
 
 // src/internal/capture/pick-on-failure.ts
 var ANSI_RE = /\[[0-9;]*m/g;
-function endOfString(s, start) {
-  const q = s[start];
-  for (let i = start + 1; i < s.length; i++) {
-    if (s[i] === "\\") {
-      i++;
-      continue;
-    }
-    if (s[i] === q) return i;
-  }
-  return s.length - 1;
-}
-function matchBrace(s, start) {
-  let depth = 0;
-  for (let i = start; i < s.length; i++) {
-    if (s[i] === "{") depth++;
-    else if (s[i] === "}" && --depth === 0) return i;
-  }
-  return s.length - 1;
-}
-function parseOptions(src) {
-  const obj = {};
-  const re = /(\w+)\s*:\s*('(?:\\.|[^'])*'|"(?:\\.|[^"])*"|true|false|-?\d+)/g;
-  let m;
-  while ((m = re.exec(src)) !== null) {
-    const key = m[1];
-    const raw = m[2];
-    if (raw === "true") obj[key] = true;
-    else if (raw === "false") obj[key] = false;
-    else if (/^-?\d+$/.test(raw)) obj[key] = Number(raw);
-    else obj[key] = raw.slice(1, -1).replace(/\\(.)/g, "$1");
-  }
-  return obj;
-}
-function parseArgs(inner) {
-  const args = [];
-  let i = 0;
-  while (i < inner.length) {
-    const c = inner[i];
-    if (c === " " || c === ",") {
-      i++;
-      continue;
-    }
-    if (c === "'" || c === '"') {
-      const end = endOfString(inner, i);
-      args.push(inner.slice(i + 1, end).replace(/\\(.)/g, "$1"));
-      i = end + 1;
-      continue;
-    }
-    if (c === "{") {
-      const end = matchBrace(inner, i);
-      args.push(parseOptions(inner.slice(i, end + 1)));
-      i = end + 1;
-      continue;
-    }
-    i++;
-  }
-  return args;
-}
-function leafExpression(expr) {
-  let depth = 0;
-  let leafStart = 0;
-  for (let i = 0; i < expr.length - 1; i++) {
-    const c = expr[i];
-    if (c === "'" || c === '"') {
-      i = endOfString(expr, i);
-      continue;
-    }
-    if (c === "(") depth++;
-    else if (c === ")") {
-      depth--;
-      if (depth === 0 && expr[i + 1] === ".") leafStart = i + 2;
-    }
-  }
-  return expr.slice(leafStart);
-}
 function parseLeafLocatorExpression(rawExpr) {
-  const expr = leafExpression(rawExpr.trim());
-  const m = /^([A-Za-z]+)\((.*)\)$/s.exec(expr);
-  if (!m) return null;
-  return { method: m[1], args: parseArgs(m[2].trim()) };
+  const leaf = parseLeafLocatorCall(rawExpr);
+  return leaf ? { method: leaf.method, args: locatorCallValues(leaf) } : null;
 }
 function deriveFailedLocator(testInfo) {
   const info = testInfo;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piwitests/reporter",
-  "version": "0.36.0",
+  "version": "0.38.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",
@@ -42,7 +42,7 @@
   "scripts": {
     "reporter:build": "tsup",
     "reporter:dev": "tsup --watch",
-    "reporter:typecheck": "tsc --noEmit",
+    "reporter:typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tests/tsconfig.json",
     "reporter:format": "oxfmt --config oxfmt.config.mts --write \"src/\"",
     "reporter:format:check": "oxfmt --config oxfmt.config.mts --check \"src/\"",
     "reporter:lint": "oxlint --config oxlint.config.mts .",

package/templates/skills/write-the-missing-test/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: write-the-missing-test
+description: Write a test that does not exist yet, chosen from Piwi's scenario gaps — the routes, pages, controls and error paths the suite never exercises, or passes over without noticing. Use when the user asks to "close a test gap", "cover what's missing", "write the test we're missing", "add coverage for this change", or wants the next most valuable test rather than more of the same.
+---
+
+# Write the missing test with Piwi scenario gaps
+
+A passing suite hides what it never tries. Piwi builds one graph of what the
+application exposes, what the suite reaches, and what a probe showed it would not
+notice, and proposes the tests that do not exist yet — each a **scenario gap**
+with its evidence and an exposure score. This skill takes the top gap in scope,
+drafts it from the graph, and opens it in the same change.
+
+## How you reach Piwi
+
+Prefer the **Piwi MCP server** if it is connected (`list_scenario_gaps`,
+`draft_scenario`, `get_change_coverage`). Otherwise use the dashboard's **Gaps**
+view, or the reporter CLI with `PIWI_DASHBOARD_URL` / `PIWI_API_KEY` /
+`PIWI_PROJECT_NAME` set.
+
+## Steps
+
+1. **Find the gaps.** On a change, call `get_change_coverage` for the current
+   branch first — the uncovered changed files are the gaps that matter now.
+   Otherwise call `list_scenario_gaps` for the project. Filter to what you are
+   working on with `class`, `feature`, `minScore` or `pr`. Read the classes:
+   - **blind-spot** — no trusted test reaches it (a route, a page, a control, a
+     new error path).
+   - **false-comfort** — tests reach it and a probe showed they would not notice
+     it breaking. The most valuable to fix: the catalog says it is covered.
+   - **fragile** — reached by a single, flaky, quarantined or long-skipped test.
+
+2. **Pick one.** Take the highest-scored gap in scope. Every gap is *observed
+   reach*, never instrumented coverage, and every evidence line pairs "no test"
+   with the count from recent history — trust the evidence, not a percentage.
+
+3. **Draft it.** Call `draft_scenario` with the gap id. You get a deterministic
+   skeleton: a title, `piwi:` annotations from the nearest test, the graph path
+   from a reached page to the gap as the step list, the catalog page-object
+   methods that match the page, and a `TODO` assertion naming what to check.
+   Nothing is committed — the skeleton is yours to finish.
+
+4. **Finish the assertion.** The draft reaches the subject; you write the check.
+   For a false-comfort gap, assert the effect the probe fault suppressed (the row
+   reflects the saved value, an error toast appears, the total is right) — a
+   visibility assertion is what let the gap through. Prefer the catalog methods
+   the draft named over hand-rolled locators.
+
+5. **Run just this test, then verify.** Run the new spec with a file filter
+   (`npx @piwitests/reporter run` or `playwright test <file>`). Confirm it passes
+   for the right reason: temporarily break the behavior it asserts and see it
+   fail. Open it in the same pull request as the change that motivated it.
+
+6. **Report.** State which gap you closed (class, subject, score) and how the new
+   test asserts the missing behavior. If the gap had no reachable path, say so —
+   the draft cannot invent an entry point, and the gap may need a fixture.
+
+## Guardrails
+
+- A gap is a suggestion with evidence, never a verdict. If the evidence does not
+  hold — the route is headless by design, the control is decorative — dismiss it
+  in the dashboard with a reason rather than writing a test that asserts nothing.
+- Do not weaken an assertion to make the draft pass. A test that passes without
+  asserting the behavior is the false-comfort gap you were sent to close.
+- The draft's assertion is a `TODO` on purpose: fill it from the source and the
+  intent, and validate the test the way you would any other — nothing is
+  committed except through the reviewed pull request.
+- One gap at a time. Close the highest-value gap, verify it, then re-check the
+  list — closing one often changes the ranking of the rest.