Playswag

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 five dimensions:

| Dimension | What it measures | |-----------|------------------| | Endpoints | Which path + method combinations were called | | Status codes | Which response codes defined in the spec were exercised | | Parameters | Which query/path/header params were supplied | | Body properties | Which request body fields were provided | | Response properties | Which response body fields were observed |

Works with multiple workers out of the box — per-worker data is collected via test attachments and aggregated in the reporter process.

Installation

npm install --save-dev @michalfidor/playswag

@playwright/test >=1.20.0 is a required peer dependency.

Quick start

1. Replace your import

-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

import { defineConfig } from '@michalfidor/playswag';

export default defineConfig({
  reporter: [
    ['list'],
    ['@michalfidor/playswag/reporter', {
      specs: ['./openapi.yaml'],
      outputDir: './playswag-coverage',
      outputFormats: ['console', 'json'],
      threshold: { endpoints: 80, statusCodes: 60 },
    }],
  ],
  use: {
    baseURL: 'https://api.example.com',
  },
});

3. Run your tests

npx playwright test

Coverage is printed to the terminal and written to ./playswag-coverage/playswag-coverage.json.

Documentation

| Guide | Description | |-------|-------------| | Configuration | Full config reference — all reporter options, thresholds, console/JSON/HTML/badge/JUnit/markdown settings | | Output formats | Console, HTML, JSON, SVG badge, JUnit XML, and Markdown output details | | Multi-project setup | Per-project specs, per-file opt-out, custom request contexts, multiple spec files | | CI integration | GitHub Actions auto-detection, merging reports from parallel jobs (project-based, sharded, mixed), best practices | | Coverage history | Sparkline trends, delta indicators, persisting history across CI runs | | API reference | All public exports — fixtures, functions, config types, result types |

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 5-dimension coverage
                                     print console report
                                     write output files

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