@michalfidor/playswag 1.0.0

package/README.md

@@ -0,0 +1,253 @@
+# Playswag 
+
+![playswag logo](assets/logo.png)
+
+> Playwright API coverage tracking against Swagger / OpenAPI specifications.
+
+`playswag` transparently wraps Playwright's built-in `request` fixture to record every API call made during your tests, then compares the results against your OpenAPI spec(s) to report coverage across four dimensions:
+
+| Dimension | What it measures |
+|-----------|------------------|
+| **Endpoints** | Which path + method combinations were called at all |
+| **Status codes** | Which response codes defined in the spec were actually exercised |
+| **Parameters** | Which query/path/header params were supplied |
+| **Body properties** | Which request body fields were provided |
+
+Works with **multiple workers** out of the box — per-worker data is collected via test attachments and aggregated in the reporter process after all tests complete.
+
+---
+
+## Installation
+
+```bash
+npm install --save-dev @michalfidor/playswag
+```
+
+`@playwright/test >=1.20.0` is a required peer dependency.
+
+---
+
+## Quick start
+
+### 1. Replace your import
+
+```diff
+-import { test, expect } from '@playwright/test';
++import { test, expect } from '@michalfidor/playswag';
+```
+
+That's it. The `request` fixture is transparently wrapped — existing tests need no other changes.
+
+### 2. Add the reporter to `playwright.config.ts`
+
+```ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  reporter: [
+    ['list'],
+    ['@michalfidor/playswag/reporter', {
+      // Required: one or more spec sources (file paths or URLs)
+      specs: ['./openapi.yaml'],
+
+      // Optional
+      outputDir: './playswag-coverage',
+      outputFormats: ['console', 'json'],   // default
+
+      threshold: {
+        endpoints: 80,         // warn / fail if < 80% of endpoints are hit
+        statusCodes: 60,
+      },
+      failOnThreshold: false,  // set true to fail the run when thresholds aren't met
+    }],
+  ],
+  use: {
+    baseURL: 'https://api.example.com',  // auto-detected by the reporter
+  },
+});
+```
+
+### 3. Run your tests
+
+```bash
+npx playwright test
+```
+
+Coverage is printed to the terminal and written to `./playswag-coverage/playswag-coverage.json`.
+
+---
+
+## Configuration reference
+
+All options are passed as the second element of the reporter tuple in `playwright.config.ts`.
+
+```ts
+interface PlayswagConfig {
+  /**
+   * OpenAPI / Swagger spec source(s).
+   * Accepts local file paths (.yaml / .json), remote URLs, or an array of both.
+   * Supports Swagger 2.0 and OpenAPI 3.0 / 3.1.
+   */
+  specs: string | string[];
+
+  /** Output directory for generated files. @default './playswag-coverage' */
+  outputDir?: string;
+
+  /** Which output formats to produce. @default ['console', 'json'] */
+  outputFormats?: Array<'console' | 'json'>;
+
+  /**
+   * Base URL of the API under test.
+   * Auto-detected from playwright.config.ts `use.baseURL` if not provided.
+   */
+  baseURL?: string;
+
+  /** Only track API calls whose paths match these glob patterns. */
+  includePatterns?: string[];
+
+  /** Ignore API calls whose paths match these glob patterns. */
+  excludePatterns?: string[];
+
+  consoleOutput?: {
+    enabled?: boolean;            // @default true
+    showUncoveredOnly?: boolean;  // @default false
+    showDetails?: boolean;        // @default true — per-operation table
+    showParams?: boolean;         // @default false
+    showBodyProperties?: boolean; // @default false
+  };
+
+  jsonOutput?: {
+    enabled?: boolean;    // @default true
+    fileName?: string;    // @default 'playswag-coverage.json'
+    pretty?: boolean;     // @default true
+  };
+
+  threshold?: {
+    endpoints?: number;       // 0–100
+    statusCodes?: number;
+    parameters?: number;
+    bodyProperties?: number;
+  };
+
+  /**
+   * When true, the test run is marked as failed if any threshold is not met.
+   * @default false — thresholds are informational only by default
+   */
+  failOnThreshold?: boolean;
+}
+```
+
+### Per-project / per-file opt-out
+
+```ts
+// In playwright.config.ts — disable coverage for a specific project
+projects: [
+  {
+    name: 'no-coverage',
+    use: { playswagEnabled: false },
+  },
+]
+
+// Or inside a test file
+test.use({ playswagEnabled: false });
+```
+
+---
+
+## Multiple spec files
+
+```ts
+specs: [
+  './specs/users.yaml',
+  './specs/orders.yaml',
+  'https://api.example.com/openapi.json',
+]
+```
+
+Duplicate `method + path` entries across files are de-duplicated (last one wins, with a console warning).
+
+---
+
+## Console output example
+
+```
+────────────────────────────────────────────────────────────────────────────────
+  Playswag · API Coverage Report
+  2026-03-04T12:00:00.000Z  ·  specs: openapi.yaml
+────────────────────────────────────────────────────────────────────────────────
+┌──────────────┬─────────┬───────┬──────────────────────┐
+│ Dimension    │ Covered │ %     │ Progress             │
+├──────────────┼─────────┼───────┼──────────────────────┤
+│ Endpoints    │ 5/6     │ 83.3% │ ████████████████░░░░ │
+│ Status Codes │ 7/11    │ 63.6% │ █████████████░░░░░░░ │
+│ Parameters   │ 4/5     │ 80.0% │ ████████████████░░░░ │
+│ Body Props   │ 2/3     │ 66.7% │ █████████████░░░░░░░ │
+└──────────────┴─────────┴───────┴──────────────────────┘
+```
+
+---
+
+## JSON output schema
+
+```json
+{
+  "specFiles": ["./openapi.yaml"],
+  "timestamp": "2026-03-04T12:00:00.000Z",
+  "summary": {
+    "endpoints":     { "total": 6, "covered": 5, "percentage": 83.3 },
+    "statusCodes":   { "total": 11, "covered": 7, "percentage": 63.6 },
+    "parameters":    { "total": 5, "covered": 4, "percentage": 80.0 },
+    "bodyProperties":{ "total": 3, "covered": 2, "percentage": 66.7 }
+  },
+  "operations": [
+    {
+      "path": "/api/users",
+      "method": "GET",
+      "covered": true,
+      "statusCodes": {
+        "200": { "covered": true,  "testRefs": ["users.spec.ts > list users"] },
+        "400": { "covered": false, "testRefs": [] }
+      },
+      "parameters": [
+        { "name": "limit", "in": "query", "required": false, "covered": true }
+      ],
+      "bodyProperties": [],
+      "testRefs": ["users.spec.ts > list users"]
+    }
+  ],
+  "uncoveredOperations": [...],
+  "unmatchedHits": [...]
+}
+```
+
+---
+
+## How it works
+
+```
+Worker process                     Main process (Reporter)
+──────────────────                 ──────────────────────
+request.get('/api/users')
+  ↓ Proxy intercepts
+  records { method, url,
+    status, body, params }
+  ↓
+testInfo.attach(                   onTestEnd():
+  'playswag:hits', JSON             reads attachment
+)                                   appends to aggregated list
+                                   ↓
+                                   onEnd():
+                                     parse OpenAPI spec(s)
+                                     match hits → path templates
+                                     calculate 3-tier coverage
+                                     print console report
+                                     write JSON file
+```
+
+Data flows from each worker to the reporter via Playwright's built-in test attachment IPC — no temp files, no shared state, no locking required. Works correctly with any number of parallel workers.
+
+---
+
+## License
+
+MIT

