@slashgear/gdpr-cookie-scanner 1.3.0 → 1.4.0

package/.github/workflows/ci.yml

@@ -36,3 +36,9 @@ jobs:
 
       - name: Build
         run: pnpm build
+
+      - name: Install Playwright browsers
+        run: pnpm exec playwright install chromium --with-deps
+
+      - name: Test
+        run: pnpm test

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @slashgear/gdpr-cookie-scanner
 
+## 1.4.0
+
+### Minor Changes
+
+- 5af8678: test: add Vitest unit and E2E test suite
+
+  Introduces a comprehensive test suite using Vitest:
+
+  - **Unit tests** (76 tests) covering the three pure-logic modules:
+    `cookie-classifier`, `network-classifier`, `wording` analyzer, and
+    `compliance` analyzer — verifying scoring rules, dark pattern detection,
+    and cookie/tracker classification across French and English content.
+
+  - **E2E tests** (14 tests) that spin up a local HTTP server serving three
+    HTML fixtures (compliant banner, non-compliant banner, no modal) and run
+    the full Playwright scanner against them, asserting detected modals,
+    cookie behavior, and compliance grades.
+
+  - **CI integration**: the GitHub Actions workflow now installs Playwright's
+    Chromium browser and runs `pnpm test` after every build, blocking merges
+    on test failures.
+
 ## 1.3.0
 
 ### Minor Changes

package/README.md

@@ -69,58 +69,12 @@ gdpr-scan list-trackers
 
 ## How it works
 
-The scanner runs **4 phases** using a real Chromium browser (Playwright):
-
-1. **Initial load** — The page is loaded without any interaction. All cookies and network requests are captured (`before-interaction`).
-2. **Modal analysis** — The consent banner is detected (CSS selectors of known CMPs + DOM heuristics). Buttons are extracted with their visual properties (size, color, contrast ratio).
-3. **Reject test** — The "Reject" button is clicked. Cookies and requests are captured (`after-reject`).
-4. **Accept test** — A new browser session (clean state) loads the page and clicks "Accept". Cookies and requests are captured (`after-accept`).
-
-## Architecture
-
 ```mermaid
-flowchart TD
-    CLI["⌨️  gdpr-scan CLI\n─────────────────\nURL · options"]
-
-    CLI --> B
-
-    subgraph B["🌐  Chromium browser — 4 sequential phases"]
-        direction TB
-        P1["Phase 1 — Load page\nCapture cookies & network requests\n(before-interaction)"]
-        P2["Phase 2 — Detect consent modal\nCSS selectors · DOM heuristics\nExtract buttons, checkboxes, screenshots"]
-        P3["Phase 3 — Click Reject  (same session)\nCapture state  (after-reject)"]
-        P4["Phase 4 — Fresh session · Click Accept\nCapture state  (after-accept)"]
-        P1 --> P2 --> P3 --> P4
-    end
-
-    B --> C
-
-    subgraph C["🔎  Classifiers"]
-        direction LR
-        CK["Cookie classifier\n─────────────\nPattern matching → category\n(analytics, ads, strictly-necessary…)"]
-        NK["Network classifier\n─────────────\nTracker DB lookup\nPixel pattern matching"]
-    end
-
-    C --> A
-
-    subgraph A["⚖️  Analyzers"]
-        direction LR
-        SC["Compliance scorer\n─────────────\n4 dimensions × 25 pts\n→ score 0–100, grade A–F"]
-        DP["Dark pattern detector\n─────────────\nPre-ticked boxes · asymmetry\nMissing reject · misleading wording"]
-    end
-
-    A --> R
-
-    subgraph R["📄  Report generator"]
-        direction LR
-        MD1["gdpr-report-*.md\nMain compliance report"]
-        MD2["gdpr-checklist-*.md\nPer-rule checklist\nwith legal references"]
-        MD3["gdpr-cookies-*.md\nDeduplicated cookie\ninventory"]
-        PDF["gdpr-report-*.pdf\nMerged PDF with TOC\n& embedded screenshots"]
-    end
+flowchart LR
+    URL([URL]) --> Chromium[Chromium] --> Classify[Classify] --> Score[Score] --> Report[Report]
 ```
 
