playwright-code-coverage 0.0.0-alpha

package/README.md

@@ -0,0 +1,121 @@
+# Playwright code coverage
+
+Generate istanbul code coverage reports for Playwright tests.
+
+## Prerequisites
+
+- Playwright >= 1.40.0
+- Ensure sourcemaps are enabled for dev server/bundle
+- Run tests with a chromium-based browser
+
+## Usage
+
+### Install:
+
+```bash
+npm i -D playwright-code-coverage
+```
+
+### Configure:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+import { defineCoverageReporterConfig } from 'playwright-code-coverage';
+
+export default defineConfig({
+  reporter: [
+    [
+      'playwright-code-coverage',
+      defineCoverageReporterConfig({
+        workspaceRoot: __dirname,
+      }),
+    ],
+  ],
+});
+```
+
+### Instrument your tests:
+
+To enable code coverage for tests you need to use the `testWithCoverage` fixture instead of the regular `test` fixture.
+
+```typescript
+import { expect } from '@playwright/test';
+import { testWithCoverage as test } from 'playwright-code-coverage';
+
+test('has title', async ({ page }) => {
+  await page.goto('/');
+
+  expect(await page.locator('h1').innerText()).toContain('Welcome');
+});
+```
+
+You can also [extend](https://playwright.dev/docs/test-fixtures#creating-a-fixture) this fixture or [merge]() it.
+
+### Generate coverage report:
+
+Code coverage is generated after each test command is finished and written to the configured output directory (default: `coverage/playwright-code-coverage`).
+
+Default output format is `lcov` but can be configured to use any format supported by `istanbul-reports` like:
+
+- `clover`
+- `html`
+- `json`
+- `text`
+
+## Supported frameworks
+
+In theory this library works with any framework that uses sourcemaps.
+However, only the following frameworks have currently been tested:
+
+- `angular 21`
+
+## Configuration
+
+### Configuration options
+
+| Setting           | Description                                                         | Default                                             |
+| ----------------- | ------------------------------------------------------------------- | --------------------------------------------------- |
+| `workspaceRoot`   | Root folder of project, should be an absolute path                  | None, this is a required field                      |
+| `outputDir`       | Folder to write the coverage report to                              | `coverage/playwright-code-coverage`                 |
+| `baseURL`         | URL on which the application lives                                  | `http://localhost:4200`                             |
+| `bundleLocation`  | Location of the bundle folder on disk                               | None, required when testing with static file server |
+| `includePatterns` | glob patterns for including files in coverage report                | `['**/*.ts', '**/*.tsx']`                           |
+| `excludePatterns` | glob patterns for excluding files in coverage report                | `[]`                                                |
+| `reporters`       | reporters from `istanbul-reports` executed at the end of test suite | `['lcov']`                                          |
+| `debug`           | Prints config at start when set                                     | false                                               |
+
+### Configuration examples
+
+#### Standard angular app - dev server
+
+```typescript
+import { defineCoverageReporterConfig } from 'playwright-code-coverage';
+
+defineCoverageReporterConfig({
+  workspaceRoot: __dirname,
+});
+```
+
+#### Standard angular app - static file server
+
+```typescript
+import { defineCoverageReporterConfig } from 'playwright-code-coverage';
+
+defineCoverageReporterConfig({
+  workspaceRoot: __dirname,
+  bundleLocation: 'dist/angular-app/browser',
+});
+```
+
+#### Angular in nx monorepo
+
+```typescript
+import { workspaceRoot } from '@nx/devkit';
+import { defineCoverageReporterConfig } from 'playwright-code-coverage';
+
+defineCoverageReporterConfig({
+  workspaceRoot: workspaceRoot,
+  includePatterns: ['**/angular/app/**/*.ts'],
+});
+```

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./src/index";
+export { default } from "./src/index";

package/index.esm.js

