feat: add authenticated route support via Playwright storageState

juancguerrerodev · claude · juancguerrerodev · commit 482ac91f222e · 2026-03-28T00:14:50.000-06:00
Captures pages behind login using Playwright's storageState:
- auth.storageState — default auth file for all routes
- auth.profiles — named profiles (admin, student, etc.) for role-based capture
- auth.routes — per-route profile mapping (null = anonymous)
- Routes grouped by auth profile to minimize browser context creation

Generate auth state: npx playwright codegen --save-storage=.dojowatch/auth.json
For CI, use a setup script (Supabase, Clerk, NextAuth) that saves state before capture.

Integration test verifies anonymous vs authenticated capture produce different screenshots.

46 tests passing.

Co-Authored-By: Claude Opus 4.6 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "dojowatch",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI-native visual regression testing engine by Dojo Coding — capture screenshots with Playwright, pre-filter with pixelmatch, and analyze UI changes with LLM vision. Zero incremental cost.",
   "owner": {
     "name": "Dojo Coding",
@@ -11,7 +11,7 @@
     {
       "name": "dojowatch",
       "description": "Visual regression testing powered by AI. Captures screenshots with Playwright, pre-filters with pixelmatch, and uses Claude (locally) or Gemini (in CI) to classify visual changes as regressions, intentional changes, or noise. Includes slash commands for interactive workflows and a CI orchestrator for GitHub Actions.",
-      "version": "0.4.0",
+      "version": "0.5.0",
       "author": {
         "name": "Dojo Coding",
         "email": "team@dojocoding.io"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "dojowatch",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "AI-native visual regression testing engine by Dojo Coding — capture screenshots with Playwright, pre-filter with pixelmatch, and analyze UI changes with LLM vision. Zero incremental cost.",
   "author": {
     "name": "Dojo Coding",
diff --git a/.gitignore b/.gitignore
@@ -7,6 +7,9 @@ dist/
 # DojoWatch runtime artifacts (captures and diffs are ephemeral)
 .dojowatch/captures/
 .dojowatch/diffs/
+.dojowatch/auth*.json
+.dojowatch/last-check.json
+.dojowatch/prefilter-report.json
 
 # Environment
 .env
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,6 +1,17 @@
 # Changelog
 
-## [0.4.0] — Unreleased
+## [0.5.0] — Unreleased
+
+### Added
+- **Authenticated route support**: Capture pages behind login using Playwright `storageState`
+  - `auth.storageState` — default auth file for all routes
+  - `auth.profiles` — named profiles (admin, student, etc.) mapping to different auth state files
+  - `auth.routes` — per-route profile assignment (null = anonymous)
+  - Routes grouped by auth profile to minimize browser context creation
+  - Generate auth state: `npx playwright codegen --save-storage=.dojowatch/auth.json`
+- Auth state files (`.dojowatch/auth*.json`) added to `.gitignore`
+
+## [0.4.0]
 
 ### Added
 - **Supabase data layer** (`scripts/supabase.ts`): Full Supabase integration for shared storage
diff --git a/README.md b/README.md
@@ -194,6 +194,35 @@ Add `data-vr-mask` to elements that change between captures — timestamps, avat
 
 DojoWatch replaces masked elements with solid placeholders before capture, preventing false positives.
 
+### Authenticated Routes
+
+Most apps have protected routes (dashboards, admin panels, settings). DojoWatch supports Playwright's `storageState` to capture these pages as a logged-in user:
+
+```json
+{
+  "auth": {
+    "storageState": ".dojowatch/auth.json",
+    "profiles": {
+      "admin": "e2e/.auth/admin.json",
+      "student": "e2e/.auth/student.json"
+    },
+    "routes": {
+      "/": null,
+      "/dashboard": "student",
+      "/admin": "admin"
+    }
+  }
+}
+```
+
+Generate an auth state file by logging in manually:
+
+```bash
+npx playwright codegen --save-storage=.dojowatch/auth.json http://localhost:3000
+```
+
+For CI, use a setup script that authenticates via your provider's API (Supabase, Clerk, Auth.js) and saves the state file before DojoWatch runs.
+
 ### Storybook Support
 
 Point `storybookUrl` at your Storybook instance. DojoWatch crawls `stories.json`, captures every story in isolation, and provides component-level regression detection — equivalent to Chromatic's core offering.
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "dojowatch",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/scripts/capture.ts b/scripts/capture.ts
@@ -6,7 +6,7 @@ import pc from "picocolors";
 import { injectStabilization, maskElements } from "./stabilize.js";
 import { loadConfig, findProjectRoot, getDojoWatchDir } from "./config.js";
 import { loadRouteMap, resolveScope } from "./route-map.js";
-import type { CaptureResult, DojoWatchConfig, Viewport } from "./types.js";
+import type { AuthConfig, CaptureResult, DojoWatchConfig, Viewport } from "./types.js";
 
 /**
  * Derive a filesystem-safe name from a route path.
@@ -69,8 +69,33 @@ async function captureRoute(
   };
 }
 
+/**
+ * Resolve which storageState file to use for a given route.
+ * Returns undefined for anonymous access.
+ */
+function resolveAuthForRoute(
+  route: string,
+  auth?: AuthConfig
+): string | undefined {
+  if (!auth) return undefined;
+
+  // Check per-route mapping first
+  if (auth.routes && route in auth.routes) {
+    const profileName = auth.routes[route];
+    if (profileName === null) return undefined; // explicitly anonymous
+    if (auth.profiles && profileName in auth.profiles) {
+      return auth.profiles[profileName];
+    }
+    return undefined;
+  }
+
+  // Fall back to default storageState
+  return auth.storageState;
+}
+
 /**
  * Capture all configured routes at all viewports.
+ * Supports authenticated captures via Playwright storageState.
  */
 export async function captureRoutes(
   config: DojoWatchConfig,
@@ -82,21 +107,39 @@ export async function captureRoutes(
   const browser = await chromium.launch({ headless: true });
   const results: CaptureResult[] = [];
 
+  // Group routes by auth profile to minimize context creation
+  const routesByAuth = new Map<string | undefined, string[]>();
+  for (const route of routes) {
+    const authFile = resolveAuthForRoute(route, config.auth);
+    const key = authFile ?? "__anonymous__";
+    if (!routesByAuth.has(key)) routesByAuth.set(key, []);
+    routesByAuth.get(key)!.push(route);
+  }
+
   try {
-    const context = await browser.newContext();
-    const page = await context.newPage();
+    for (const [authKey, groupedRoutes] of routesByAuth) {
+      const storageState = authKey === "__anonymous__" ? undefined : authKey;
+      const context = await browser.newContext(
+        storageState ? { storageState } : undefined
+      );
+      const page = await context.newPage();
+
+      if (storageState) {
+        console.log(pc.dim(`  Auth: ${storageState}`));
+      }
 
-    for (const route of routes) {
-      for (const viewport of config.viewports) {
-        console.log(
-          pc.dim(`  Capturing ${route} @ ${viewport.name} (${viewport.width}x${viewport.height})`)
-        );
-        const result = await captureRoute(page, config, route, viewport, outputDir);
-        results.push(result);
+      for (const route of groupedRoutes) {
+        for (const viewport of config.viewports) {
+          console.log(
+            pc.dim(`  Capturing ${route} @ ${viewport.name} (${viewport.width}x${viewport.height})`)
+          );
+          const result = await captureRoute(page, config, route, viewport, outputDir);
+          results.push(result);
+        }
       }
-    }
 
-    await context.close();
+      await context.close();
+    }
   } finally {
     await browser.close();
   }
diff --git a/scripts/config.ts b/scripts/config.ts
@@ -100,6 +100,13 @@ function mergeConfig(
       ...defaults.prefilter,
       ...overrides.prefilter,
     },
+    auth: overrides.auth
+      ? {
+          storageState: overrides.auth.storageState,
+          profiles: overrides.auth.profiles,
+          routes: overrides.auth.routes,
+        }
+      : undefined,
     supabase: overrides.supabase
       ? {
           url: overrides.supabase.url,
diff --git a/scripts/types.ts b/scripts/types.ts
@@ -26,6 +26,15 @@ export interface PrefilterConfig {
   clusterMinPixels: number;
 }
 
+export interface AuthConfig {
+  /** Default Playwright storageState file for authenticated captures. */
+  storageState?: string;
+  /** Named auth profiles mapping to storageState files (e.g., { "admin": "e2e/.auth/admin.json" }). */
+  profiles?: Record<string, string>;
+  /** Maps routes to profile names. null = anonymous (no auth). Unlisted routes use default storageState. */
+  routes?: Record<string, string | null>;
+}
+
 export interface SupabaseConfig {
   /** Supabase project URL. Read from env var in CI, .env.local locally. */
   url: string;
@@ -54,6 +63,8 @@ export interface DojoWatchConfig {
   engine: EngineConfig;
   /** Pre-filter configuration. */
   prefilter: PrefilterConfig;
+  /** Authentication configuration. Optional — when absent, captures run as anonymous. */
+  auth?: AuthConfig;
   /** Supabase configuration. Optional — when absent, local file storage is used. */
   supabase?: SupabaseConfig;
 }
diff --git a/skills/visual-regression/SKILL.md b/skills/visual-regression/SKILL.md
@@ -51,6 +51,39 @@ DojoWatch is configured via `.dojowatch/config.json`:
 - `/vr-report` — Generate markdown summary of last check
 - `/vr-watch` — File watcher with live re-capture (coming soon)
 
+## Authenticated Routes
+
+DojoWatch supports capturing pages behind authentication via Playwright's `storageState`:
+
+```json
+{
+  "auth": {
+    "storageState": ".dojowatch/auth.json",
+    "profiles": {
+      "admin": "e2e/.auth/admin.json",
+      "student": "e2e/.auth/student.json"
+    },
+    "routes": {
+      "/": null,
+      "/dashboard": "student",
+      "/admin": "admin"
+    }
+  }
+}
+```
+
+- **`storageState`** — default auth file for all routes (cookies + localStorage)
+- **`profiles`** — named profiles mapping to different auth state files
+- **`routes`** — per-route profile assignment. `null` = anonymous. Unlisted routes use the default.
+
+To generate an auth state file:
+```bash
+npx playwright codegen --save-storage=.dojowatch/auth.json http://localhost:3000
+```
+This opens a browser — log in manually, then close it. The session is saved.
+
+For automated CI, use a setup script that logs in via your auth provider's API (Supabase, Clerk, NextAuth) and saves the storageState file. See DojoOS's `e2e/global-setup.ts` for an example.
+
 ## File Structure
 - `.dojowatch/config.json` — Project configuration
 - `.dojowatch/routeMap.json` — Source file → route mapping
diff --git a/templates/config.example.json b/templates/config.example.json
@@ -26,6 +26,18 @@
       "apiKeyEnv": "GOOGLE_GENAI_API_KEY"
     }
   },
+  "auth": {
+    "storageState": ".dojowatch/auth.json",
+    "profiles": {
+      "admin": "e2e/.auth/admin.json",
+      "student": "e2e/.auth/student.json"
+    },
+    "routes": {
+      "/": null,
+      "/dashboard": "student",
+      "/admin": "admin"
+    }
+  },
   "prefilter": {
     "threshold": 0.05,
     "clusterMinPixels": 500
diff --git a/tests/integration.test.ts b/tests/integration.test.ts
@@ -189,3 +189,102 @@ describe("DojoWatch integration pipeline", () => {
     expect(markdown).toContain("Intentional changes");
   });
 });
+
+describe("DojoWatch auth support", () => {
+  const AUTH_TEST_DIR = join(import.meta.dirname, ".tmp-auth-test");
+  const AUTH_PORT = 9879;
+  let authServer: Server;
+
+  const PROTECTED_HTML = `<!DOCTYPE html><html><body>
+    <h1 id="status">Please log in</h1>
+    <script>
+      if (document.cookie.includes('session=authenticated')) {
+        document.getElementById('status').textContent = 'Welcome, authenticated user!';
+      }
+    </script>
+  </body></html>`;
+
+  const authConfig: DojoWatchConfig = {
+    project: "auth-test",
+    baseUrl: `http://localhost:${AUTH_PORT}`,
+    viewports: [{ name: "desktop", width: 800, height: 600 }],
+    routes: ["/"],
+    maskSelectors: [],
+    engine: {
+      local: { model: "claude" },
+      ci: { model: "gemini", apiKeyEnv: "KEY" },
+    },
+    prefilter: { threshold: 0.05, clusterMinPixels: 500 },
+  };
+
+  beforeAll(async () => {
+    mkdirSync(join(AUTH_TEST_DIR, ".dojowatch"), { recursive: true });
+    writeFileSync(
+      join(AUTH_TEST_DIR, ".dojowatch", "config.json"),
+      JSON.stringify(authConfig)
+    );
+
+    authServer = createServer((_req, res) => {
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(PROTECTED_HTML);
+    });
+
+    await new Promise<void>((resolve) => {
+      authServer.listen(AUTH_PORT, resolve);
+    });
+  });
+
+  afterAll(async () => {
+    await new Promise<void>((resolve) => {
+      authServer.close(() => resolve());
+    });
+    rmSync(AUTH_TEST_DIR, { recursive: true, force: true });
+  });
+
+  it("captures anonymous page when no auth is configured", async () => {
+    const capturesDir = join(AUTH_TEST_DIR, ".dojowatch", "captures");
+    const results = await captureRoutes(authConfig, ["/"], capturesDir);
+
+    expect(results).toHaveLength(1);
+    expect(existsSync(results[0].path)).toBe(true);
+  });
+
+  it("captures authenticated page when storageState provides session cookie", async () => {
+    // Create a storageState file with the session cookie
+    const storageState = {
+      cookies: [
+        {
+          name: "session",
+          value: "authenticated",
+          domain: "localhost",
+          path: "/",
+          expires: -1,
+          httpOnly: false,
+          secure: false,
+          sameSite: "Lax" as const,
+        },
+      ],
+      origins: [],
+    };
+
+    const authStatePath = join(AUTH_TEST_DIR, ".dojowatch", "auth.json");
+    writeFileSync(authStatePath, JSON.stringify(storageState));
+
+    // Capture with auth
+    const configWithAuth: DojoWatchConfig = {
+      ...authConfig,
+      auth: { storageState: authStatePath },
+    };
+    const capturesDir = join(AUTH_TEST_DIR, ".dojowatch", "captures-auth");
+    const results = await captureRoutes(configWithAuth, ["/"], capturesDir);
+
+    expect(results).toHaveLength(1);
+    expect(existsSync(results[0].path)).toBe(true);
+
+    // The hashes should differ — anonymous vs authenticated show different content
+    const anonDir = join(AUTH_TEST_DIR, ".dojowatch", "captures");
+    const anonCaptures = await captureRoutes(authConfig, ["/"], anonDir);
+
+    expect(results[0].hash).not.toBe(anonCaptures[0].hash);
+  });
+});

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "dojowatch",`
`3`		`- "version": "0.4.0",`
	`3`	`+ "version": "0.5.0",`
`4`	`4`	`"description": "AI-native visual regression testing engine by Dojo Coding — capture screenshots with Playwright, pre-filter with pixelmatch, and analyze UI changes with LLM vision. Zero incremental cost.",`
`5`	`5`	`"author": {`
`6`	`6`	`"name": "Dojo Coding",`