-The tool runs a **real Chromium browser** (via Playwright) through 4 isolated phases to capture the site's behaviour before any interaction, on modal detection, after rejection, and after acceptance. Raw data is then classified (cookies by name pattern, network requests against a tracker database), scored across 4 compliance dimensions, and rendered into 3 Markdown files plus a self-contained PDF.
+A real Chromium browser loads the page, interacts with the consent modal (reject then accept in a fresh session), and captures cookies and network requests at each step. Results are classified, scored across 4 compliance dimensions, and rendered into Markdown and PDF reports.
 
 ## Generated report
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slashgear/gdpr-cookie-scanner",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI tool to scan websites for GDPR cookie consent compliance",
   "keywords": [
     "compliance",
@@ -43,7 +43,8 @@
     "@types/node": "^22.0.0",
     "oxfmt": "^0.33.0",
     "oxlint": "^1.48.0",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=20.0.0"
@@ -57,6 +58,8 @@
     "format": "oxfmt .",
     "format:check": "oxfmt --check .",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "changeset": "changeset"
   }
 }

package/tests/e2e/fixtures/compliant-site.html

@@ -0,0 +1,80 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Compliant Test Site</title>
+  </head>
+  <body>
+    <main>
+      <h1>Welcome to our website</h1>
+      <p>This is a test page with a GDPR-compliant cookie banner.</p>
+    </main>
+
+    <footer>
+      <a href="/privacy-policy">Privacy Policy</a>
+      <a href="/terms">Terms of Service</a>
+    </footer>
+
+    <!-- GDPR-compliant cookie banner -->
+    <div
+      id="cookie-banner"
+      style="
+        position: fixed;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        background: #1a1a2e;
+        color: #fff;
+        padding: 20px;
+        z-index: 9999;
+        display: flex;
+        align-items: center;
+        gap: 16px;
+      "
+    >
+      <p style="flex: 1; margin: 0">
+        We use cookies for analytics purposes with <strong>third-party vendors</strong>. Cookies
+        expire after <strong>13 months</strong>. You may <strong>withdraw your consent</strong> at
+        any time. See our <a href="/privacy-policy" style="color: #90e0ef">Privacy Policy</a>.
+      </p>
+      <button
+        id="reject-btn"
+        style="
+          padding: 10px 20px;
+          background: transparent;
+          color: #fff;
+          border: 1px solid #fff;
+          cursor: pointer;
+          font-size: 14px;
+        "
+      >
+        Reject all
+      </button>
+      <button
+        id="accept-btn"
+        style="
+          padding: 10px 20px;
+          background: #4caf50;
+          color: #fff;
+          border: none;
+          cursor: pointer;
+          font-size: 14px;
+        "
+      >
+        Accept all
+      </button>
+    </div>
+
+    <script>
+      document.getElementById("accept-btn").addEventListener("click", function () {
+        document.getElementById("cookie-banner").style.display = "none";
+        document.cookie = "consent=accepted; path=/; max-age=31536000";
+      });
+
+      document.getElementById("reject-btn").addEventListener("click", function () {
+        document.getElementById("cookie-banner").style.display = "none";
+        document.cookie = "consent=rejected; path=/; max-age=31536000";
+      });
+    </script>
+  </body>
+</html>

package/tests/e2e/fixtures/no-modal-site.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>No Modal Test Site</title>
+  </head>
+  <body>
+    <main>
+      <h1>Welcome</h1>
+      <p>This page has no cookie consent modal at all.</p>
+    </main>
+
+    <footer>
+      <a href="/privacy-policy">Privacy Policy</a>
+    </footer>
+  </body>
+</html>

package/tests/e2e/fixtures/non-compliant-site.html

