playwright-toolbox 1.0.0

package/packages/playwright-history-dashboard/package-lock.json

@@ -0,0 +1,105 @@
+{
+  "name": "@acahet/playwright-history-dashboard",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "@acahet/playwright-history-dashboard",
+      "version": "1.0.0",
+      "license": "MIT",
+      "bin": {
+        "pw-history-init": "dist/scripts/init.js"
+      },
+      "devDependencies": {
+        "@playwright/test": "^1.50.0",
+        "typescript": "^5.4.0"
+      },
+      "peerDependencies": {
+        "@playwright/test": ">=1.40.0"
+      },
+      "peerDependenciesMeta": {
+        "@playwright/test": {
+          "optional": false
+        }
+      }
+    },
+    "node_modules/@playwright/test": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.58.2.tgz",
+      "integrity": "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.58.2"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/fsevents": {
+      "version": "2.3.2",
+      "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz",
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": "^8.16.0 || ^10.6.0 || >=11.0.0"
+      }
+    },
+    "node_modules/playwright": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.58.2.tgz",
+      "integrity": "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.58.2"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "fsevents": "2.3.2"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.58.2",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.58.2.tgz",
+      "integrity": "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/typescript": {
+      "version": "5.9.3",
+      "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz",
+      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "tsc": "bin/tsc",
+        "tsserver": "bin/tsserver"
+      },
+      "engines": {
+        "node": ">=14.17"
+      }
+    }
+  }
+}

package/packages/playwright-history-dashboard/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@acahet/playwright-history-dashboard",
+  "version": "2.0.0",
+  "description": "Self-hosted Playwright test history dashboard — custom reporter + single-file HTML dashboard. No SaaS, no subscriptions.",
+  "keywords": [
+    "playwright",
+    "playwright-reporter",
+    "test-history",
+    "test-automation",
+    "dashboard",
+    "testing",
+    "typescript"
+  ],
+  "homepage": "https://github.com/acahet-automation-org/playwright-toolbox#readme",
+  "bugs": {
+    "url": "https://github.com/acahet-automation-org/playwright-toolbox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/acahet-automation-org/playwright-toolbox.git",
+    "directory": "packages/playwright-history-dashboard"
+  },
+  "license": "MIT",
+  "author": "acahet",
+  "type": "module",
+  "exports": {
+    "./reporter": {
+      "import": "./dist/src/reporter.js",
+      "types": "./dist/src/reporter.d.ts"
+    }
+  },
+  "bin": {
+    "pw-history-init": "./dist/scripts/init.js"
+  },
+  "files": [
+    "dist/",
+    "dashboard/"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "build:watch": "tsc --project tsconfig.json --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.0",
+    "typescript": "^5.4.0"
+  }
+}

package/packages/playwright-history-dashboard/pw-dashboard.config.js

@@ -0,0 +1,22 @@
+// pw-dashboard.config.js
+// Copy this file to your project root and rename it to pw-dashboard.config.js
+// Then run: npx pw-history-init
+//
+// All fields are optional — omit any you don't want to override.
+
+module.exports = {
+	// Your project name — shown in the topbar and footer
+	projectName: 'My Project',
+
+	// Top-left brand label
+	brandName: 'pw_dashboard',
+
+	// Browser tab title
+	pageTitle: 'Test History Dashboard',
+
+	// Where the reporter writes history (must match historyDir in playwright.config.ts)
+	historyDir: 'tests/report/test-history',
+
+	// Path to history-index.json relative to index.html (rarely needs changing)
+	historyIndexPath: 'history-index.json',
+};

package/packages/playwright-history-dashboard/scripts/init.ts

