@riddledc/riddle-proof 0.7.38 → 0.7.40

package/README.md

@@ -182,7 +182,35 @@ before navigation, records each hit, and adds an implicit
 `network_mocks_succeeded` check when mocks are present. A mock supports
 `url`/`glob`/`pattern`, optional `method`, `status`, `content_type`, `headers`,
 string `body`, JSON `json` / `body_json`, and `required: false` for
-best-effort mocks.
+best-effort mocks. Use `responses` for retry or recovery profiles where the
+same endpoint should return a sequence, such as first `503` and then `200`.
+Each response accepts the same payload fields plus an optional label:
+
+```json
+{
+  "label": "builder-build",
+  "url": "**/api/build",
+  "method": "POST",
+  "responses": [
+    {
+      "label": "first-build-fails",
+      "status": 503,
+      "json": { "error": "Synthetic build outage" }
+    },
+    {
+      "label": "second-build-succeeds",
+      "status": 200,
+      "json": { "previewUrl": "https://cdn.example/game/index.html" }
+    }
+  ]
+}
+```
+
+When `responses` is present, `network_mocks_succeeded` requires each configured
+response to be hit at least once by default and records `hit_index`,
+`response_index`, and `response_label` for each request. Set
+`required_hit_count` / `min_hits` or `required: false` when a different
+contract is intentional.
 
 `target.setup_actions` is optional. Use it when the meaningful proof surface
 appears only after a picker, tab, login stub, storage seed, form fill,
@@ -202,6 +230,25 @@ clears `local`, `session`, or `both` browser storage scopes, defaults to
 profile carries its own hosted Riddle worker budget; an explicit CLI `--timeout`
 still overrides the profile value for one-off runs.
 
+Use `allowed_console_patterns` / `allowed_console_texts` on
+`no_fatal_console_errors` when a negative-path profile intentionally triggers a
+known browser console error, such as a mocked `503` that the app recovers from:
+
+```json
+{
+  "type": "no_fatal_console_errors",
+  "allowed_console_patterns": [
+    "Failed to load resource: the server responded with a status of 503",
+    "Build failed: Error: Synthetic build outage"
+  ]
+}
+```
+
+Allowed console events and page errors are still counted in check evidence, but
+only unallowed `error` / `assert` console events and page errors fail the check.
+Use `allowed_page_error_patterns`, `allowed_console_texts`, or
+`allowed_page_error_texts` for narrower matching when needed.
+
 Use `selector_text_order` when a table, list, or card group must show visible
 items in a specific order after setup actions such as sorting or filtering:
 

package/dist/{chunk-ZB7AFRN3.js → chunk-RAVOICNN.js}