@@ -0,0 +1,54 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Non-Compliant Test Site</title>
+  </head>
+  <body>
+    <main>
+      <h1>Welcome</h1>
+      <p>This page has no reject button and sets analytics cookies immediately.</p>
+    </main>
+
+    <!-- Non-compliant: no reject button, no privacy policy link, cookie set before interaction -->
+    <div
+      id="cookie-banner"
+      style="
+        position: fixed;
+        bottom: 0;
+        left: 0;
+        right: 0;
+        background: #333;
+        color: #fff;
+        padding: 20px;
+        z-index: 9999;
+      "
+    >
+      <p style="margin: 0 0 10px 0">
+        By continuing to browse this site, you accept the use of cookies.
+      </p>
+      <button
+        id="accept-btn"
+        style="
+          padding: 10px 24px;
+          background: #e53935;
+          color: #fff;
+          border: none;
+          cursor: pointer;
+          font-size: 16px;
+        "
+      >
+        OK
+      </button>
+    </div>
+
+    <script>
+      // Set analytics cookie before any interaction (non-compliant)
+      document.cookie = "_ga=GA1.2.123456789.1234567890; path=/; max-age=34560000";
+
+      document.getElementById("accept-btn").addEventListener("click", function () {
+        document.getElementById("cookie-banner").style.display = "none";
+      });
+    </script>
+  </body>
+</html>

package/tests/e2e/scanner.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
+import { Scanner } from "../../src/scanner/index.js";
+import { startTestServer, type TestServer } from "../helpers/test-server.js";
+
+// E2E tests spin up real Playwright browsers — allow generous timeouts
+const E2E_TIMEOUT = 60_000;
+
+describe("Scanner E2E", { timeout: E2E_TIMEOUT }, () => {
+  let server: TestServer;
+  let outputDir: string;
+
+  beforeAll(async () => {
+    server = await startTestServer();
+    outputDir = await mkdtemp(join(tmpdir(), "gdpr-test-"));
+  });
+
+  afterAll(async () => {
+    await server.close();
+    await rm(outputDir, { recursive: true, force: true });
+  });
+
+  function makeOptions(fixture: string) {
+    return {
+      url: `${server.url}/${fixture}`,
+      outputDir: join(outputDir, fixture.replace(".html", "")),
+      timeout: 30_000,
+      screenshots: false,
+      locale: "en-US",
+      verbose: false,
+    };
+  }
+
+  describe("compliant-site.html", () => {
+    it("detects the consent modal", async () => {
+      const scanner = new Scanner(makeOptions("compliant-site.html"));
+      const result = await scanner.run();
+      expect(result.modal.detected).toBe(true);
+    });
+
+    it("finds both accept and reject buttons", async () => {
+      const scanner = new Scanner(makeOptions("compliant-site.html"));
+      const result = await scanner.run();
+      const types = result.modal.buttons.map((b) => b.type);
+      expect(types).toContain("accept");
+      expect(types).toContain("reject");
+    });
+
+    it("finds the privacy policy link in the modal", async () => {
+      const scanner = new Scanner(makeOptions("compliant-site.html"));
+      const result = await scanner.run();
+      expect(result.modal.privacyPolicyUrl).toBeTruthy();
+    });
+
+    it("finds a privacy policy link on the page", async () => {
+      const scanner = new Scanner(makeOptions("compliant-site.html"));
+      const result = await scanner.run();
+      expect(result.privacyPolicyUrl).toBeTruthy();
+    });
+
+    it("assigns a passing compliance grade (A or B)", async () => {
+      const scanner = new Scanner(makeOptions("compliant-site.html"));
+      const result = await scanner.run();
+      expect(["A", "B"]).toContain(result.compliance.grade);
+    });
+
+    it("does not flag pre-consent cookies", async () => {
+      const scanner = new Scanner(makeOptions("compliant-site.html"));
+      const result = await scanner.run();
+      const illegalPreConsent = result.cookiesBeforeInteraction.filter((c) => c.requiresConsent);
+      expect(illegalPreConsent).toHaveLength(0);
+    });
+  });
+
+  describe("non-compliant-site.html", () => {
+    it("detects the consent modal", async () => {
+      const scanner = new Scanner(makeOptions("non-compliant-site.html"));
+      const result = await scanner.run();
+      expect(result.modal.detected).toBe(true);
+    });
+
+    it("detects _ga cookie set before any interaction", async () => {
+      const scanner = new Scanner(makeOptions("non-compliant-site.html"));
+      const result = await scanner.run();
+      const gaBeforeInteraction = result.cookiesBeforeInteraction.some(
+        (c) => c.name === "_ga" && c.requiresConsent,
+      );
+      expect(gaBeforeInteraction).toBe(true);
+    });
+
+    it("raises an auto-consent issue for pre-interaction cookies", async () => {
+      const scanner = new Scanner(makeOptions("non-compliant-site.html"));
+      const result = await scanner.run();
+      const issue = result.compliance.issues.find((i) => i.type === "auto-consent");
+      expect(issue).toBeDefined();
+    });
+
+    it("assigns a failing grade (C, D, or F)", async () => {
+      const scanner = new Scanner(makeOptions("non-compliant-site.html"));
+      const result = await scanner.run();
+      expect(["C", "D", "F"]).toContain(result.compliance.grade);
+    });
+  });
+
+  describe("no-modal-site.html", () => {
+    it("reports modal as not detected", async () => {
+      const scanner = new Scanner(makeOptions("no-modal-site.html"));
+      const result = await scanner.run();
+      expect(result.modal.detected).toBe(false);
+    });
+
+    it("still finds the page-level privacy policy link", async () => {
+      const scanner = new Scanner(makeOptions("no-modal-site.html"));
+      const result = await scanner.run();
+      expect(result.privacyPolicyUrl).toBeTruthy();
+    });
+
+    it("assigns grade F when no modal is detected", async () => {
+      const scanner = new Scanner(makeOptions("no-modal-site.html"));
+      const result = await scanner.run();
+      expect(result.compliance.grade).toBe("F");
+    });
+
+    it("raises a critical no-reject-button issue", async () => {
+      const scanner = new Scanner(makeOptions("no-modal-site.html"));
+      const result = await scanner.run();
+      const issue = result.compliance.issues.find(
+        (i) => i.type === "no-reject-button" && i.severity === "critical",
+      );
+      expect(issue).toBeDefined();
+    });
+  });
+});

