@michalfidor/playswag 1.0.0 → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michał Fidor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -52,7 +52,7 @@ export default defineConfig({
 
       // Optional
       outputDir: './playswag-coverage',
-      outputFormats: ['console', 'json'],   // default
+      outputFormats: ['console', 'json'],   // also: 'html', 'badge'
 
       threshold: {
         endpoints: 80,         // warn / fail if < 80% of endpoints are hit
@@ -74,6 +74,8 @@ npx playwright test
 ```
 
 Coverage is printed to the terminal and written to `./playswag-coverage/playswag-coverage.json`.
+To also get an interactive HTML report, add `'html'` to `outputFormats` — the reporter will print a
+clickable `file://` link at the end of the run (suppressed when `CI=true`).
 
 ---
 
@@ -94,7 +96,7 @@ interface PlayswagConfig {
   outputDir?: string;
 
   /** Which output formats to produce. @default ['console', 'json'] */
-  outputFormats?: Array<'console' | 'json'>;
+  outputFormats?: Array<'console' | 'json' | 'html' | 'badge'>;
 
   /**
    * Base URL of the API under test.
@@ -111,7 +113,7 @@ interface PlayswagConfig {
   consoleOutput?: {
     enabled?: boolean;            // @default true
     showUncoveredOnly?: boolean;  // @default false
-    showDetails?: boolean;        // @default true — per-operation table
+    showOperations?: boolean;     // @default true — per-operation table
     showParams?: boolean;         // @default false
     showBodyProperties?: boolean; // @default false
   };
@@ -122,11 +124,34 @@ interface PlayswagConfig {
     pretty?: boolean;     // @default true
   };
 
+  /**
+   * Options for the standalone HTML coverage report.
+   * Enable by adding 'html' to outputFormats.
+   */
+  htmlOutput?: {
+    enabled?: boolean;  // @default true
+    fileName?: string;  // @default 'playswag-coverage.html'
+    title?: string;     // @default 'API Coverage Report'
+  };
+
+  /**
+   * Options for the SVG coverage badge.
+   * Enable by adding 'badge' to outputFormats.
+   */
+  badge?: {
+    enabled?: boolean;                                                        // @default true
+    fileName?: string;                                                        // @default 'playswag-badge.svg'
+    /** Which coverage dimension drives the badge percentage. */
+    dimension?: 'endpoints' | 'statusCodes' | 'parameters' | 'bodyProperties'; // @default 'endpoints'
+    label?: string;                                                           // @default 'API Coverage'
+  };
+
   threshold?: {
-    endpoints?: number;       // 0–100
-    statusCodes?: number;
-    parameters?: number;
-    bodyProperties?: number;
+    // Plain number: informational warning only (respects failOnThreshold globally)
+    endpoints?: number | { min: number; fail?: boolean };
+    statusCodes?: number | { min: number; fail?: boolean };
+    parameters?: number | { min: number; fail?: boolean };
+    bodyProperties?: number | { min: number; fail?: boolean };
   };
 
   /**
@@ -152,6 +177,48 @@ projects: [
 test.use({ playswagEnabled: false });
 ```
 
+## Tracking custom request contexts
+
+The built-in `request` fixture is wrapped automatically. If your tests use **additional
+`APIRequestContext` instances** — for example contexts created with `request.newContext()`
+or returned by a custom fixture — use the `trackRequest` fixture to wrap them:
+
+```ts
+import { test, expect } from '@michalfidor/playswag';
+
+// request.newContext()
+test('uses a second context', async ({ request, trackRequest }) => {
+  const adminCtx = trackRequest(await request.newContext({ extraHTTPHeaders: { 'x-role': 'admin' } }));
+  const res = await adminCtx.get('/api/admin/stats');
+  expect(res.ok()).toBeTruthy();
+});
+```
+
+`trackRequest` is most useful inside **custom fixtures** that create their own contexts:
+
+```ts
+import { test as base } from '@michalfidor/playswag';
+
+const test = base.extend<{ adminRequest: import('@playwright/test').APIRequestContext }>({
+  adminRequest: async ({ trackRequest }, use) => {
+    const raw = await ContextFactory.getContextByUserAccessToken('admin');
+    await use(trackRequest(raw));
+  },
+});
+
+export { test };
+
+// Then in tests:
+test('admin can list users', async ({ adminRequest }) => {
+  const res = await adminRequest.get('/api/admin/users');
+  expect(res.ok()).toBeTruthy();
+});
+```
+
+All calls made through any `trackRequest`-wrapped context are recorded alongside
+calls from the main `request` fixture. They all end up in the same per-test
+attachment and contribute to the coverage report.
+
 ---
 
 ## Multiple spec files
@@ -168,6 +235,61 @@ Duplicate `method + path` entries across files are de-duplicated (last one wins,
 
 ---
 
+---
+
+## HTML report
+
+Add `'html'` to `outputFormats` to generate a self-contained, zero-dependency HTML file alongside
+the JSON report:
+
+```ts
+outputFormats: ['console', 'json', 'html'],
+htmlOutput: {
+  fileName: 'playswag-coverage.html', // written to outputDir
+  title: 'My API Coverage',
+},
+```
+
+After the run, the reporter prints a clickable link:
+
+```
+[playswag] HTML report → file:///path/to/playswag-coverage/playswag-coverage.html
+```
+
+(On CI the `file://` link is omitted; only the relative path is logged.)
+
+The report includes:
+- Summary cards with progress bars for all four dimensions
+- Operations table with **All / Covered / Uncovered** filter buttons and per-tag filtering
+- Click any row to expand status codes, parameters, body properties, and the tests that hit it
+- Unmatched hits section (calls that matched no spec operation)
+- Dark / light theme toggle (persisted to `localStorage`)
+
+---
+
+## SVG badge
+
+Add `'badge'` to `outputFormats` to write a shields.io-style SVG badge:
+
+```ts
+outputFormats: ['console', 'json', 'badge'],
+badge: {
+  dimension: 'endpoints', // the percentage shown on the badge
+  label: 'API coverage',
+  fileName: 'playswag-badge.svg',
+},
+```
+
+Commit the badge and embed it in your README:
+
+```markdown
+![API coverage](./playswag-coverage/playswag-badge.svg)
+```
+
+Colour thresholds: **green** ≥ 80 % · **orange** ≥ 50 % · **red** < 50 %.
+
+---
+
 ## Console output example
 
 ```
@@ -193,6 +315,9 @@ Duplicate `method + path` entries across files are de-duplicated (last one wins,
 {
   "specFiles": ["./openapi.yaml"],
   "timestamp": "2026-03-04T12:00:00.000Z",
+  "playwrightVersion": "1.50.0",
+  "playswagVersion": "1.0.0",
+  "totalTestCount": 12,
   "summary": {
     "endpoints":     { "total": 6, "covered": 5, "percentage": 83.3 },
     "statusCodes":   { "total": 11, "covered": 7, "percentage": 63.6 },
@@ -239,7 +364,7 @@ testInfo.attach(                   onTestEnd():
                                    onEnd():
                                      parse OpenAPI spec(s)
                                      match hits → path templates
-                                     calculate 3-tier coverage
+                                     calculate 4-dimension coverage
                                      print console report
                                      write JSON file
 ```

package/assets/.gitkeep

@@ -0,0 +1 @@
+Drop your logo file (logo.png) into this directory. It is referenced from README.md.