Fix mock overlap in contract validation (#4)

* feat: set test.status to running in onStart callback

Enables twd-js to find the currently executing test by scanning
handlers for status === 'running' during mock collection.

* feat: add buildTestPath utility

Walks the handler parent chain to build a full test path string
like 'Cart > Checkout > should submit order' from a testId.

* feat: fix mock dedup key and add occurrence tracking

Change mock collection key from alias to method:url:status:testId:occurrence.
Track occurrence count per alias:testId combination.
Enrich collected mocks with full test path names from handlers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: add formatMockLabel utility for report display

Formats mock labels with alias, ordinal occurrence suffix (2nd, 3rd),
and test name context for contract validation reports.

* feat: show test name and occurrence in console contract report

Use formatMockLabel to display test context and ordinal occurrence
in error, pass, and warning lines.

* feat: show test name and occurrence in markdown contract report

Use formatMockLabelMd to display test context and ordinal occurrence
in the failure details section of the markdown report.

* docs: update README with test context in contract reports

Update contract validation example output to show test name and
occurrence count in mock labels. Add note about automatic handling
of mock overlaps (same alias, different endpoints).

* chore: update dependencies

* fix: reset test.status and pass testName/occurrence through validation

Two bugs prevented test names from showing in contract reports:
1. onStart set test.status="running" but never reset it, so
   __twdCollectMock always found the first test as "running"
2. validateMocks didn't forward testName/occurrence to result objects

Also bump test-example-app twd-js to ^1.6.5 (sends testId).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: kevinccbsg

README.md

@@ -60,6 +60,8 @@ Create a `twd.config.json` file in your project root:
 
 **Important**: Puppeteer is **not** used as a testing framework here. It simply provides a headless browser to load your application — the same way a user would open Chrome. Once the page loads, all test execution happens inside the real browser context through the [TWD runner](https://brikev.github.io/twd/). Your tests interact with real DOM, real components, and real browser APIs — Puppeteer just opens the door and gets out of the way.
 
+**Contract Validation**: Mock overlaps are automatically handled — if multiple tests or calls use the same alias but with different HTTP methods/URLs/statuses, all are validated separately (no silent drops).
+
 1. Launches a headless browser via Puppeteer (the only thing Puppeteer does)
 2. Navigates to your dev server URL
 3. Waits for the app and TWD sidebar to be ready
@@ -188,12 +190,12 @@ Validate your test mocks against OpenAPI specs to catch drift between your mocks
 ```
 Source: ./contracts/users-3.0.json   ERROR
 
-  ✓ GET /users (200) — mock "getUsers"
-  ✗ GET /users/{userId} (200) — mock "getUserBadAddress"
+  ✓ GET /users (200) — mock "getUsers" — in "UserList > should display all users"
+  ✗ GET /users/{userId} (200) — mock "getUserBadAddress" — in "UserDetails > should fetch user details"
     → response.address.city: missing required property
     → response.address.country: missing required property
 
-  ⚠ GET /users/{userId} (404) — mock "getUserNotFound"
+  ⚠ GET /users/{userId} (404) — mock "getUserNotFound" 2nd time — in "UserDetails > should show not found"
     Status 404 not documented for GET /users/{userId}
 ```
 

package-lock.json

@@ -25,14 +25,14 @@
   "dependencies": {
     "openapi-mock-validator": "^0.1.4",
     "puppeteer": "^24.40.0",
-    "twd-js": "^1.6.4"
+    "twd-js": "^1.6.5"
   },
   "engines": {
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.2",
+    "@vitest/coverage-v8": "^4.1.4",
     "conventional-changelog": "^7.2.0",
-    "vitest": "^4.1.2"
+    "vitest": "^4.1.4"
   }
 }

package.json

@@ -0,0 +1,11 @@
+export function buildTestPath(testId, handlers) {
+  const handlerMap = new Map(handlers.map(h => [h.id, h]));
+  const parts = [];
+  let current = handlerMap.get(testId);
+  if (!current) return null;
+  while (current) {
+    parts.unshift(current.name);
+    current = current.parent ? handlerMap.get(current.parent) : null;
+  }
+  return parts.join(' > ');
+}

src/buildTestPath.js

@@ -1,3 +1,10 @@
+import { formatMockLabel } from './formatMockLabel.js';
+
+function formatMockLabelMd(result) {
+  // Reuse the plain-text label but replace quoted alias with backtick-wrapped alias
+  return formatMockLabel(result).replace(`"${result.alias}"`, `\`${result.alias}\``);
+}
+
 export function generateContractMarkdown(output) {
   const { results, skipped } = output;
   const lines = [];
@@ -85,7 +92,7 @@ export function generateContractMarkdown(output) {
       lines.push('');
 
       for (const r of failures) {
-        lines.push(`- \`${r.method} ${r.matchedPath}\` (${r.status}) — mock \`${r.alias}\``);
+        lines.push(`- \`${r.method} ${r.matchedPath}\` (${r.status}) — ${formatMockLabelMd(r)}`);
         for (const err of r.validation.errors) {
           lines.push(`  - \`${err.path}\`: ${err.message}`);
         }

src/contractMarkdown.js

@@ -1,3 +1,5 @@
+import { formatMockLabel } from './formatMockLabel.js';
+
 const red = (s) => `\x1b[31m${s}\x1b[0m`;
 const boldRed = (s) => `\x1b[1;31m${s}\x1b[0m`;
 const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
@@ -45,7 +47,7 @@ export function printContractReport(output) {
 
       if (!result.validation.valid) {
         errorCount += result.validation.errors.length;
-        console.log(failColor(`  ✗ ${result.method} ${result.matchedPath} (${result.status}) — mock "${result.alias}"`));
+        console.log(failColor(`  ✗ ${result.method} ${result.matchedPath} (${result.status}) — ${formatMockLabel(result)}`));
         for (const err of result.validation.errors) {
           console.log(detailColor(`    → ${err.path}: ${err.message}`));
         }
@@ -54,12 +56,12 @@ export function printContractReport(output) {
           hasContractErrors = true;
         }
       } else if (result.validation.warnings.length === 0) {
-        console.log(green(`  ✓ ${result.method} ${result.matchedPath} (${result.status}) — mock "${result.alias}"`));
+        console.log(green(`  ✓ ${result.method} ${result.matchedPath} (${result.status}) — ${formatMockLabel(result)}`));
       }
 
       for (const warning of result.validation.warnings) {
         warningCount++;
-        console.log(yellow(`  ⚠ ${result.method} ${result.matchedPath} (${result.status}) — mock "${result.alias}"`));
+        console.log(yellow(`  ⚠ ${result.method} ${result.matchedPath} (${result.status}) — ${formatMockLabel(result)}`));
         console.log(yellow(`    ${warning.message}`));
         console.log('');
       }

src/contractReport.js

@@ -83,6 +83,8 @@ export function validateMocks(collectedMocks, contracts) {
         specSource: contract.source,
         matchedPath: pathMatch.path,
         mode: contract.mode,
+        testName: mock.testName,
+        occurrence: mock.occurrence,
         validation,
       });
 

src/contracts.js

@@ -0,0 +1,16 @@
+function ordinal(n) {
+  if (n === 2) return '2nd';
+  if (n === 3) return '3rd';
+  return `${n}th`;
+}
+
+export function formatMockLabel(result) {
+  let label = `mock "${result.alias}"`;
+  if (result.occurrence && result.occurrence > 1) {
+    label += ` ${ordinal(result.occurrence)} time`;
+  }
+  if (result.testName) {
+    label += ` — in "${result.testName}"`;
+  }
+  return label;
+}

src/formatMockLabel.js

@@ -6,6 +6,7 @@ import { loadConfig } from './config.js';
 import { loadContracts, validateMocks } from './contracts.js';
 import { printContractReport } from './contractReport.js';
 import { generateContractMarkdown } from './contractMarkdown.js';
+import { buildTestPath } from './buildTestPath.js';
 
 export async function runTests() {
   let browser;
@@ -32,9 +33,15 @@ export async function runTests() {
 
     // Register mock collector for contract validation
     const collectedMocks = new Map();
+    const occurrenceCounters = new Map();
     if (config.contracts && config.contracts.length > 0) {
       await page.exposeFunction('__twdCollectMock', (mock) => {
-        collectedMocks.set(mock.alias, mock);
+        const occKey = `${mock.alias}:${mock.testId}`;
+        const count = (occurrenceCounters.get(occKey) || 0) + 1;
+        occurrenceCounters.set(occKey, count);
+
+        const dedupKey = `${mock.method}:${mock.url}:${mock.status}:${mock.testId}:${count}`;
+        collectedMocks.set(dedupKey, { ...mock, occurrence: count });
       });
     }
 
@@ -51,16 +58,21 @@ export async function runTests() {
       const TestRunner = window.__testRunner;
       const testStatus = [];
       const runner = new TestRunner({
-        onStart: () => {},
+        onStart: (test) => {
+          test.status = "running";
+        },
         onPass: (test, retryAttempt) => {
+          test.status = "done";
           const entry = { id: test.id, status: "pass" };
           if (retryAttempt !== undefined) entry.retryAttempt = retryAttempt;
           testStatus.push(entry);
         },
         onFail: (test, err) => {
+          test.status = "done";
           testStatus.push({ id: test.id, status: "fail", error: `${err.message} (at ${window.location.href})` });
         },
         onSkip: (test) => {
+          test.status = "done";
           testStatus.push({ id: test.id, status: "skip" });
         },
       }, { retryCount });
@@ -89,6 +101,13 @@ export async function runTests() {
     let hasFailures = testStatus.some(test => test.status === 'fail');
     console.timeEnd('Total Test Time');
 
+    // Enrich collected mocks with full test path names
+    for (const [, mock] of collectedMocks) {
+      if (mock.testId) {
+        mock.testName = buildTestPath(mock.testId, handlers);
+      }
+    }
+
     // Contract validation
     if (config.contracts && config.contracts.length > 0) {
       if (collectedMocks.size === 0) {