feat: implement unified Playwright E2E testing for /run page with CI integration

- Add Playwright configuration and environment-aware settings in frontend/playwright.config.ts
- Create initial E2E tests in frontend/tests/e2e/run-page.spec.ts to verify Run Timeline visibility
- Integrate E2E tests into the Husky pre-push hook for automated verification
- Update package.json scripts for E2E testing and add necessary dependencies
- Enhance documentation to reflect new testing strategy and implementation details

Author: nirukk52

.DS_Store

@@ -1,6 +1,6 @@
 #!/bin/sh
 # Husky pre-push hook
-# Runs smoke tests before allowing push
+# Runs smoke tests + E2E tests before allowing push
 
 echo "🧪 Running smoke tests before push (bun run qa:smoke)..."
 echo ""
@@ -9,5 +9,12 @@ echo ""
 bun run qa:smoke || exit 1
 
 echo ""
-echo "✅ All smoke tests passed - proceeding with push"
+echo "🎭 Running E2E tests before push (bun run test:e2e:ci)..."
+echo ""
+
+# Run E2E tests in headless CI mode
+bun run test:e2e:ci || exit 1
+
+echo ""
+echo "✅ All smoke tests and E2E tests passed - proceeding with push"
 

.husky/pre-push

@@ -12,7 +12,11 @@
     "format": "bunx biome format --write .",
     "format:check": "bunx biome format --write=false .",
     "lint": "bunx biome lint .",
-    "lint:fix": "bunx biome lint --apply ."
+    "lint:fix": "bunx biome lint --apply .",
+    "test:e2e": "playwright test",
+    "test:e2e:headed": "HEADLESS=false playwright test",
+    "test:e2e:ci": "HEADLESS=true playwright test",
+    "test:e2e:ui": "playwright test --ui"
   },
   "dependencies": {
     "@formkit/auto-animate": "^0.8.2",
@@ -24,6 +28,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "1.9.2",
+    "@playwright/test": "^1.48.0",
     "@skeletonlabs/skeleton": "^4.2.4",
     "@skeletonlabs/skeleton-svelte": "^4.2.4",
     "@sveltejs/adapter-vercel": "^4.0.0",

frontend/package.json

@@ -0,0 +1,79 @@
+import { defineConfig, devices } from "@playwright/test";
+import { resolve, dirname } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** Get __dirname equivalent in ES modules */
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/** Load .env file manually to ensure test environment matches app environment */
+const envPath = resolve(__dirname, "../.env");
+try {
+	const envFile = readFileSync(envPath, "utf-8");
+	for (const line of envFile.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) continue;
+		const [key, ...valueParts] = trimmed.split("=");
+		if (key && valueParts.length > 0) {
+			process.env[key] = valueParts.join("=");
+		}
+	}
+} catch (error) {
+	console.warn("⚠️  Could not load .env file, using defaults");
+}
+
+/** Detect CI environment (GitHub Actions, GitLab CI, etc.) */
+const CI = !!process.env.CI;
+
+/** Control headless mode - defaults to true, can be overridden with HEADLESS=false */
+const HEADLESS = process.env.HEADLESS !== "false";
+
+/** Frontend URL - defaults to standard port from .env */
+const FRONTEND_URL = process.env.FRONTEND_URL || "http://localhost:5173";
+
+/**
+ * Playwright configuration for ScreenGraph frontend E2E tests.
+ * 
+ * Environment-aware setup:
+ * - Local dev: headed mode with slowMo for debugging
+ * - CI: headless, retries enabled, video on failure
+ * - Test package from .env: VITE_PACKAGE_NAME
+ */
+export default defineConfig({
+	testDir: "./tests/e2e",
+	fullyParallel: false, // Run tests sequentially for stability
+	forbidOnly: CI, // Prevent .only() in CI
+	retries: CI ? 2 : 0, // Retry flaky tests in CI only
+	workers: 1, // Single worker for now
+	reporter: CI ? "github" : "list",
+
+	use: {
+		baseURL: FRONTEND_URL,
+		headless: HEADLESS,
+		trace: "on-first-retry",
+		video: CI ? "retain-on-failure" : "off",
+		screenshot: "only-on-failure",
+		
+		// Slow motion in local dev for visual debugging
+		launchOptions: {
+			slowMo: CI ? 0 : 150,
+		},
+	},
+
+	projects: [
+		{
+			name: "chromium",
+			use: { ...devices["Desktop Chrome"] },
+		},
+	],
+
+	// Auto-start frontend if not running (optional)
+	webServer: {
+		command: "bun run dev",
+		url: FRONTEND_URL,
+		reuseExistingServer: true,
+		timeout: 120_000,
+	},
+});
+