package/dist/cjs/index.cjs

@@ -0,0 +1,85 @@
+'use strict';
+
+var test$1 = require('@playwright/test');
+
+// src/fixture.ts
+
+// src/constants.ts
+var ATTACHMENT_NAME = "playswag:hits";
+
+// src/fixture.ts
+var INTERCEPTED_METHODS = ["get", "post", "put", "patch", "delete", "head", "fetch"];
+function buildTrackedRequest(original, hits, testInfo) {
+  return new Proxy(original, {
+    get(target, prop, receiver) {
+      if (!INTERCEPTED_METHODS.includes(prop)) {
+        return Reflect.get(target, prop, receiver);
+      }
+      const method = prop;
+      return async (urlOrRequest, options) => {
+        let httpMethod;
+        if (method === "fetch") {
+          httpMethod = (typeof options?.["method"] === "string" ? options["method"] : "GET").toUpperCase();
+        } else {
+          httpMethod = method.toUpperCase();
+        }
+        const response = await target[method].call(target, urlOrRequest, options);
+        let queryParams;
+        const rawParams = options?.["params"];
+        if (rawParams && typeof rawParams === "object" && !Array.isArray(rawParams)) {
+          queryParams = Object.fromEntries(
+            Object.entries(rawParams).map(([k, v]) => [k, String(v)])
+          );
+        }
+        let headers;
+        const rawHeaders = options?.["headers"];
+        if (rawHeaders && typeof rawHeaders === "object" && !Array.isArray(rawHeaders)) {
+          headers = Object.fromEntries(
+            Object.entries(rawHeaders).map(([k, v]) => [k, String(v)])
+          );
+        }
+        const requestBody = options?.["data"] ?? options?.["form"] ?? options?.["multipart"] ?? void 0;
+        hits.push({
+          method: httpMethod,
+          url: response.url(),
+          statusCode: response.status(),
+          requestBody,
+          queryParams,
+          headers,
+          testFile: testInfo.titlePath[0] ?? "",
+          testTitle: testInfo.title
+        });
+        return response;
+      };
+    }
+  });
+}
+var test = test$1.test.extend({
+  playswagEnabled: [true, { option: true }],
+  trackRequest: async ({ playswagEnabled }, use, testInfo) => {
+    if (!playswagEnabled) {
+      await use((ctx) => ctx);
+      return;
+    }
+    const hits = [];
+    await use((ctx) => buildTrackedRequest(ctx, hits, testInfo));
+    if (hits.length > 0) {
+      await testInfo.attach(ATTACHMENT_NAME, {
+        body: Buffer.from(JSON.stringify(hits), "utf8"),
+        contentType: "application/json"
+      });
+    }
+  },
+  request: async ({ request, trackRequest }, use) => {
+    await use(trackRequest(request));
+  }
+});
+
+Object.defineProperty(exports, "expect", {
+  enumerable: true,
+  get: function () { return test$1.expect; }
+});
+exports.ATTACHMENT_NAME = ATTACHMENT_NAME;
+exports.test = test;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/constants.ts","../../src/fixture.ts"],"names":["base"],"mappings":";;;;;;;AACO,IAAM,eAAA,GAAkB;;;ACY/B,IAAM,mBAAA,GAAsB,CAAC,KAAA,EAAO,MAAA,EAAQ,OAAO,OAAA,EAAS,QAAA,EAAU,QAAQ,OAAO,CAAA;AAOrF,SAAS,mBAAA,CACP,QAAA,EACA,IAAA,EACA,QAAA,EACG;AACH,EAAA,OAAO,IAAI,MAAM,QAAA,EAAU;AAAA,IACzB,GAAA,CAAI,MAAA,EAAQ,IAAA,EAAM,QAAA,EAAU;AAC1B,MAAA,IAAI,CAAC,mBAAA,CAAoB,QAAA,CAAS,IAAkB,CAAA,EAAG;AACrD,QAAA,OAAO,OAAA,CAAQ,GAAA,CAAI,MAAA,EAAQ,IAAA,EAAM,QAAQ,CAAA;AAAA,MAC3C;AAEA,MAAA,MAAM,MAAA,GAAS,IAAA;AAEf,MAAA,OAAO,OAAO,cAA+B,OAAA,KAA4D;AACvG,QAAA,IAAI,UAAA;AACJ,QAAA,IAAI,WAAW,OAAA,EAAS;AACtB,UAAA,UAAA,GAAA,CACE,OAAO,UAAU,QAAQ,CAAA,KAAM,WAAW,OAAA,CAAQ,QAAQ,CAAA,GAAI,KAAA,EAC9D,WAAA,EAAY;AAAA,QAChB,CAAA,MAAO;AACL,UAAA,UAAA,GAAa,OAAO,WAAA,EAAY;AAAA,QAClC;AAGA,QAAA,MAAM,QAAA,GAAwB,MAAO,MAAA,CAAO,MAAM,EAAU,IAAA,CAAK,MAAA,EAAQ,cAAc,OAAO,CAAA;AAE9F,QAAA,IAAI,WAAA;AACJ,QAAA,MAAM,SAAA,GAAY,UAAU,QAAQ,CAAA;AACpC,QAAA,IAAI,SAAA,IAAa,OAAO,SAAA,KAAc,QAAA,IAAY,CAAC,KAAA,CAAM,OAAA,CAAQ,SAAS,CAAA,EAAG;AAC3E,UAAA,WAAA,GAAc,MAAA,CAAO,WAAA;AAAA,YACnB,MAAA,CAAO,OAAA,CAAQ,SAAoC,CAAA,CAAE,IAAI,CAAC,CAAC,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA,EAAG,MAAA,CAAO,CAAC,CAAC,CAAC;AAAA,WACrF;AAAA,QACF;AAEA,QAAA,IAAI,OAAA;AACJ,QAAA,MAAM,UAAA,GAAa,UAAU,SAAS,CAAA;AACtC,QAAA,IAAI,UAAA,IAAc,OAAO,UAAA,KAAe,QAAA,IAAY,CAAC,KAAA,CAAM,OAAA,CAAQ,UAAU,CAAA,EAAG;AAC9E,UAAA,OAAA,GAAU,MAAA,CAAO,WAAA;AAAA,YACf,MAAA,CAAO,OAAA,CAAQ,UAAoC,CAAA,CAAE,IAAI,CAAC,CAAC,CAAA,EAAG,CAAC,MAAM,CAAC,CAAA,EAAG,MAAA,CAAO,CAAC,CAAC,CAAC;AAAA,WACrF;AAAA,QACF;AAEA,QAAA,MAAM,WAAA,GAAc,UAAU,MAAM,CAAA,IAAK,UAAU,MAAM,CAAA,IAAK,OAAA,GAAU,WAAW,CAAA,IAAK,MAAA;AAExF,QAAA,IAAA,CAAK,IAAA,CAAK;AAAA,UACR,MAAA,EAAQ,UAAA;AAAA,UACR,GAAA,EAAK,SAAS,GAAA,EAAI;AAAA,UAClB,UAAA,EAAY,SAAS,MAAA,EAAO;AAAA,UAC5B,WAAA;AAAA,UACA,WAAA;AAAA,UACA,OAAA;AAAA,UACA,QAAA,EAAU,QAAA,CAAS,SAAA,CAAU,CAAC,CAAA,IAAK,EAAA;AAAA,UACnC,WAAW,QAAA,CAAS;AAAA,SACrB,CAAA;AAED,QAAA,OAAO,QAAA;AAAA,MACT,CAAA;AAAA,IACF;AAAA,GACD,CAAA;AACH;AA2CO,IAAM,IAAA,GAAOA,YAAK,MAAA,CAA2C;AAAA,EAClE,iBAAiB,CAAC,IAAA,EAAM,EAAE,MAAA,EAAQ,MAAM,CAAA;AAAA,EAExC,cAAc,OACZ,EAAE,eAAA,EAAgB,EAClB,KACA,QAAA,KACG;AACH,IAAA,IAAI,CAAC,eAAA,EAAiB;AACpB,MAAA,MAAM,GAAA,CAAI,CAA8B,GAAA,KAAW,GAAG,CAAA;AACtD,MAAA;AAAA,IACF;AAEA,IAAA,MAAM,OAAsB,EAAC;AAC7B,IAAA,MAAM,IAAI,CAA8B,GAAA,KAAW,oBAAoB,GAAA,EAAK,IAAA,EAAM,QAAQ,CAAC,CAAA;AAE3F,IAAA,IAAI,IAAA,CAAK,SAAS,CAAA,EAAG;AACnB,MAAA,MAAM,QAAA,CAAS,OAAO,eAAA,EAAiB;AAAA,QACrC,MAAM,MAAA,CAAO,IAAA,CAAK,KAAK,SAAA,CAAU,IAAI,GAAG,MAAM,CAAA;AAAA,QAC9C,WAAA,EAAa;AAAA,OACd,CAAA;AAAA,IACH;AAAA,EACF,CAAA;AAAA,EAEA,SAAS,OACP,EAAE,OAAA,EAAS,YAAA,IACX,GAAA,KACG;AACH,IAAA,MAAM,GAAA,CAAI,YAAA,CAAa,OAAO,CAAC,CAAA;AAAA,EACjC;AACF,CAAC","file":"index.cjs","sourcesContent":["/** Attachment name used to pass hit data from workers to the reporter process. */\nexport const ATTACHMENT_NAME = 'playswag:hits';\n","import {\n  test as base,\n  expect,\n  type APIRequestContext,\n  type APIResponse,\n  type TestInfo,\n} from '@playwright/test';\nimport type { EndpointHit } from './types.js';\nimport { ATTACHMENT_NAME } from './constants.js';\n\nexport { expect };\nexport { ATTACHMENT_NAME } from './constants.js';\n\nconst INTERCEPTED_METHODS = ['get', 'post', 'put', 'patch', 'delete', 'head', 'fetch'] as const;\ntype HttpMethod = (typeof INTERCEPTED_METHODS)[number];\n\n/**\n * Build a Proxy around an APIRequestContext that records every HTTP call.\n * Generic so the original type (e.g. a CustomAPIRequest subtype) is preserved.\n */\nfunction buildTrackedRequest<T extends APIRequestContext>(\n  original: T,\n  hits: EndpointHit[],\n  testInfo: TestInfo\n): T {\n  return new Proxy(original, {\n    get(target, prop, receiver) {\n      if (!INTERCEPTED_METHODS.includes(prop as HttpMethod)) {\n        return Reflect.get(target, prop, receiver);\n      }\n\n      const method = prop as HttpMethod;\n\n      return async (urlOrRequest: string | object, options?: Record<string, unknown>): Promise<APIResponse> => {\n        let httpMethod: string;\n        if (method === 'fetch') {\n          httpMethod = (\n            typeof options?.['method'] === 'string' ? options['method'] : 'GET'\n          ).toUpperCase();\n        } else {\n          httpMethod = method.toUpperCase();\n        }\n\n        // eslint-disable-next-line @typescript-eslint/no-explicit-any\n        const response: APIResponse = await (target[method] as any).call(target, urlOrRequest, options);\n\n        let queryParams: Record<string, string> | undefined;\n        const rawParams = options?.['params'];\n        if (rawParams && typeof rawParams === 'object' && !Array.isArray(rawParams)) {\n          queryParams = Object.fromEntries(\n            Object.entries(rawParams as Record<string, unknown>).map(([k, v]) => [k, String(v)])\n          );\n        }\n\n        let headers: Record<string, string> | undefined;\n        const rawHeaders = options?.['headers'];\n        if (rawHeaders && typeof rawHeaders === 'object' && !Array.isArray(rawHeaders)) {\n          headers = Object.fromEntries(\n            Object.entries(rawHeaders as Record<string, string>).map(([k, v]) => [k, String(v)])\n          );\n        }\n\n        const requestBody = options?.['data'] ?? options?.['form'] ?? options?.['multipart'] ?? undefined;\n\n        hits.push({\n          method: httpMethod,\n          url: response.url(),\n          statusCode: response.status(),\n          requestBody,\n          queryParams,\n          headers,\n          testFile: testInfo.titlePath[0] ?? '',\n          testTitle: testInfo.title,\n        });\n\n        return response;\n      };\n    },\n  }) as T;\n}\n\n\ntype PlayswagOptions = {\n  /** Set to false to disable coverage tracking for this project/file. @default true */\n  playswagEnabled: boolean;\n};\n\n/**\n * Fixtures added by playswag, available in any test or fixture that extends `test`.\n *\n * `trackRequest` wraps any `APIRequestContext` (including custom subtypes) so\n * that every HTTP call made through it is recorded for coverage.  All hits from\n * all wrapped contexts within a single test are combined into one attachment.\n *\n * @example\n * // In your context fixture:\n * myServiceContext: async ({ trackRequest }, use) => {\n *   const raw = await ContextFactory.getContextByUserAccessToken('user');\n *   await use(trackRequest(raw));\n * },\n */\nexport type PlayswagFixtures = {\n  trackRequest: <T extends APIRequestContext>(ctx: T) => T;\n};\n\n/**\n * `test` extended from `@playwright/test` with transparent API coverage tracking.\n *\n * Just replace:\n *   import { test, expect } from '@playwright/test';\n * with:\n *   import { test, expect } from '@michalfidor/playswag';\n *\n * The `request` fixture is automatically wrapped — no other changes needed.\n *\n * For tests that use custom `APIRequestContext` objects (e.g. created via\n * `request.newContext()`), use the `trackRequest` fixture to wrap them:\n *   myContext: async ({ trackRequest }, use) => { use(trackRequest(raw)); }\n *\n * Disable tracking per-project or per-file with:\n *   test.use({ playswagEnabled: false });\n */\nexport const test = base.extend<PlayswagOptions & PlayswagFixtures>({\n  playswagEnabled: [true, { option: true }],\n\n  trackRequest: async (\n    { playswagEnabled }: { playswagEnabled: boolean },\n    use: (fn: <T extends APIRequestContext>(ctx: T) => T) => Promise<void>,\n    testInfo: TestInfo\n  ) => {\n    if (!playswagEnabled) {\n      await use(<T extends APIRequestContext>(ctx: T) => ctx);\n      return;\n    }\n\n    const hits: EndpointHit[] = [];\n    await use(<T extends APIRequestContext>(ctx: T) => buildTrackedRequest(ctx, hits, testInfo));\n\n    if (hits.length > 0) {\n      await testInfo.attach(ATTACHMENT_NAME, {\n        body: Buffer.from(JSON.stringify(hits), 'utf8'),\n        contentType: 'application/json',\n      });\n    }\n  },\n\n  request: async (\n    { request, trackRequest }: { request: APIRequestContext; trackRequest: <T extends APIRequestContext>(ctx: T) => T },\n    use: (r: APIRequestContext) => Promise<void>\n  ) => {\n    await use(trackRequest(request));\n  },\n});\n"]}