@sungen/driver-mock 3.2.31 → 3.2.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sungen/driver-mock",
-  "version": "3.2.31",
+  "version": "3.2.32",
   "description": "Sungen Mock capability (Network Mocking) — the @mock tag, mocks.yaml catalog, mock-install/call-count steps, and the specs/mock.ts runtime template. Plugs into @sun-asterisk/sungen via the capability SPI.",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -13,7 +13,7 @@
   "author": "eqe team (engineer & quality) — Sun Asterisk",
   "license": "MIT",
   "dependencies": {
-    "@sun-asterisk/sungen": "3.2.31"
+    "@sun-asterisk/sungen": "3.2.32"
   },
   "files": [
     "dist",

package/src/mock-catalog.ts

@@ -7,35 +7,65 @@
  *   reservations-check-500:
  *     method: POST                     # required — HTTP verb or "*"
  *     url: "**\/api/reservations/check" # required — page.route glob; "re:" prefix = regex
- *     status: 500                      # required
+ *     status: 500                      # required, unless `abort` is set
  *     headers: { content-type: application/json }   # optional
  *     body: { message: "Internal Server Error" }    # optional — inline, or a "{{var}}" test-data ref
  *     delay_ms: 5000                   # optional — hold the response N ms (the timeout simulator)
  *
+ * An entry describes ONE of three network outcomes, and the app under test takes a
+ * different branch for each — which is why none of them substitutes for another:
+ *
+ *   status:    the server ANSWERED. fetch() resolves, `res.ok` is false.
+ *   abort:     the request NEVER ARRIVED. fetch() rejects with `TypeError: Failed to
+ *              fetch`, so the app's `catch` runs instead of its `!res.ok` branch.
+ *   delay_ms:  the server answered LATE. This is the timeout tool (#676).
+ *
+ * `abort:` takes `true` — the faithful spelling of "just fail it", normalized here to
+ * Playwright's own no-argument default `failed` — or one of ABORT_CODES. Note the
+ * browser hides the reason from page JS: every code surfaces to the app as the same
+ * opaque `TypeError`, so the code buys readability and trace detail, not behaviour.
+ *
+ * A mock named "timeout" that aborts makes tests green for the wrong reason. That is
+ * still true, and it is now enforced by name (see TIMEOUT_SHAPED_NAME) rather than by
+ * banning the key outright — which left a genuine network failure with no path at all.
+ *
  * The loader ERRORS on an incomplete or unknown-keyed entry, naming the entry and
  * the valid keys — a malformed mock must never silently vanish from the suite
  * (the api-catalog loader's silent `continue` is a known trap, deliberately not
- * copied). There is no `abort` on purpose: route.abort() is a network error
- * (ERR_FAILED), not a timeout — a mock named "timeout" that aborts makes tests
- * green for the wrong reason. mocks.yaml is COMMITTED: credentials in bodies must
- * be `${QA_*}` refs (the secret scan covers mock/*.yaml).
+ * copied). mocks.yaml is COMMITTED: credentials in bodies must be `${QA_*}` refs
+ * (the secret scan covers mock/*.yaml).
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
 import { parse as parseYaml } from 'yaml';
 
+/** Playwright `route.abort()` errorCodes. `true` in YAML resolves to `failed`, its no-arg default. */
+export const ABORT_CODES = [
+  'failed', 'aborted', 'accessdenied', 'addressunreachable', 'connectionaborted',
+  'connectionclosed', 'connectionfailed', 'connectionrefused', 'connectionreset',
+  'internetdisconnected', 'namenotresolved', 'timedout', 'blockedbyclient', 'blockedbyresponse',
+] as const;
+
+export type AbortErrorCode = (typeof ABORT_CODES)[number];
+
+/** An entry whose NAME promises a timeout must not be satisfied by an abort — see the header. */
+const TIMEOUT_SHAPED_NAME = /timeout|slow|hang/i;
+
 export interface MockEntry {
   name: string;
   method: string;
   url: string;
-  status: number;
+  /** Absent exactly when `abort` is set — the two are mutually exclusive. */
+  status?: number;
+  /** Always a code once loaded: `abort: true` is normalized to 'failed' here. */
+  abort?: AbortErrorCode;
   headers?: Record<string, string>;
   body?: unknown;
   delay_ms?: number;
 }
 
-const VALID_KEYS = ['method', 'url', 'status', 'headers', 'body', 'delay_ms'];
+const VALID_KEYS = ['method', 'url', 'status', 'abort', 'headers', 'body', 'delay_ms'];
 const METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS', '*'];
 
 /** Absolute path of a unit's mock catalog (screens only in MVP — the locked unit shape). */
@@ -81,8 +111,7 @@ function validateEntry(name: string, value: unknown, file: string): MockEntry {
   const obj = value as Record<string, unknown>;
   const unknown = Object.keys(obj).filter((k) => !VALID_KEYS.includes(k));
   if (unknown.length) {
-    throw new Error(`${where}: unknown key(s) ${unknown.join(', ')} — valid keys: ${VALID_KEYS.join(', ')}` +
-      (unknown.includes('abort') ? ' (no `abort`: route.abort() is a network error, not a timeout — use a large delay_ms)' : ''));
+    throw new Error(`${where}: unknown key(s) ${unknown.join(', ')} — valid keys: ${VALID_KEYS.join(', ')}`);
   }
   const method = String(obj.method ?? '').toUpperCase();
   if (!obj.method || !METHODS.includes(method)) {
@@ -91,9 +120,35 @@ function validateEntry(name: string, value: unknown, file: string): MockEntry {
   if (!obj.url || typeof obj.url !== 'string') {
     throw new Error(`${where}: "url" is required (a page.route glob, or "re:<pattern>" for a regex)`);
   }
-  const status = Number(obj.status);
-  if (obj.status === undefined || !Number.isInteger(status) || status < 100 || status > 599) {
-    throw new Error(`${where}: "status" is required and must be an HTTP status code (100-599)`);
+  const abort = obj.abort === undefined ? undefined : resolveAbort(obj.abort, name, where);
+
+  // `status` and `abort` answer the same question — did the server respond? — with
+  // opposite answers. Picking one for the user would silently discard the other.
+  if (abort !== undefined && obj.status !== undefined) {
+    throw new Error(`${where}: "status" and "abort" are mutually exclusive — "status" is a response ` +
+      'the server sent, "abort" is a request that never arrived');
+  }
+
+  // An aborted request produces no response, so these describe a thing that never exists.
+  // Accepting them would compile a body the runtime silently drops — the "declared, plumbed
+  // and read by nothing" shape this loader refuses everywhere else. `delay_ms` is NOT in this
+  // list on purpose: a connection can legitimately drop late.
+  if (abort !== undefined) {
+    for (const key of ['headers', 'body'] as const) {
+      if (obj[key] !== undefined) {
+        throw new Error(`${where}: "${key}" cannot be used with "abort" — a request that ` +
+          'never arrives has no response to carry it');
+      }
+    }
+  }
+
+  let status: number | undefined;
+  if (abort === undefined) {
+    status = Number(obj.status);
+    if (obj.status === undefined || !Number.isInteger(status) || status < 100 || status > 599) {
+      throw new Error(`${where}: "status" is required and must be an HTTP status code (100-599)` +
+        ' — or use "abort" for a request that never reaches the server');
+    }
   }
   if (obj.delay_ms !== undefined && (!Number.isFinite(Number(obj.delay_ms)) || Number(obj.delay_ms) < 0)) {
     throw new Error(`${where}: "delay_ms" must be a non-negative number`);
@@ -105,13 +160,45 @@ function validateEntry(name: string, value: unknown, file: string): MockEntry {
     name,
     method,
     url: obj.url,
-    status,
+    ...(status === undefined ? {} : { status }),
+    ...(abort === undefined ? {} : { abort }),
     headers: obj.headers as Record<string, string> | undefined,
     body: obj.body,
     delay_ms: obj.delay_ms === undefined ? undefined : Number(obj.delay_ms),
   };
 }
 
+/**
+ * Normalize and validate one `abort:` value. Returns the errorCode the runtime will pass
+ * to `route.abort()`; throws naming the entry otherwise.
+ */
+function resolveAbort(value: unknown, name: string, where: string): AbortErrorCode {
+  // FIRST, before any value handling: the original rationale behind banning `abort` outright,
+  // kept as a name check. An entry that PROMISES a timeout and delivers a network error is
+  // green for the wrong reason — and `abort: true` under such a name is the likeliest way to
+  // write that defect, so this must run ahead of the `true` shorthand, not after it.
+  if (TIMEOUT_SHAPED_NAME.test(name)) {
+    throw new Error(`${where}: a timeout-shaped name must not be satisfied by an abort — use ` +
+      '"delay_ms" to hold the response; "abort" is for a request that never reaches the server');
+  }
+  if (value === true) return 'failed';
+  // `false` reads as "do not abort" — which is what omitting the key already says. Accepting
+  // it would leave an entry that looks disabled but still fulfils.
+  if (value === false) {
+    throw new Error(`${where}: "abort: false" is not a way to disable a mock — remove the "abort" key instead`);
+  }
+  // The sibling key is `status: 500`, so a number here is far more likely a misplaced HTTP
+  // status than a typo'd errorCode. Say that, rather than listing an enum it does not belong to.
+  if (typeof value === 'number') {
+    throw new Error(`${where}: "abort" takes true or an errorCode, not a number — for an HTTP ` +
+      `status use "status: ${value}"`);
+  }
+  if (typeof value !== 'string' || !(ABORT_CODES as readonly string[]).includes(value)) {
+    throw new Error(`${where}: "abort" must be true or one of ${ABORT_CODES.join(', ')}`);
+  }
+  return value as AbortErrorCode;
+}
+
 function rel(p: string, cwd: string): string {
   return path.relative(cwd, p) || p;
 }

package/src/patterns/mock-patterns.ts

@@ -45,8 +45,11 @@ function entryExpr(entry: MockEntry): string {
     `name: ${JSON.stringify(entry.name)}`,
     `method: ${JSON.stringify(entry.method)}`,
     `url: ${JSON.stringify(entry.url)}`,
-    `status: ${entry.status}`,
   ];
+  // Exactly one of these is set — the loader refuses an entry carrying both (#676). The
+  // loader also normalized `abort: true` to a code, so this is always a string.
+  if (entry.abort !== undefined) parts.push(`abort: ${JSON.stringify(entry.abort)}`);
+  else parts.push(`status: ${entry.status}`);
   if (entry.headers) parts.push(`headers: ${JSON.stringify(entry.headers)}`);
   if (entry.delay_ms !== undefined) parts.push(`delay_ms: ${entry.delay_ms}`);
   if (entry.body !== undefined) {
@@ -74,7 +77,7 @@ export const mockPatterns: StepPattern[] = [
       const entry = resolveMock(name, context.screenName || context.featureName || '', process.cwd());
       return {
         code: `await mock.install(page, ${entryExpr(entry)});`,
-        comment: `Mock ${name}: ${entry.method} ${entry.url} → ${entry.status}${entry.delay_ms ? ` after ${entry.delay_ms}ms` : ''}`,
+        comment: `Mock ${name}: ${entry.method} ${entry.url} → ${entry.abort ? `aborts (${entry.abort})` : entry.status}${entry.delay_ms ? ` after ${entry.delay_ms}ms` : ''}`,
       };
     },
     priority: 70,