@@ -0,0 +1,95 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface DashboardConfig {
+	projectName?: string;
+	brandName?: string;
+	pageTitle?: string;
+	historyIndexPath?: string;
+	emptyTitle?: string;
+	emptyMessage?: string;
+	errorTitle?: string;
+	errorMessage?: string;
+	historyDir?: string;
+}
+
+// Defaults — used when the consumer hasn't overridden a value
+const DEFAULTS: Required<DashboardConfig> = {
+	projectName: '',
+	brandName: 'pw_dashboard',
+	pageTitle: 'Test History Dashboard',
+	historyIndexPath: 'history-index.json',
+	emptyTitle: 'No test history yet',
+	emptyMessage: 'Run your tests to start tracking history.',
+	errorTitle: 'Could not load history',
+	errorMessage: 'Make sure history-index.json is in the same directory.',
+	historyDir: 'tests/report/test-history',
+};
+
+function loadConsumerConfig(): DashboardConfig {
+	const configPath = path.resolve(process.cwd(), 'pw-dashboard.config.js');
+	if (fs.existsSync(configPath)) {
+		try {
+			const cfg = require(configPath) as DashboardConfig;
+			console.log(
+				`\nFound pw-dashboard.config.js — applying your settings.`,
+			);
+			return cfg;
+		} catch (err) {
+			console.warn(
+				`\nWarning: could not read pw-dashboard.config.js — using defaults.\n${String(err)}`,
+			);
+		}
+	}
+	return {};
+}
+
+function injectConfig(html: string, cfg: Required<DashboardConfig>): string {
+	const configBlock = `const CONFIG = {
+  pageTitle:        ${JSON.stringify(cfg.pageTitle)},
+  projectName:      ${JSON.stringify(cfg.projectName)},
+  brandName:        ${JSON.stringify(cfg.brandName)},
+  historyIndexPath: ${JSON.stringify(cfg.historyIndexPath)},
+  emptyTitle:       ${JSON.stringify(cfg.emptyTitle)},
+  emptyMessage:     ${JSON.stringify(cfg.emptyMessage)},
+  errorTitle:       ${JSON.stringify(cfg.errorTitle)},
+  errorMessage:     ${JSON.stringify(cfg.errorMessage)},
+};`;
+
+	// Replace the entire CONFIG block between the banner comments
+	return html.replace(
+		/\/\/ ─+\n\/\/ CONFIG[\s\S]*?\/\/ ─+/,
+		`// ─────────────────────────────────────────────────────────────────────────────\n// CONFIG — generated by pw-history-init · edit pw-dashboard.config.js to change\n// ─────────────────────────────────────────────────────────────────────────────\n${configBlock}\n// ─────────────────────────────────────────────────────────────────────────────`,
+	);
+}
+
+function main() {
+	const consumerCfg = loadConsumerConfig();
+	const cfg: Required<DashboardConfig> = { ...DEFAULTS, ...consumerCfg };
+
+	const src = path.resolve(__dirname, '../dashboard/index.html');
+	const destDir = path.resolve(process.cwd(), cfg.historyDir);
+	const dest = path.join(destDir, 'index.html');
+
+	if (!fs.existsSync(destDir)) {
+		fs.mkdirSync(destDir, { recursive: true });
+	}
+
+	const template = fs.readFileSync(src, 'utf-8');
+	const output = injectConfig(template, cfg);
+
+	fs.writeFileSync(dest, output, 'utf-8');
+
+	console.log(`\n✓ Dashboard written to:\n  ${dest}\n`);
+	if (!consumerCfg.projectName) {
+		console.log(
+			`Tip: create pw-dashboard.config.js in your project root to set your project name:\n`,
+		);
+		console.log(`  module.exports = {`);
+		console.log(`    projectName: 'Your Project Name',`);
+		console.log(`  };\n`);
+	}
+	console.log(`Serve with: npx serve ${cfg.historyDir}\n`);
+}
+
+main();

package/packages/playwright-history-dashboard/src/reporter.ts