@@ -0,0 +1,191 @@
+import { existsSync, rmSync, mkdirSync } from 'fs';
+import libCoverage from 'istanbul-lib-coverage';
+import libReport from 'istanbul-lib-report';
+import reports from 'istanbul-reports';
+import { minimatch } from 'minimatch';
+import { join } from 'path';
+import v8toIstanbul from 'v8-to-istanbul';
+import { test } from '@playwright/test';
+
+const COVERAGE_REPORTER_DEFAULTS = {
+    outputDir: 'coverage/playwright-code-coverage',
+    reporters: ['lcov'],
+    baseUrl: 'http://localhost:4200',
+    includePatterns: ['**/*.ts', '**/*.tsx'],
+};
+const defineCoverageReporterConfig = (config) => {
+    return {
+        workspaceRoot: config.workspaceRoot ?? '',
+        outputDir: config.outputDir ?? COVERAGE_REPORTER_DEFAULTS.outputDir,
+        baseURL: config.baseURL ?? COVERAGE_REPORTER_DEFAULTS.baseUrl,
+        reporters: config.reporters ?? COVERAGE_REPORTER_DEFAULTS.reporters,
+        bundleLocation: config.bundleLocation ?? '',
+        includePatterns: config.includePatterns ?? COVERAGE_REPORTER_DEFAULTS.includePatterns,
+        excludePatterns: config.excludePatterns ?? [],
+        debug: config.debug ?? false,
+    };
+};
+
+const coverageFileKey = 'coverage';
+const marshallCoverage = (coverage) => {
+    return {
+        body: Buffer.from(JSON.stringify(coverage)),
+        contentType: 'application/json',
+    };
+};
+const unmarshallCoverage = (attachments) => {
+    const coverageAttachment = attachments.find(a => a.name === coverageFileKey);
+    if (coverageAttachment?.body) {
+        return JSON.parse(coverageAttachment.body.toString());
+    }
+    return [];
+};
+
+const postProcessIstanbulCoverMap = (coverageMapData, config) => {
+    const newCoverMapData = {};
+    Object.entries(coverageMapData).forEach(entries => {
+        const [key, entry] = entries;
+        let newKey;
+        if (config.bundleLocation) {
+            newKey = key.replace(`/${config.bundleLocation}`, '');
+        }
+        else {
+            const doubleSlashRemoved = config.baseURL.replace('//', '/');
+            newKey = key.replace(`/${doubleSlashRemoved}`, '');
+        }
+        newCoverMapData[newKey] = entry;
+    });
+    Object.values(coverageMapData).forEach(coverage => {
+        if (config.bundleLocation) {
+            coverage.path = coverage.path.replace(`/${config.bundleLocation}`, '');
+            return;
+        }
+        const doubleSlashRemoved = config.baseURL.replace('//', '/');
+        coverage.path = coverage.path.replace(`/${doubleSlashRemoved}`, '');
+    });
+    return newCoverMapData;
+};
+const filterCoverageMap = (coverageMap, config) => {
+    const filteredCoverage = libCoverage.createCoverageMap();
+    coverageMap.files().forEach(filePath => {
+        const isIncluded = config.includePatterns.some(pattern => minimatch(filePath, pattern));
+        const isExcluded = config.excludePatterns.some(pattern => minimatch(filePath, pattern));
+        if (isIncluded && !isExcluded) {
+            filteredCoverage.addFileCoverage(coverageMap.fileCoverageFor(filePath));
+        }
+    });
+    return filteredCoverage;
+};
+const generateReports = (coverageMap, config) => {
+    const context = libReport.createContext({
+        dir: `${config.workspaceRoot}/${config.outputDir}`,
+        coverageMap,
+    });
+    config.reporters.forEach(reportType => {
+        const report = reports.create(reportType, {
+            projectRoot: config.workspaceRoot,
+        });
+        report.execute(context);
+    });
+};
+
+const isBaseURL = (url, config) => {
+    return url.startsWith(config.baseURL);
+};
+const isFsPath = (path) => {
+    // Not source files in angular, pain to map
+    return path.indexOf('@fs') > 0;
+};
+// Only map in case of "bundled angular app"
+// Bundled js in this mode does not contain inline sourcemaps
+// So we need this for v8ToIstanbull to handle path resolution
+const mapCoverageReportToScriptPath = (coverageReport, config) => {
+    if (config.bundleLocation) {
+        const urlObj = new URL(coverageReport.url);
+        const { pathname } = urlObj;
+        return join(`${config.workspaceRoot}/${config.bundleLocation}`, pathname);
+    }
+    else {
+        return coverageReport.url;
+    }
+};
+const mapPlaywrightCoverageToIstanbul = async (coverageReport, config) => {
+    if (isFsPath(coverageReport.url) ||
+        !isBaseURL(coverageReport.url, config) ||
+        !coverageReport.source ||
+        !(coverageReport.functions.length > 0)) {
+        return null;
+    }
+    const converter = v8toIstanbul(mapCoverageReportToScriptPath(coverageReport, config), 0, coverageReport.source ? { source: coverageReport.source } : undefined);
+    await converter.load();
+    converter.applyCoverage(coverageReport.functions);
+    return converter.toIstanbul();
+};
+const mapReportsToMapData = async (coverageReports, config) => {
+    const istanbulCoverage = await Promise.all(coverageReports.map(async (entry) => mapPlaywrightCoverageToIstanbul(entry, config)));
+    return istanbulCoverage.filter(mappedData => mappedData !== null);
+};
+
+class CoverageReporter {
+    #coverageMap = libCoverage.createCoverageMap();
+    #config;
+    constructor(options) {
+        if (!options) {
+            throw new Error('No configuration provided for coverage reporter');
+        }
+        if (!options.workspaceRoot) {
+            throw new Error('No project root provided for coverage reporter');
+        }
+        if (!options.includePatterns || !options.includePatterns.length) {
+            throw new Error('No include patterns provided for coverage reporter');
+        }
+        this.#config = defineCoverageReporterConfig(options);
+        if (this.#config.debug) {
+            console.info('Coverage reporter configuration:', this.#config);
+        }
+    }
+    onBegin() {
+        console.info('Starting coverage reporter...');
+        const outputDir = `${this.#config.workspaceRoot}/${this.#config.outputDir}`;
+        if (existsSync(outputDir)) {
+            rmSync(outputDir, { recursive: true, force: true });
+        }
+        mkdirSync(outputDir, { recursive: true });
+    }
+    async onTestEnd(test, result) {
+        if (result.attachments) {
+            try {
+                const coverageReport = unmarshallCoverage(result.attachments);
+                const coverageMapData = await mapReportsToMapData(coverageReport, this.#config);
+                coverageMapData.forEach((map) => {
+                    const postProcessedCoverageMap = postProcessIstanbulCoverMap(map, this.#config);
+                    this.#coverageMap.merge(postProcessedCoverageMap);
+                });
+            }
+            catch (error) {
+                console.error(`Failed to process coverage data for "${test.title}" :`, error);
+            }
+        }
+    }
+    async onEnd() {
+        const filteredCoverageMap = filterCoverageMap(this.#coverageMap, this.#config);
+        generateReports(filteredCoverageMap, this.#config);
+        console.info('Coverage reports generated...');
+    }
+}
+
+const testWithCoverage = test.extend({
+    page: async ({ context, page }, use, testInfo) => {
+        if (context.browser()?.browserType()?.name() !== 'chromium') {
+            return use(page);
+        }
+        else {
+            await page.coverage.startJSCoverage({ resetOnNavigation: false });
+            await use(page);
+            const coverage = await page.coverage.stopJSCoverage();
+            await testInfo.attach(coverageFileKey, marshallCoverage(coverage));
+        }
+    },
+});
+
+export { COVERAGE_REPORTER_DEFAULTS, CoverageReporter, CoverageReporter as default, defineCoverageReporterConfig, testWithCoverage };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "playwright-code-coverage",
+  "version": "0.0.0-alpha",
+  "description": "Reporter for generating istanbul coverage reports for playwright tests ",
+  "keywords": [
+    "playwright",
+    "coverage",
+    "istanbul",
+    "reporter"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": "^1.40.0"
+  },
+  "dependencies": {
+    "istanbul-lib-coverage": "^3.2.2",
+    "istanbul-lib-report": "^3.0.1",
+    "istanbul-reports": "^3.2.0",
+    "minimatch": "^10.1.2",
+    "v8-to-istanbul": "^9.3.0"
+  },
+  "module": "./index.esm.js",
+  "type": "module",
+  "main": "./index.esm.js",
+  "types": "./index.d.ts"
+}

package/src/config.d.ts

@@ -0,0 +1,19 @@
+import { ReportType } from 'istanbul-reports';
+export type CoverageReporterConfig = {
+    workspaceRoot: string;
+    outputDir: string;
+    baseURL: string;
+    bundleLocation: string;
+    includePatterns: string[];
+    excludePatterns: string[];
+    reporters: ReportType[];
+    debug?: boolean;
+};
+export declare const COVERAGE_REPORTER_DEFAULTS: {
+    outputDir: string;
+    reporters: ReportType[];
+    baseUrl: string;
+    includePatterns: string[];
+};
+export declare const defineCoverageReporterConfig: (config: Partial<CoverageReporterConfig>) => CoverageReporterConfig;
+//# sourceMappingURL=config.d.ts.map

package/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../../libs/playwright-code-coverage/src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,MAAM,sBAAsB,GAAG;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,0BAA0B;;eAEd,UAAU,EAAE;;;CAGpC,CAAC;AAEF,eAAO,MAAM,4BAA4B,GACvC,QAAQ,OAAO,CAAC,sBAAsB,CAAC,KACtC,sBAWF,CAAC"}

package/src/coverage-reporter.d.ts

@@ -0,0 +1,11 @@
+import type { Reporter, TestCase, TestResult } from '@playwright/test/reporter';
+import { CoverageReporterConfig } from './config';
+export declare class CoverageReporter implements Reporter {
+    #private;
+    constructor(options?: Partial<CoverageReporterConfig>);
+    onBegin(): void;
+    onTestEnd(test: TestCase, result: TestResult): Promise<void>;
+    onEnd(): Promise<void>;
+}
+export default CoverageReporter;
+//# sourceMappingURL=coverage-reporter.d.ts.map

package/src/coverage-reporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-reporter.d.ts","sourceRoot":"","sources":["../../../../libs/playwright-code-coverage/src/coverage-reporter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAGhF,OAAO,EAAE,sBAAsB,EAAgC,MAAM,UAAU,CAAC;AAShF,qBAAa,gBAAiB,YAAW,QAAQ;;gBAInC,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC;IAiBrD,OAAO;IASD,SAAS,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU;IAe5C,KAAK;CAKZ;AAED,eAAe,gBAAgB,CAAC"}

package/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './config';
+export * from './coverage-reporter';
+export { default } from './coverage-reporter';
+export * from './test-with-coverage';
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../libs/playwright-code-coverage/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AAC9C,cAAc,sBAAsB,CAAC"}

package/src/models.d.ts

@@ -0,0 +1,21 @@
+export type CoverageReport = {
+    url: string;
+    scriptId: string;
+    source?: string;
+    functions: Array<{
+        functionName: string;
+        isBlockCoverage: boolean;
+        ranges: Array<{
+            count: number;
+            startOffset: number;
+            endOffset: number;
+        }>;
+    }>;
+};
+export type Attachment = {
+    name: string;
+    contentType: string;
+    path?: string;
+    body?: Buffer;
+};
+//# sourceMappingURL=models.d.ts.map

package/src/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../../libs/playwright-code-coverage/src/models.ts"],"names":[],"mappings":"AACA,MAAM,MAAM,cAAc,GAAG;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,KAAK,CAAC;QACf,YAAY,EAAE,MAAM,CAAC;QACrB,eAAe,EAAE,OAAO,CAAC;QACzB,MAAM,EAAE,KAAK,CAAC;YACZ,KAAK,EAAE,MAAM,CAAC;YACd,WAAW,EAAE,MAAM,CAAC;YACpB,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC,CAAC;KACJ,CAAC,CAAC;CACJ,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC"}

package/src/test-with-coverage.d.ts

@@ -0,0 +1,2 @@
+export declare const testWithCoverage: import("@playwright/test").TestType<import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions, import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions>;
+//# sourceMappingURL=test-with-coverage.d.ts.map

package/src/test-with-coverage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-with-coverage.d.ts","sourceRoot":"","sources":["../../../../libs/playwright-code-coverage/src/test-with-coverage.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,gBAAgB,6OAa3B,CAAC"}

package/src/utils/attachment.utils.d.ts

@@ -0,0 +1,8 @@
+import { Attachment, CoverageReport } from '../models';
+export declare const coverageFileKey = "coverage";
+export declare const marshallCoverage: (coverage: CoverageReport[]) => {
+    body: Buffer<ArrayBuffer>;
+    contentType: string;
+};
+export declare const unmarshallCoverage: (attachments: Attachment[]) => CoverageReport[];
+//# sourceMappingURL=attachment.utils.d.ts.map

package/src/utils/attachment.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment.utils.d.ts","sourceRoot":"","sources":["../../../../../libs/playwright-code-coverage/src/utils/attachment.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEvD,eAAO,MAAM,eAAe,aAAa,CAAC;AAE1C,eAAO,MAAM,gBAAgB,GAAI,UAAU,cAAc,EAAE;;;CAK1D,CAAC;AAEF,eAAO,MAAM,kBAAkB,GAAI,aAAa,UAAU,EAAE,qBAM3D,CAAC"}

package/src/utils/coverage-map.utils.d.ts

@@ -0,0 +1,6 @@
+import { CoverageMap, CoverageMapData } from 'istanbul-lib-coverage';
+import { CoverageReporterConfig } from '../config';
+export declare const postProcessIstanbulCoverMap: (coverageMapData: CoverageMapData, config: CoverageReporterConfig) => CoverageMapData;
+export declare const filterCoverageMap: (coverageMap: CoverageMap, config: CoverageReporterConfig) => CoverageMap;
+export declare const generateReports: (coverageMap: CoverageMap, config: CoverageReporterConfig) => void;
+//# sourceMappingURL=coverage-map.utils.d.ts.map

package/src/utils/coverage-map.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-map.utils.d.ts","sourceRoot":"","sources":["../../../../../libs/playwright-code-coverage/src/utils/coverage-map.utils.ts"],"names":[],"mappings":"AAAA,OAAoB,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAIlF,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEnD,eAAO,MAAM,2BAA2B,GACtC,iBAAiB,eAAe,EAChC,QAAQ,sBAAsB,KAC7B,eAyBF,CAAC;AAEF,eAAO,MAAM,iBAAiB,GAC5B,aAAa,WAAW,EACxB,QAAQ,sBAAsB,KAC7B,WAYF,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,aAAa,WAAW,EAAE,QAAQ,sBAAsB,KAAG,IAa1F,CAAC"}

package/src/utils/coverage-report.utils.d.ts

@@ -0,0 +1,5 @@
+import { CoverageMapData } from 'istanbul-lib-coverage';
+import { CoverageReporterConfig } from '../config';
+import { CoverageReport } from '../models';
+export declare const mapReportsToMapData: (coverageReports: CoverageReport[], config: CoverageReporterConfig) => Promise<CoverageMapData[]>;
+//# sourceMappingURL=coverage-report.utils.d.ts.map

package/src/utils/coverage-report.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coverage-report.utils.d.ts","sourceRoot":"","sources":["../../../../../libs/playwright-code-coverage/src/utils/coverage-report.utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAkD3C,eAAO,MAAM,mBAAmB,GAC9B,iBAAiB,cAAc,EAAE,EACjC,QAAQ,sBAAsB,KAC7B,OAAO,CAAC,eAAe,EAAE,CAK3B,CAAC"}