@qualestech/coverage-gap-detector

AI-powered Playwright test coverage gap detector by Quales Consulting Ltd

Crawls your live web app, analyses your existing Playwright test suite, identifies untested routes, and uses AI to classify each gap by the correct testing layer — generating ready-to-run Playwright and Vitest templates.

What it does

1. Crawls your app — launches a headless Playwright browser, authenticates, and spiders all navigable routes
2. Parses your test files — statically analyses your .spec.ts files to extract which routes and interactions are already covered
3. Diffs the two — finds routes the app has that no test visits
4. AI classifies each gap — via the Quales API (powered by Claude), determines whether each gap needs an E2E test, a unit/integration test, or can be deprioritised
5. Generates output — a coverage score, HTML report, JSON data file, and ready-to-run test templates

Output

coverage-reports/
├── coverage-gap-report.html     ← Visual report with filter, score badge, templates
├── coverage-gap-report.json     ← Machine-readable data (feeds other Quales agents)
└── templates/
    ├── wallet-send.spec.ts      ← Playwright E2E template
    ├── send-amount.test.ts      ← Vitest unit template
    └── ...

Installation

npm install --save-dev @qualestech/coverage-gap-detector

Requires Node.js ≥ 18 and Playwright browsers:

npx playwright install chromium

Setup

Generate a starter config file in your project root:

npx coverage-gap-detector --init

This copies gap.config.example.json to gap.config.json in your current directory. Open it and fill in your app's details:

{
  "baseUrl": "https://your-app.example.com",
  "testDir": "./tests",
  "outputDir": "./coverage-reports",
  "licenceKey": "YOUR_QUALES_LICENCE_KEY",
  "auth": {
    "loginUrl": "/login",
    "emailSelector": "#email",
    "passwordSelector": "#password",
    "submitSelector": "[type=submit]",
    "email": "[email protected]",
    "password": "yourpassword"
  },
  "seedRoutes": ["/dashboard", "/settings", "/billing"]
}

Licence keys are issued by Quales Consulting. Contact [email protected]

If your app has a 2FA / OTP step after login

Add these fields under auth — the defaults match a common pattern of six individually-indexed digit inputs:

"auth": {
  "otp": "123456",
  "otpScreenSelector": "[data-testid=\"screen-2fa\"]",
  "otpInputSelectorPattern": "[data-testid=\"otp-input-{i}\"]",
  "otpSubmitSelector": "[data-testid=\"btn-verify-2fa\"]"
}

Omit otp entirely if your app has no 2FA step.

If your app uses button-based navigation (not <a href> links)

Many single-page apps lose their authenticated session on a hard page reload. If your app's nav uses buttons rather than real links, map each route to the data-testid of the button that navigates there:

"navButtonMap": {
  "/dashboard": "nav-dashboard",
  "/settings": "nav-settings"
}

The crawler will click the mapped button instead of doing a full page navigation, preserving the in-memory auth state most SPAs rely on. Routes without a mapped button fall back to a normal page navigation.

Usage

# Run full analysis (crawl + extract + diff + AI classify)
npx coverage-gap-detector --config gap.config.json

# Skip re-crawl and reuse cached routes (faster for re-analysis)
npx coverage-gap-detector --config gap.config.json --no-crawl

Config reference

| Field | Required | Description | |---|---|---| | baseUrl | ✅ | Root URL of the app to crawl | | testDir | ✅ | Path to your Playwright test directory | | outputDir | ✅ | Where to write reports and templates | | licenceKey | ✅ | Quales licence key | | seedRoutes | recommended | Authenticated routes to check for coverage | | auth.loginUrl | — | Login page path (default: /login) | | auth.emailSelector | — | CSS selector for email input | | auth.passwordSelector | — | CSS selector for password input | | auth.submitSelector | — | CSS selector for submit button | | auth.email | — | Test user email | | auth.password | — | Test user password | | auth.otp | — | OTP code, if your app has a 2FA step | | auth.otpScreenSelector | — | Selector for the 2FA screen container | | auth.otpInputSelectorPattern | — | Selector pattern for each digit input, with {i} as the index placeholder | | auth.otpSubmitSelector | — | Selector for the 2FA verify button | | navButtonMap | — | Maps a route to the data-testid of its nav button, for SPAs without <a href> links | | crawlDepth | — | Reserved for future link-following crawl mode |

Test layer classification

| Layer | When assigned | Template format | |---|---|---| | E2E | Auth flows, multi-step journeys, cross-page state | Playwright .spec.ts | | Unit / Integration | Form validation, field rules, data transforms | Vitest .test.ts (Jest-compatible) | | Deprioritise | Static pages, minimal interactions, low-risk content | No template generated |

Part of the Quales QA Agent Suite

| Agent | Purpose | |---|---| | Environment Sentinel | Pre-flight health gate before test runs | | Jira-to-Test-Case | Generates test cases from Jira tickets | | Self-Healing Reporter | Detects and suggests fixes for broken locators | | Coverage Gap Detector | Maps untested routes and generates templates | | Failure Triage Agent | (coming soon) Classifies CI failures by root cause |

Licence

MIT © Quales Consulting Ltd