package/tests/helpers/test-server.ts

@@ -0,0 +1,57 @@
+import { createServer } from "http";
+import { readFile } from "fs/promises";
+import { join, extname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const FIXTURES_DIR = join(__dirname, "../e2e/fixtures");
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+};
+
+export interface TestServer {
+  url: string;
+  close(): Promise<void>;
+}
+
+/**
+ * Starts a minimal HTTP server serving static HTML fixtures.
+ * Returns the base URL and a close() function.
+ */
+export async function startTestServer(port = 0): Promise<TestServer> {
+  const server = createServer(async (req, res) => {
+    const urlPath = req.url === "/" ? "/index.html" : (req.url ?? "/");
+    // Map /privacy-policy → privacy-policy.html or return a stub
+    const filePath = urlPath.endsWith(".html")
+      ? join(FIXTURES_DIR, urlPath)
+      : join(FIXTURES_DIR, `${urlPath.slice(1)}.html`);
+
+    try {
+      const content = await readFile(filePath);
+      const ext = extname(filePath) || ".html";
+      res.writeHead(200, { "Content-Type": MIME_TYPES[ext] ?? "text/plain" });
+      res.end(content);
+    } catch {
+      // Return a minimal stub for unknown paths (e.g., /privacy-policy)
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end("<!DOCTYPE html><html><body><h1>Privacy Policy</h1></body></html>");
+    }
+  });
+
+  await new Promise<void>((resolve) => server.listen(port, "127.0.0.1", resolve));
+
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    throw new Error("Unexpected server address type");
+  }
+
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    close: () =>
+      new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+  };
+}