@@ -246,24 +246,57 @@ function normalizeNetworkMock(input, index) {
   if (!isRecord(input)) throw new Error(`target.network_mocks[${index}] must be an object.`);
   const url = stringValue(input.url) || stringValue(input.glob) || stringValue(input.pattern);
   if (!url) throw new Error(`target.network_mocks[${index}] requires url.`);
-  const status = numberValue(input.status) ?? 200;
-  if (!Number.isInteger(status) || status < 100 || status > 599) {
-    throw new Error(`target.network_mocks[${index}].status must be an HTTP status code.`);
+  const payload = normalizeNetworkMockResponsePayload(input, `target.network_mocks[${index}]`);
+  const responsesInput = input.responses ?? input.sequence;
+  const responses = normalizeNetworkMockResponses(responsesInput, index, payload);
+  const requiredHitCount = numberValue(
+    input.required_hit_count ?? input.requiredHitCount ?? input.required_hits ?? input.requiredHits ?? input.min_hits ?? input.minHits
+  );
+  if (requiredHitCount !== void 0 && (!Number.isInteger(requiredHitCount) || requiredHitCount < 1)) {
+    throw new Error(`target.network_mocks[${index}].required_hit_count must be a positive integer.`);
   }
-  const body = stringValue(input.body) ?? stringValue(input.body_text) ?? stringValue(input.bodyText);
-  const hasJsonBody = Object.prototype.hasOwnProperty.call(input, "body_json") || Object.prototype.hasOwnProperty.call(input, "bodyJson") || Object.prototype.hasOwnProperty.call(input, "json");
   return {
+    ...payload,
     label: normalizeName(input.label || input.name, `network-mock-${index + 1}`),
     url,
     method: stringValue(input.method)?.toUpperCase(),
+    responses,
+    required_hit_count: requiredHitCount,
+    required: input.required === false ? false : true
+  };
+}
+function normalizeNetworkMockResponsePayload(input, label, defaults = {}) {
+  const status = numberValue(input.status) ?? defaults.status ?? 200;
+  if (!Number.isInteger(status) || status < 100 || status > 599) {
+    throw new Error(`${label}.status must be an HTTP status code.`);
+  }
+  const body = stringValue(input.body) ?? stringValue(input.body_text) ?? stringValue(input.bodyText) ?? defaults.body;
+  const hasJsonBody = Object.prototype.hasOwnProperty.call(input, "body_json") || Object.prototype.hasOwnProperty.call(input, "bodyJson") || Object.prototype.hasOwnProperty.call(input, "json");
+  return {
+    label: stringValue(input.label) || stringValue(input.name) || defaults.label,
     status,
-    content_type: stringValue(input.content_type) || stringValue(input.contentType),
-    headers: stringRecord(input.headers),
+    content_type: stringValue(input.content_type) || stringValue(input.contentType) || defaults.content_type,
+    headers: stringRecord(input.headers) || defaults.headers,
     body,
-    body_json: hasJsonBody ? toJsonValue(input.body_json ?? input.bodyJson ?? input.json) : void 0,
-    required: input.required === false ? false : true
+    body_json: hasJsonBody ? toJsonValue(input.body_json ?? input.bodyJson ?? input.json) : defaults.body_json
   };
 }
+function normalizeNetworkMockResponses(value, mockIndex, defaults) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) throw new Error(`target.network_mocks[${mockIndex}].responses must be an array.`);
+  if (!value.length) throw new Error(`target.network_mocks[${mockIndex}].responses must not be empty.`);
+  const responseDefaults = { ...defaults, label: void 0 };
+  return value.map((response, responseIndex) => {
+    if (!isRecord(response)) {
+      throw new Error(`target.network_mocks[${mockIndex}].responses[${responseIndex}] must be an object.`);
+    }
+    return normalizeNetworkMockResponsePayload(
+      response,
+      `target.network_mocks[${mockIndex}].responses[${responseIndex}]`,
+      responseDefaults
+    );
+  });
+}
 function normalizeNetworkMocks(value) {
   if (value === void 0) return void 0;
   if (!Array.isArray(value)) throw new Error("target.network_mocks must be an array.");
@@ -305,6 +338,13 @@ function normalizeExpectedTexts(value, index) {
   if (!texts.length) throw new Error(`checks[${index}] selector_text_order expected_texts must contain non-empty strings.`);
   return texts;
 }
+function normalizeStringList(value, label) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array.`);
+  const values = value.map((item) => String(item).replace(/\s+/g, " ").trim()).filter(Boolean);
+  if (!values.length) throw new Error(`${label} must contain non-empty strings.`);
+  return values;
+}
 function normalizeCheck(input, index) {
   if (!isRecord(input)) throw new Error(`checks[${index}] must be an object.`);
   const type = stringValue(input.type);
@@ -353,6 +393,10 @@ function normalizeCheck(input, index) {
     text: stringValue(input.text),
     pattern: stringValue(input.pattern),
     flags: stringValue(input.flags),
+    allowed_console_texts: normalizeStringList(input.allowed_console_texts ?? input.allowedConsoleTexts ?? input.allow_console_texts ?? input.allowConsoleTexts, `checks[${index}] allowed_console_texts`),
+    allowed_console_patterns: normalizeStringList(input.allowed_console_patterns ?? input.allowedConsolePatterns ?? input.allow_console_patterns ?? input.allowConsolePatterns, `checks[${index}] allowed_console_patterns`),
+    allowed_page_error_texts: normalizeStringList(input.allowed_page_error_texts ?? input.allowedPageErrorTexts ?? input.allow_page_error_texts ?? input.allowPageErrorTexts, `checks[${index}] allowed_page_error_texts`),
+    allowed_page_error_patterns: normalizeStringList(input.allowed_page_error_patterns ?? input.allowedPageErrorPatterns ?? input.allow_page_error_patterns ?? input.allowPageErrorPatterns, `checks[${index}] allowed_page_error_patterns`),
     min_count: numberValue(input.min_count),
     max_overflow_px: numberValue(input.max_overflow_px),
     timeout_ms: numberValue(input.timeout_ms) ?? numberValue(input.timeoutMs),
@@ -516,6 +560,18 @@ function matchText(sample, check) {
   }
   return sample.includes(check.text || "");
 }
+function matchesAllowedMessage(message, texts, patterns) {
+  const sample = String(message || "");
+  if (texts?.some((text) => sample.includes(text))) return true;
+  for (const pattern of patterns || []) {
+    try {
+      if (new RegExp(pattern).test(sample)) return true;
+    } catch {
+      continue;
+    }
+  }
+  return false;
+}
 function normalizeRoutePath(path) {
   const value = path || "/";
   if (value === "/") return "/";
@@ -802,14 +858,28 @@ function assessCheckFromEvidence(check, evidence) {
     };
   }
   if (check.type === "no_fatal_console_errors") {
-    const fatalCount = (evidence.console?.fatal_count || 0) + (evidence.page_errors?.length || 0);
+    const fatalConsoleEvents = (evidence.console?.events || []).filter((event) => event.type === "error" || event.type === "assert");
+    const allowedConsoleEvents = fatalConsoleEvents.filter((event) => matchesAllowedMessage(event.text, check.allowed_console_texts, check.allowed_console_patterns));
+    const unallowedConsoleEvents = fatalConsoleEvents.filter((event) => !matchesAllowedMessage(event.text, check.allowed_console_texts, check.allowed_console_patterns));
+    const pageErrors = evidence.page_errors || [];
+    const allowedPageErrors = pageErrors.filter((error) => matchesAllowedMessage(error.message, check.allowed_page_error_texts, check.allowed_page_error_patterns));
+    const unallowedPageErrors = pageErrors.filter((error) => !matchesAllowedMessage(error.message, check.allowed_page_error_texts, check.allowed_page_error_patterns));
+    const fatalCount = unallowedConsoleEvents.length + unallowedPageErrors.length;
     return {
       type: check.type,
       label: checkLabel(check),
       status: fatalCount ? "failed" : "passed",
       evidence: {
-        console_fatal_count: evidence.console?.fatal_count || 0,
-        page_error_count: evidence.page_errors?.length || 0
+        console_fatal_count: unallowedConsoleEvents.length,
+        page_error_count: unallowedPageErrors.length,
+        total_console_fatal_count: fatalConsoleEvents.length,
+        total_page_error_count: pageErrors.length,
+        allowed_console_fatal_count: allowedConsoleEvents.length,
+        allowed_page_error_count: allowedPageErrors.length,
+        allowed_console_texts: check.allowed_console_texts || [],
+        allowed_console_patterns: check.allowed_console_patterns || [],
+        allowed_page_error_texts: check.allowed_page_error_texts || [],
+        allowed_page_error_patterns: check.allowed_page_error_patterns || []
       },
       message: fatalCount ? `${fatalCount} fatal browser error(s) were captured.` : void 0
     };
@@ -872,12 +942,15 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
   const requiredMocks = mocks.filter((mock) => mock.required !== false);
   for (const mock of requiredMocks) {
     const hits = events.filter((event) => event.label === mock.label && event.ok !== false).length;
-    if (hits < 1) {
+    const requiredHitCount = requiredNetworkMockHitCount(mock);
+    if (hits < requiredHitCount) {
       failed.push({
         label: mock.label,
         url: mock.url,
         method: mock.method || null,
-        reason: "required_mock_not_hit"
+        reason: hits < 1 ? "required_mock_not_hit" : "required_mock_hit_count_not_met",
+        required_hit_count: requiredHitCount,
+        hit_count: hits
       });
     }
   }
@@ -903,11 +976,21 @@ function assessNetworkMocksFromEvidence(profile, evidence) {
         mock.label,
         events.filter((event) => event.label === mock.label && event.ok !== false).length
       ])),
+      required_hits_by_label: Object.fromEntries(requiredMocks.map((mock) => [
+        mock.label,
+        requiredNetworkMockHitCount(mock)
+      ])),
       failed
     },
     message: failed.length ? `Network mocks failed or were not hit for ${failed.length} mock(s).` : void 0
   };
 }
+function requiredNetworkMockHitCount(mock) {
+  if (mock.required === false) return 0;
+  if (mock.required_hit_count !== void 0) return mock.required_hit_count;
+  if (Array.isArray(mock.responses) && mock.responses.length) return mock.responses.length;
+  return 1;
+}
 function profileStatusFromEvidence(profile, evidence, checks) {
   if (!evidence) return "proof_insufficient";
   const viewports = evidence.viewports || [];
@@ -1065,6 +1148,16 @@ function textMatches(sample, check) {
   }
   return String(sample || "").includes(check.text || "");
 }
+function matchesAllowedMessage(message, texts, patterns) {
+  const sample = String(message || "");
+  if ((texts || []).some((text) => sample.includes(text))) return true;
+  for (const pattern of patterns || []) {
+    try {
+      if (new RegExp(pattern).test(sample)) return true;
+    } catch {}
+  }
+  return false;
+}
 function textSequenceForCheck(viewport, check) {
   const key = check.selector || "";
   const sequence = viewport.text_sequences && viewport.text_sequences[key];
@@ -1192,6 +1285,12 @@ function horizontalBoundsOverflowPx(value) {
   }
   return roundPixels(max);
 }
+function requiredNetworkMockHitCount(mock) {
+  if (!mock || mock.required === false) return 0;
+  if (Number.isInteger(mock.required_hit_count) && mock.required_hit_count > 0) return mock.required_hit_count;
+  if (Array.isArray(mock.responses) && mock.responses.length) return mock.responses.length;
+  return 1;
+}
 function assessProfile(profile, evidence) {
   const checks = [];
   const viewports = evidence.viewports || [];
@@ -1201,12 +1300,15 @@ function assessProfile(profile, evidence) {
     const failed = [];
     for (const mock of requiredMocks) {
       const hits = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
-      if (hits < 1) {
+      const requiredHitCount = requiredNetworkMockHitCount(mock);
+      if (hits < requiredHitCount) {
         failed.push({
           label: mock.label,
           url: mock.url,
           method: mock.method || null,
-          reason: "required_mock_not_hit",
+          reason: hits < 1 ? "required_mock_not_hit" : "required_mock_hit_count_not_met",
+          required_hit_count: requiredHitCount,
+          hit_count: hits,
         });
       }
     }
@@ -1221,8 +1323,10 @@ function assessProfile(profile, evidence) {
       }
     }
     const hitsByLabel = {};
+    const requiredHitsByLabel = {};
     for (const mock of profile.target.network_mocks) {
       hitsByLabel[mock.label] = events.filter((event) => event && event.label === mock.label && event.ok !== false).length;
+      if (mock && mock.required !== false) requiredHitsByLabel[mock.label] = requiredNetworkMockHitCount(mock);
     }
     checks.push({
       type: "network_mocks_succeeded",
@@ -1233,6 +1337,7 @@ function assessProfile(profile, evidence) {
         required_count: requiredMocks.length,
         hit_count: events.filter((event) => event && event.ok !== false).length,
         hits_by_label: hitsByLabel,
+        required_hits_by_label: requiredHitsByLabel,
         failed,
       },
       message: failed.length ? "Network mocks failed or were not hit for " + failed.length + " mock(s)." : undefined,
@@ -1499,12 +1604,29 @@ function assessProfile(profile, evidence) {
       continue;
     }
     if (check.type === "no_fatal_console_errors") {
-      const fatalCount = ((evidence.console && evidence.console.fatal_count) || 0) + ((evidence.page_errors || []).length);
+      const fatalConsoleEvents = ((evidence.console && evidence.console.events) || []).filter((event) => event && (event.type === "error" || event.type === "assert"));
+      const allowedConsoleEvents = fatalConsoleEvents.filter((event) => matchesAllowedMessage(event.text, check.allowed_console_texts, check.allowed_console_patterns));
+      const unallowedConsoleEvents = fatalConsoleEvents.filter((event) => !matchesAllowedMessage(event.text, check.allowed_console_texts, check.allowed_console_patterns));
+      const pageErrors = evidence.page_errors || [];
+      const allowedPageErrors = pageErrors.filter((error) => matchesAllowedMessage(error && error.message, check.allowed_page_error_texts, check.allowed_page_error_patterns));
+      const unallowedPageErrors = pageErrors.filter((error) => !matchesAllowedMessage(error && error.message, check.allowed_page_error_texts, check.allowed_page_error_patterns));
+      const fatalCount = unallowedConsoleEvents.length + unallowedPageErrors.length;
       checks.push({
         type: check.type,
         label: check.label || check.type,
         status: fatalCount ? "failed" : "passed",
-        evidence: { console_fatal_count: (evidence.console && evidence.console.fatal_count) || 0, page_error_count: (evidence.page_errors || []).length },
+        evidence: {
+          console_fatal_count: unallowedConsoleEvents.length,
+          page_error_count: unallowedPageErrors.length,
+          total_console_fatal_count: fatalConsoleEvents.length,
+          total_page_error_count: pageErrors.length,
+          allowed_console_fatal_count: allowedConsoleEvents.length,
+          allowed_page_error_count: allowedPageErrors.length,
+          allowed_console_texts: check.allowed_console_texts || [],
+          allowed_console_patterns: check.allowed_console_patterns || [],
+          allowed_page_error_texts: check.allowed_page_error_texts || [],
+          allowed_page_error_patterns: check.allowed_page_error_patterns || [],
+        },
         message: fatalCount ? String(fatalCount) + " fatal browser error(s) were captured." : undefined,
       });
       continue;
@@ -1614,6 +1736,7 @@ async function setupLocatorVisible(locator, index) {
 }
 async function registerNetworkMocks(mocks) {
   for (const mock of mocks || []) {
+    let hitCount = 0;
     await page.route(mock.url, async (route) => {
       const request = route.request();
       const method = request.method ? request.method() : "";
@@ -1622,22 +1745,31 @@ async function registerNetworkMocks(mocks) {
         return;
       }
       try {
-        const headers = { ...(mock.headers || {}) };
-        let body = mock.body || "";
-        let contentType = mock.content_type || headers["content-type"] || headers["Content-Type"] || "text/plain";
-        if (mock.body_json !== undefined) {
-          body = JSON.stringify(mock.body_json);
-          contentType = mock.content_type || headers["content-type"] || headers["Content-Type"] || "application/json";
+        const responses = Array.isArray(mock.responses) ? mock.responses : [];
+        const hitIndex = hitCount;
+        hitCount += 1;
+        const responseIndex = responses.length ? Math.min(hitIndex, responses.length - 1) : null;
+        const response = responseIndex === null ? mock : responses[responseIndex];
+        const headers = { ...(response.headers || mock.headers || {}) };
+        let body = response.body || "";
+        let contentType = response.content_type || headers["content-type"] || headers["Content-Type"] || "text/plain";
+        if (response.body_json !== undefined) {
+          body = JSON.stringify(response.body_json);
+          contentType = response.content_type || headers["content-type"] || headers["Content-Type"] || "application/json";
         }
         networkMockEvents.push({
           ok: true,
           label: mock.label,
+          response_label: response.label || null,
+          hit_index: hitIndex,
+          response_index: responseIndex,
+          sequence_reused: responseIndex !== null && hitIndex >= responses.length,
           url: request.url(),
           method,
-          status: mock.status || 200,
+          status: response.status || mock.status || 200,
         });
         await route.fulfill({
-          status: mock.status || 200,
+          status: response.status || mock.status || 200,
           headers,
           contentType,
           body,