stably 4.8.9 → 4.10.0

package/dist/stably-plugin/skills/playwright-best-practices/references/test-coverage.md

@@ -1,495 +0,0 @@
-# Test Coverage
-
-## Table of Contents
-
-1. [Coverage Setup](#coverage-setup)
-2. [Collecting Coverage](#collecting-coverage)
-3. [Coverage Reports](#coverage-reports)
-4. [Coverage Thresholds](#coverage-thresholds)
-5. [Advanced Patterns](#advanced-patterns)
-6. [CI Integration](#ci-integration)
-
-## Coverage Setup
-
-### Install Dependencies
-
-```bash
-# For V8 coverage (built into Playwright)
-# No additional dependencies needed
-
-# For Istanbul-based coverage (more features)
-npm install -D nyc @istanbuljs/nyc-config-typescript
-```
-
-### Basic Configuration
-
-```typescript
-// playwright.config.ts
-import { defineConfig } from "@playwright/test";
-
-export default defineConfig({
-  use: {
-    // Enable coverage collection
-    contextOptions: {
-      // V8 coverage is automatic with the API below
-    },
-  },
-});
-```
-
-### V8 Coverage Fixture
-
-```typescript
-// fixtures/coverage.ts
-import { test as base, expect } from "@playwright/test";
-import fs from "fs";
-import path from "path";
-import { randomUUID } from "crypto";
-
-export const test = base.extend<{}, { collectCoverage: void }>({
-  collectCoverage: [
-    async ({ browser }, use) => {
-      // Start coverage for all pages
-      const context = await browser.newContext();
-      const page = await context.newPage();
-
-      await page.coverage.startJSCoverage();
-      await page.coverage.startCSSCoverage();
-
-      await use();
-
-      // Collect coverage
-      const [jsCoverage, cssCoverage] = await Promise.all([
-        page.coverage.stopJSCoverage(),
-        page.coverage.stopCSSCoverage(),
-      ]);
-
-      // Save coverage data
-      const coverageDir = "./coverage";
-      if (!fs.existsSync(coverageDir)) {
-        fs.mkdirSync(coverageDir, { recursive: true });
-      }
-
-      fs.writeFileSync(
-        path.join(coverageDir, `coverage-${randomUUID()}.json`),
-        JSON.stringify([...jsCoverage, ...cssCoverage]),
-      );
-
-      await context.close();
-    },
-    { scope: "worker", auto: true },
-  ],
-});
-```
-
-## Collecting Coverage
-
-### Per-Test Coverage
-
-```typescript
-test("collect coverage for single test", async ({ page }) => {
-  // Start coverage collection
-  await page.coverage.startJSCoverage({
-    resetOnNavigation: false,
-  });
-
-  // Run test
-  await page.goto("/app");
-  await page.getByRole("button", { name: "Submit" }).click();
-  await expect(page.getByText("Success")).toBeVisible();
-
-  // Stop and get coverage
-  const coverage = await page.coverage.stopJSCoverage();
-
-  // Filter to only your source files
-  const appCoverage = coverage.filter((entry) => entry.url.includes("/src/"));
-
-  console.log(`Covered ${appCoverage.length} source files`);
-});
-```
-
-### Coverage for Specific Files
-
-```typescript
-test("track specific module coverage", async ({ page }) => {
-  await page.coverage.startJSCoverage();
-
-  await page.goto("/checkout");
-  await page.getByRole("button", { name: "Pay" }).click();
-
-  const coverage = await page.coverage.stopJSCoverage();
-
-  // Find coverage for checkout module
-  const checkoutCoverage = coverage.find((c) => c.url.includes("checkout.js"));
-
-  if (checkoutCoverage) {
-    const totalBytes = checkoutCoverage.text?.length || 0;
-    const coveredBytes = checkoutCoverage.ranges.reduce(
-      (sum, range) => sum + (range.end - range.start),
-      0,
-    );
-    const percentage = (coveredBytes / totalBytes) * 100;
-
-    console.log(`Checkout module: ${percentage.toFixed(1)}% covered`);
-    expect(percentage).toBeGreaterThan(80);
-  }
-});
-```
-
-### CSS Coverage
-
-```typescript
-test("collect CSS coverage", async ({ page }) => {
-  await page.coverage.startCSSCoverage();
-
-  await page.goto("/app");
-
-  // Interact to trigger different CSS states
-  await page.getByRole("button").hover();
-  await page.getByRole("dialog").waitFor();
-
-  const cssCoverage = await page.coverage.stopCSSCoverage();
-
-  // Find unused CSS
-  for (const entry of cssCoverage) {
-    const totalBytes = entry.text?.length || 0;
-    const usedBytes = entry.ranges.reduce(
-      (sum, range) => sum + (range.end - range.start),
-      0,
-    );
-    const unusedPercentage = ((totalBytes - usedBytes) / totalBytes) * 100;
-
-    if (unusedPercentage > 50) {
-      console.warn(`${entry.url}: ${unusedPercentage.toFixed(1)}% unused CSS`);
-    }
-  }
-});
-```
-
-## Coverage Reports
-
-### Converting to Istanbul Format
-
-```typescript
-// scripts/convert-coverage.ts
-import { execSync } from "child_process";
-import fs from "fs";
-import path from "path";
-import v8ToIstanbul from "v8-to-istanbul";
-
-async function convertCoverage() {
-  const coverageDir = "./coverage";
-  const files = fs.readdirSync(coverageDir).filter((f) => f.endsWith(".json"));
-
-  const istanbulCoverage: any = {};
-
-  for (const file of files) {
-    const coverageData = JSON.parse(
-      fs.readFileSync(path.join(coverageDir, file), "utf-8"),
-    );
-
-    for (const entry of coverageData) {
-      if (!entry.url.startsWith("file://")) continue;
-
-      const filePath = entry.url.replace("file://", "");
-      const converter = v8ToIstanbul(filePath);
-
-      await converter.load();
-      converter.applyCoverage(entry.functions || []);
-
-      const istanbul = converter.toIstanbul();
-      Object.assign(istanbulCoverage, istanbul);
-    }
-  }
-
-  fs.writeFileSync(
-    path.join(coverageDir, "coverage-final.json"),
-    JSON.stringify(istanbulCoverage),
-  );
-}
-
-convertCoverage();
-```
-
-### Generating HTML Report
-
-```bash
-# Using nyc to generate report
-npx nyc report --reporter=html --reporter=text --temp-dir=./coverage
-```
-
-```typescript
-// package.json scripts
-{
-  "scripts": {
-    "test": "playwright test",
-    "test:coverage": "playwright test && npm run coverage:report",
-    "coverage:report": "npx nyc report --reporter=html --reporter=lcov --temp-dir=./coverage"
-  }
-}
-```
-
-### Custom Coverage Reporter
-
-```typescript
-// reporters/coverage-reporter.ts
-import type { Reporter, FullResult } from "@playwright/test/reporter";
-import fs from "fs";
-import path from "path";
-
-class CoverageReporter implements Reporter {
-  private coverageData: any[] = [];
-
-  onEnd(result: FullResult) {
-    // Aggregate all coverage files
-    const coverageDir = "./coverage";
-    const files = fs
-      .readdirSync(coverageDir)
-      .filter((f) => f.endsWith(".json"));
-
-    for (const file of files) {
-      const data = JSON.parse(
-        fs.readFileSync(path.join(coverageDir, file), "utf-8"),
-      );
-      this.coverageData.push(...data);
-    }
-
-    // Generate summary
-    const summary = this.generateSummary();
-    console.log("\n📊 Coverage Summary:");
-    console.log(`   Files: ${summary.totalFiles}`);
-    console.log(`   Lines: ${summary.lineCoverage.toFixed(1)}%`);
-    console.log(`   Bytes: ${summary.byteCoverage.toFixed(1)}%`);
-
-    if (summary.lineCoverage < 80) {
-      console.warn("⚠️  Coverage below 80% threshold!");
-    }
-  }
-
-  private generateSummary() {
-    let totalBytes = 0;
-    let coveredBytes = 0;
-    const files = new Set<string>();
-
-    for (const entry of this.coverageData) {
-      if (entry.url.includes("/src/")) {
-        files.add(entry.url);
-        totalBytes += entry.text?.length || 0;
-        coveredBytes += entry.ranges.reduce(
-          (sum: number, r: any) => sum + (r.end - r.start),
-          0,
-        );
-      }
-    }
-
-    return {
-      totalFiles: files.size,
-      byteCoverage: (coveredBytes / totalBytes) * 100,
-      lineCoverage: (coveredBytes / totalBytes) * 100, // Simplified
-    };
-  }
-}
-
-export default CoverageReporter;
-```
-
-## Coverage Thresholds
-
-### Enforcing Minimum Coverage
-
-```typescript
-// tests/coverage.spec.ts
-import { test, expect } from "@playwright/test";
-import fs from "fs";
-import path from "path";
-
-test.afterAll(async () => {
-  const coverageDir = "./coverage";
-  const files = fs.readdirSync(coverageDir).filter((f) => f.endsWith(".json"));
-
-  let totalBytes = 0;
-  let coveredBytes = 0;
-
-  for (const file of files) {
-    const coverage = JSON.parse(
-      fs.readFileSync(path.join(coverageDir, file), "utf-8"),
-    );
-
-    for (const entry of coverage) {
-      if (!entry.url.includes("/src/")) continue;
-      totalBytes += entry.text?.length || 0;
-      coveredBytes += entry.ranges.reduce(
-        (sum: number, r: any) => sum + (r.end - r.start),
-        0,
-      );
-    }
-  }
-
-  const coveragePercent = (coveredBytes / totalBytes) * 100;
-
-  // Enforce threshold
-  expect(coveragePercent).toBeGreaterThan(80);
-});
-```
-
-### Per-Directory Thresholds
-
-```typescript
-// coverage-check.ts
-interface CoverageThreshold {
-  pattern: RegExp;
-  minCoverage: number;
-}
-
-const thresholds: CoverageThreshold[] = [
-  { pattern: /\/src\/core\//, minCoverage: 90 },
-  { pattern: /\/src\/utils\//, minCoverage: 85 },
-  { pattern: /\/src\/components\//, minCoverage: 70 },
-  { pattern: /\/src\/pages\//, minCoverage: 60 },
-];
-
-function checkThresholds(coverage: any[]): string[] {
-  const violations: string[] = [];
-
-  for (const threshold of thresholds) {
-    const matchingFiles = coverage.filter((c) => threshold.pattern.test(c.url));
-
-    let total = 0;
-    let covered = 0;
-
-    for (const file of matchingFiles) {
-      total += file.text?.length || 0;
-      covered += file.ranges.reduce(
-        (sum: number, r: any) => sum + (r.end - r.start),
-        0,
-      );
-    }
-
-    const percent = total > 0 ? (covered / total) * 100 : 0;
-
-    if (percent < threshold.minCoverage) {
-      violations.push(
-        `${threshold.pattern}: ${percent.toFixed(1)}% < ${threshold.minCoverage}%`,
-      );
-    }
-  }
-
-  return violations;
-}
-```
-
-## Advanced Patterns
-
-### Merging Coverage Across Shards
-
-```typescript
-// scripts/merge-coverage.ts
-import fs from "fs";
-import { glob } from "glob";
-
-async function mergeCoverage() {
-  const files = await glob("shard-*/coverage/*.json");
-  const merged = new Map<string, any>();
-
-  for (const file of files) {
-    const data = JSON.parse(fs.readFileSync(file, "utf-8"));
-    for (const entry of data) {
-      if (merged.has(entry.url)) {
-        const existing = merged.get(entry.url);
-        existing.ranges.push(...entry.ranges);
-      } else {
-        merged.set(entry.url, { ...entry });
-      }
-    }
-  }
-
-  fs.writeFileSync(
-    "./coverage/merged.json",
-    JSON.stringify([...merged.values()]),
-  );
-}
-
-mergeCoverage();
-```
-
-### Incremental Coverage
-
-```typescript
-// Check coverage only for changed files in CI
-import { execSync } from "child_process";
-import fs from "fs";
-
-const changedFiles = execSync("git diff --name-only HEAD~1")
-  .toString()
-  .split("\n")
-  .filter((f) => f.endsWith(".ts"));
-
-const coverage = JSON.parse(fs.readFileSync("./coverage/merged.json", "utf-8"));
-
-for (const file of changedFiles) {
-  const entry = coverage.find((c: any) => c.url.includes(file));
-  if (entry) {
-    const percent =
-      (entry.ranges.reduce((s: number, r: any) => s + r.end - r.start, 0) /
-        (entry.text?.length || 1)) *
-      100;
-    console.log(`${file}: ${percent.toFixed(1)}%`);
-  }
-}
-```
-
-## CI Integration
-
-### GitHub Actions
-
-```yaml
-# .github/workflows/test.yml
-name: Tests with Coverage
-
-on: [push, pull_request]
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - run: npm ci
-      - run: npx playwright install --with-deps
-
-      - name: Run tests with coverage
-        run: npm run test:coverage
-
-      - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v3
-        with:
-          files: ./coverage/lcov.info
-          fail_ci_if_error: true
-
-      - name: Check coverage threshold
-        run: |
-          COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
-          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
-            echo "Coverage $COVERAGE% is below 80% threshold"
-            exit 1
-          fi
-```
-
-## Anti-Patterns to Avoid
-
-| Anti-Pattern                 | Problem                                | Solution                    |
-| ---------------------------- | -------------------------------------- | --------------------------- |
-| Coverage for coverage's sake | Gaming metrics                         | Focus on critical paths     |
-| 100% coverage target         | Diminishing returns, tests for getters | Set realistic thresholds    |
-| Ignoring coverage drops      | Technical debt                         | Enforce thresholds in CI    |
-| No source map support        | Wrong line numbers                     | Enable source maps in build |
-| Coverage only in CI          | Late feedback                          | Run locally too             |
-
-## Related References
-
-- **CI/CD**: See [ci-cd.md](ci-cd.md) for pipeline configuration
-- **Performance**: See [performance.md](performance.md) for optimizing coverage collection