frontend/playwright.config.ts

@@ -0,0 +1,129 @@
+import type { Page } from "@playwright/test";
+
+/**
+ * Reusable Playwright helper utilities for ScreenGraph E2E tests.
+ * 
+ * Provides consistent patterns for:
+ * - Waiting for elements
+ * - Safe interactions
+ * - Common navigation patterns
+ * 
+ * All tests use configuration from .env file for consistency.
+ */
+
+/** 
+ * Test package name from .env - the main key for all E2E tests.
+ * Defaults to com.example.testapp if not set in environment.
+ */
+export const TEST_PACKAGE_NAME = process.env.VITE_PACKAGE_NAME || "com.example.testapp";
+
+/** 
+ * Test app configuration from .env for consistent E2E testing.
+ * All tests run against the same package defined in .env.
+ */
+export const TEST_APP_CONFIG = {
+	packageName: process.env.VITE_PACKAGE_NAME || "com.example.testapp",
+	appActivity: process.env.VITE_APP_ACTIVITY || "com.example.testapp.MainActivity",
+	apkPath: process.env.VITE_APK_PATH || "/path/to/test.apk",
+	appiumServerUrl: process.env.VITE_APPIUM_SERVER_URL || "http://localhost:4723",
+};
+
+/**
+ * Wait for a specific text to appear on the page.
+ * Useful for waiting on dynamic content or SSE events.
+ */
+export async function waitForText(
+	page: Page,
+	text: string | RegExp,
+	options?: { timeout?: number },
+): Promise<void> {
+	const timeout = options?.timeout ?? 30000;
+	await page.waitForSelector(`text=${text}`, { timeout });
+}
+
+/**
+ * Start a run from the landing page and wait for navigation to /run.
+ * Returns the run ID extracted from the URL.
+ * 
+ * NOTE: Uses TEST_PACKAGE_NAME from .env for consistency.
+ */
+export async function startRunFromLanding(page: Page): Promise<string> {
+	// Navigate to landing page
+	await page.goto("/");
+
+	// Click "Detect My First Drift" button
+	const runButton = page.getByRole("button", { name: /detect.*drift/i });
+	await runButton.click();
+
+	// Wait for navigation to /run page
+	await page.waitForURL(/\/run\/([a-f0-9-]+)/i, {
+		waitUntil: "domcontentloaded",
+		timeout: 30000,
+	});
+
+	// Extract run ID from URL
+	const url = page.url();
+	const match = url.match(/\/run\/([a-f0-9-]+)/i);
+	if (!match) {
+		throw new Error("Failed to extract run ID from URL");
+	}
+
+	return match[1];
+}
+
+/**
+ * Wait for a graph event to appear in the timeline.
+ * Requires data-testid or data-event attributes on timeline entries.
+ */
+export async function waitForGraphEvent(
+	page: Page,
+	eventName: string,
+	options?: { timeout?: number },
+): Promise<void> {
+	const timeout = options?.timeout ?? 45000;
+	await page.waitForSelector(`[data-event="${eventName}"]`, { timeout });
+}
+
+/**
+ * Capture console errors during test execution.
+ * Returns an array of error messages.
+ */
+export function captureConsoleErrors(page: Page): string[] {
+	const errors: string[] = [];
+
+	page.on("console", (msg) => {
+		if (msg.type() === "error") {
+			errors.push(msg.text());
+		}
+	});
+
+	page.on("pageerror", (error) => {
+		errors.push(error.message);
+	});
+
+	return errors;
+}
+
+/**
+ * Wait for the stop node to appear in the run timeline.
+ * Indicates the run has completed successfully.
+ */
+export async function waitForStopNode(
+	page: Page,
+	options?: { timeout?: number },
+): Promise<void> {
+	const timeout = options?.timeout ?? 60000;
+	await page.waitForSelector('[data-run-state="stopped"]', { timeout });
+}
+
+/**
+ * Count discovered screenshots in the gallery.
+ * Returns the number of screenshot images rendered.
+ */
+export async function countDiscoveredScreenshots(page: Page): Promise<number> {
+	const screenGallery = page.locator(
+		'[data-testid="discovered-screens"] img',
+	);
+	return await screenGallery.count();
+}
+