@@ -0,0 +1,376 @@
+import { promises as fs } from 'node:fs';
+import * as path from 'node:path';
+import type {
+	FullConfig,
+	FullResult,
+	Reporter,
+	Suite,
+	TestCase,
+	TestResult,
+} from '@playwright/test/reporter';
+
+interface Annotation {
+	type: string;
+	description?: string;
+}
+
+interface TestInfo {
+	title: string;
+	file: string;
+	project: string;
+	duration: number;
+	status: string;
+	error?: string;
+	tags?: string[];
+	annotations?: Annotation[];
+	artifacts: {
+		trace?: string;
+		screenshot?: string;
+	};
+}
+
+interface TestHistoryEntry {
+	runId: string;
+	timestamp: string;
+	duration: number;
+	totalTests: number;
+	passed: number;
+	failed: number;
+	skipped: number;
+	flaky: number;
+	allTests: TestInfo[];
+	failedTests: TestInfo[];
+}
+
+interface HistoryIndex {
+	runs: TestHistoryEntry[];
+}
+
+// How many runs to keep in the index AND on disk — overridable via options
+const DEFAULT_MAX_RUNS = 30;
+
+interface ReporterOptions {
+	historyDir?: string;
+	maxRuns?: number;
+}
+
+class LocalHistoryReporter implements Reporter {
+	private config!: FullConfig;
+	private suite!: Suite;
+	private startTime!: number;
+	private historyDir: string;
+	private historyIndexFile: string;
+	private maxRuns: number;
+	private currentRunId!: string;
+	private currentRunDir!: string;
+
+	constructor(options: ReporterOptions = {}) {
+		this.historyDir = options.historyDir ?? './tests/report/test-history';
+		this.maxRuns = options.maxRuns ?? DEFAULT_MAX_RUNS;
+		this.historyIndexFile = `${this.historyDir}/history-index.json`;
+	}
+
+	async onBegin(config: FullConfig, suite: Suite) {
+		this.config = config;
+		this.suite = suite;
+		this.startTime = Date.now();
+		this.currentRunId = new Date().toISOString().replace(/[:.]/g, '-');
+		this.currentRunDir = `${this.historyDir}/runs/${this.currentRunId}`;
+
+		await fs.mkdir(this.currentRunDir, { recursive: true });
+	}
+
+	async onEnd(_result: FullResult) {
+		try {
+			const duration = Date.now() - this.startTime;
+			const stats = this.collectTestStats(this.suite);
+
+			await this.copyFailureArtifacts(stats.failedTests);
+
+			const historyEntry: TestHistoryEntry = {
+				runId: this.currentRunId,
+				timestamp: new Date().toISOString(),
+				duration,
+				totalTests: stats.total,
+				passed: stats.passed,
+				failed: stats.failed,
+				skipped: stats.skipped,
+				flaky: stats.flaky,
+				allTests: stats.allTests,
+				failedTests: stats.failedTests,
+			};
+
+			await this.updateHistoryIndex(historyEntry);
+
+			// Cleanup is driven by the index: runs evicted from the index get their
+			// directories deleted. No separate time-based policy — one source of truth.
+			await this.cleanupOrphanedRunDirs();
+		} catch (err) {
+			process.stderr.write(
+				`[LocalHistoryReporter] Failed to save history: ${String(err)}\n`,
+			);
+		}
+	}
+
+	// ─── Stats collection ────────────────────────────────────────────────────
+
+	private collectTestStats(suite: Suite) {
+		let total = 0;
+		let passed = 0;
+		let failed = 0;
+		let skipped = 0;
+		let flaky = 0;
+		const allTests: TestInfo[] = [];
+		const failedTests: TestInfo[] = [];
+
+		const processSuite = (s: Suite) => {
+			for (const test of s.tests) {
+				// Skip setup project tests — they're infrastructure, not results
+				if (test.parent?.project()?.name === 'setup') {
+					continue;
+				}
+
+				total++;
+
+				const results = test.results;
+
+				if (results.length === 0) {
+					skipped++;
+					allTests.push(this.createTestEntry(test, null, 'skipped'));
+					continue;
+				}
+
+				const lastResult = results[results.length - 1];
+
+				if (lastResult.status === 'skipped') {
+					skipped++;
+					allTests.push(
+						this.createTestEntry(test, lastResult, 'skipped'),
+					);
+				} else if (lastResult.status === 'passed') {
+					// Flaky = passed on a retry (at least one earlier attempt failed)
+					const isFlaky =
+						results.length > 1 &&
+						results.some((r) => r.status !== 'passed');
+					if (isFlaky) {
+						flaky++;
+					}
+					passed++;
+					allTests.push(
+						this.createTestEntry(
+							test,
+							lastResult,
+							isFlaky ? 'flaky' : 'passed',
+						),
+					);
+				} else {
+					failed++;
+					const entry = this.createTestEntry(
+						test,
+						lastResult,
+						'failed',
+					);
+					failedTests.push(entry);
+					allTests.push(entry);
+				}
+			}
+
+			for (const child of s.suites) {
+				processSuite(child);
+			}
+		};
+
+		processSuite(suite);
+
+		return { total, passed, failed, skipped, flaky, allTests, failedTests };
+	}
+
+	private createTestEntry(
+		test: TestCase,
+		result: TestResult | null,
+		status: string,
+	): TestInfo {
+		return {
+			title: test.title,
+			file: path.relative(process.cwd(), test.location.file),
+			project: test.parent?.project()?.name ?? 'unknown',
+			duration: result?.duration ?? 0,
+			status,
+			error: result?.error?.message,
+			tags: test.tags.length > 0 ? test.tags : undefined,
+			// Playwright annotations: test.info().annotations or test.annotations
+			annotations:
+				test.annotations.length > 0 ? test.annotations : undefined,
+			artifacts: {},
+		};
+	}
+
+	// ─── Artifact copying ────────────────────────────────────────────────────
+
+	/**
+	 * Copies trace and screenshot for each failed test by looking inside the
+	 * test-specific output folder Playwright creates, rather than scanning the
+	 * entire project outputDir. This prevents one test from overwriting another's
+	 * artifacts when multiple tests fail in the same project.
+	 *
+	 * Playwright names the folder:
+	 *   test-results/<sanitized-test-title>-<project>/
+	 */
+	private async copyFailureArtifacts(failedTests: TestInfo[]) {
+		for (const failedTest of failedTests) {
+			try {
+				const testOutputDir = this.resolveTestOutputDir(failedTest);
+
+				let files: string[];
+				try {
+					const entries = await fs.readdir(testOutputDir, {
+						recursive: true,
+					});
+					files = entries.map((e) => e.toString());
+				} catch {
+					// Test output directory doesn't exist — no artifacts to copy
+					continue;
+				}
+
+				for (const file of files) {
+					const srcPath = path.join(testOutputDir, file);
+
+					let stat: Awaited<ReturnType<typeof fs.stat>>;
+					try {
+						stat = await fs.stat(srcPath);
+					} catch {
+						continue;
+					}
+					if (!stat.isFile()) continue;
+
+					const baseName = this.sanitizeFilename(failedTest.title);
+
+					if (file.endsWith('trace.zip')) {
+						const destPath = path.join(
+							this.currentRunDir,
+							`${baseName}-trace.zip`,
+						);
+						await fs.copyFile(srcPath, destPath);
+						failedTest.artifacts.trace = path.relative(
+							this.historyDir,
+							destPath,
+						);
+					} else if (
+						/\.(png|jpg|jpeg)$/i.test(file) &&
+						file.includes('screenshot')
+					) {
+						const destPath = path.join(
+							this.currentRunDir,
+							`${baseName}-screenshot.png`,
+						);
+						await fs.copyFile(srcPath, destPath);
+						failedTest.artifacts.screenshot = path.relative(
+							this.historyDir,
+							destPath,
+						);
+					}
+				}
+			} catch (err) {
+				process.stderr.write(
+					`[LocalHistoryReporter] Failed to copy artifacts for "${failedTest.title}": ${String(err)}\n`,
+				);
+			}
+		}
+	}
+
+	/**
+	 * Resolves the Playwright-generated output folder for a specific test.
+	 * Playwright convention: test-results/{title-slug}-{project}/
+	 * Falls back to the project's configured outputDir if no match is found.
+	 */
+	private resolveTestOutputDir(test: TestInfo): string {
+		const slug = test.title
+			.replace(/\W+/g, '-')
+			.replace(/^-+|-+$/g, '')
+			.toLowerCase();
+
+		const projectSlug = test.project.toLowerCase();
+
+		// Standard Playwright output dir layout
+		return path.join('test-results', `${slug}-${projectSlug}`);
+	}
+
+	private sanitizeFilename(filename: string): string {
+		return filename.replace(/[^a-z0-9]/gi, '_').toLowerCase();
+	}
+
+	// ─── History index management ────────────────────────────────────────────
+
+	private async updateHistoryIndex(entry: TestHistoryEntry) {
+		let historyIndex: HistoryIndex;
+
+		try {
+			const content = await fs.readFile(this.historyIndexFile, 'utf-8');
+			historyIndex = JSON.parse(content) as HistoryIndex;
+		} catch {
+			historyIndex = { runs: [] };
+		}
+
+		historyIndex.runs.unshift(entry);
+
+		// Evict runs beyond the cap — collect their IDs before trimming
+		const evictedRunIds = historyIndex.runs
+			.slice(this.maxRuns)
+			.map((r) => r.runId);
+
+		historyIndex.runs = historyIndex.runs.slice(0, this.maxRuns);
+
+		await fs.writeFile(
+			this.historyIndexFile,
+			JSON.stringify(historyIndex, null, 2),
+		);
+
+		// Delete directories for evicted runs immediately — index and disk stay in sync
+		for (const runId of evictedRunIds) {
+			await this.deleteRunDir(runId);
+		}
+	}
+
+	/**
+	 * Removes run directories that exist on disk but are no longer referenced
+	 * by the index. Guards against orphans left by earlier bugs or manual edits.
+	 */
+	private async cleanupOrphanedRunDirs() {
+		const runsBaseDir = path.join(this.historyDir, 'runs');
+
+		let existingDirs: string[];
+		try {
+			existingDirs = await fs.readdir(runsBaseDir);
+		} catch {
+			return; // runs/ dir doesn't exist yet — nothing to clean
+		}
+
+		let indexedRunIds: Set<string>;
+		try {
+			const content = await fs.readFile(this.historyIndexFile, 'utf-8');
+			const index = JSON.parse(content) as HistoryIndex;
+			indexedRunIds = new Set(index.runs.map((r) => r.runId));
+		} catch {
+			return; // can't read index — don't delete anything
+		}
+
+		for (const dir of existingDirs) {
+			if (!indexedRunIds.has(dir)) {
+				await this.deleteRunDir(dir);
+			}
+		}
+	}
+
+	private async deleteRunDir(runId: string) {
+		const runDir = path.join(this.historyDir, 'runs', runId);
+		try {
+			await fs.rm(runDir, { recursive: true, force: true });
+		} catch (err) {
+			process.stderr.write(
+				`[LocalHistoryReporter] Failed to delete run dir "${runDir}": ${String(err)}\n`,
+			);
+		}
+	}
+}
+
+export default LocalHistoryReporter;