frontend/tests/e2e/helpers.ts

@@ -0,0 +1,92 @@
+import { test, expect } from "@playwright/test";
+import { TEST_PACKAGE_NAME, TEST_APP_CONFIG } from "./helpers";
+
+/**
+ * /run page E2E regression suite
+ * 
+ * Verifies core functionality:
+ * - Run page loads after starting a run
+ * - Run Timeline header is visible
+ * 
+ * Prerequisites:
+ * - Backend and frontend services running
+ * - Test package from .env: ${TEST_PACKAGE_NAME}
+ * - All tests use the same package for consistency
+ */
+test.describe("/run page smoke tests", () => {
+	test.beforeAll(() => {
+		// Log test configuration from .env
+		console.log("🎯 E2E Test Configuration:");
+		console.log(`  Package: ${TEST_APP_CONFIG.packageName}`);
+		console.log(`  Activity: ${TEST_APP_CONFIG.appActivity}`);
+		console.log(`  Appium: ${TEST_APP_CONFIG.appiumServerUrl}`);
+	});
+
+	/**
+	 * Verify run page opens and displays Run Timeline header.
+	 * This is the baseline test for detecting UI regressions.
+	 * 
+	 * NOTE: Requires backend to be running and able to start runs.
+	 * Uses package from .env: ${TEST_PACKAGE_NAME}
+	 */
+	test("should open run page and show Run Timeline text", async ({ page }) => {
+		// Navigate to landing page
+		await page.goto("/");
+		
+		// Wait for page to fully load
+		await expect(page).toHaveTitle(/ScreenGraph/i);
+		
+		// Find and click the "Detect My First Drift" button
+		// Using getByRole for accessibility-friendly selection
+		const runButton = page.getByRole("button", { name: /detect.*drift/i });
+		await expect(runButton).toBeVisible();
+		
+		// Click the button - this will call the backend API and navigate
+		await runButton.click();
+		
+		// Wait for navigation to /run page (increased timeout for API call + navigation)
+		await page.waitForURL(/\/run\/[a-f0-9-]+/i, { 
+			waitUntil: "domcontentloaded",
+			timeout: 30000 
+		});
+		
+		// Verify Run Timeline text is visible in the H1 heading
+		// This is the key regression check - if timeline UI breaks, this will fail
+		// Use getByRole to be specific and avoid strict mode violations
+		const timelineHeading = page.getByRole("heading", { name: /run timeline/i });
+		await expect(timelineHeading).toBeVisible({ timeout: 10000 });
+		
+		// Verify Cancel Run button exists (indicates page fully loaded)
+		const cancelButton = page.getByRole("button", { name: /cancel run/i });
+		await expect(cancelButton).toBeVisible();
+	});
+
+	/**
+	 * Verify landing page loads correctly before testing run flow.
+	 * This is a sanity check to ensure frontend is healthy.
+	 */
+	test("should load landing page successfully", async ({ page }) => {
+		await page.goto("/");
+		
+		// Verify page title
+		await expect(page).toHaveTitle(/ScreenGraph/i);
+		
+		// Verify the main CTA button exists
+		const runButton = page.getByRole("button", { name: /detect.*drift/i });
+		await expect(runButton).toBeVisible();
+		
+		// Verify no console errors on load
+		const consoleErrors: string[] = [];
+		page.on("console", (msg) => {
+			if (msg.type() === "error") {
+				consoleErrors.push(msg.text());
+			}
+		});
+		
+		await page.waitForTimeout(1000);
+		
+		// Assert no console errors
+		expect(consoleErrors).toHaveLength(0);
+	});
+});
+