package/packages/playwright-history-dashboard/tsconfig.json

@@ -0,0 +1,19 @@
+{
+	"compilerOptions": {
+		"target": "ES2020",
+		"module": "NodeNext",
+		"moduleResolution": "NodeNext",
+		"lib": ["ES2020"],
+		"outDir": "./dist",
+		"rootDir": "./",
+		"declaration": true,
+		"declarationMap": true,
+		"sourceMap": true,
+		"strict": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true
+	},
+	"include": ["src/**/*", "scripts/**/*"],
+	"exclude": ["node_modules", "dist"]
+}

package/packages/pw-standard/.eslintrc.js

@@ -0,0 +1,23 @@
+/** @type {import('eslint').Linter.Config} */
+module.exports = {
+    root: true,
+    parser: '@typescript-eslint/parser',
+    parserOptions: {
+        ecmaVersion: 2020,
+        sourceType: 'module',
+        project: './tsconfig.json',
+    },
+    plugins: ['@typescript-eslint'],
+    extends: [
+        'eslint:recommended',
+        'plugin:@typescript-eslint/recommended',
+    ],
+    env: {
+        node: true,
+        es2020: true,
+    },
+    rules: {
+        '@typescript-eslint/no-explicit-any': 'warn',
+        '@typescript-eslint/explicit-module-boundary-types': 'off',
+    },
+};