performance tests

Author: jessehattabaugh

README.md

@@ -16,6 +16,7 @@ This boilerplate includes modern web features:
 -   ♿ Accessibility features including prefers-reduced-motion support
 -   🔍 SEO optimized
 -   🧪 End-to-end testing with Playwright
+-   📊 Performance testing and monitoring with baselines
 
 ## Getting Started
 
@@ -32,6 +33,7 @@ This boilerplate includes modern web features:
 -   `npm run test` - Run Playwright end-to-end tests
 -   `npm run test:ui` - Run Playwright tests with UI for debugging
 -   `npm run test:update-snapshots` - Update visual test baselines
+-   `npm run test:update-performance` - Update performance baselines
 -   `npm run analyze` - Analyze the site with Lighthouse
 
 ## Web Components
@@ -110,7 +112,7 @@ The site respects the user's motion preferences:
 
 ## Testing
 
-## Testing Philosophy
+### Testing Philosophy
 
 This boilerplate embraces a practical testing philosophy:
 
@@ -128,13 +130,15 @@ The boilerplate uses Playwright for comprehensive end-to-end testing which:
 -   Verifies behavior across **different devices and viewports**
 -   Ensures **accessibility standards** are met
 -   Provides **visual regression testing** to catch unexpected UI changes
+-   Monitors **performance metrics** against established baselines
 
 #### Included Test Types
 
 -   **Functional tests**: Verify features work as expected
 -   **Visual regression tests**: Catch unintended visual changes
 -   **Accessibility tests**: Ensure the site works for all users
 -   **Mobile responsiveness**: Test behavior on different devices
+-   **Performance tests**: Monitor core web vitals and prevent regressions
 
 #### Running Tests
 
@@ -148,6 +152,9 @@ npm run test:staging
 # Update visual snapshots after intentional changes
 npm run test:update-snapshots
 
+# Update performance baselines after optimizations
+npm run test:update-performance
+
 # Debug tests interactively with UI
 npm run test:ui
 
@@ -170,14 +177,51 @@ When making design changes, update the visual reference snapshots:
 npm run test:update-snapshots
 ```
 
-#### Writing Effective Tests
+### Performance Testing
+
+This boilerplate includes a comprehensive performance testing system:
+
+#### How it works
+
+1. **Performance baselines**: Each component and page has baseline metrics saved in the `/performance` directory
+2. **Automated testing**: Tests run on each build and compare current performance against baselines
+3. **Threshold alerts**: Tests fail if performance degrades beyond configurable thresholds
+4. **Lighthouse integration**: For index pages, full Lighthouse audits are run and results tracked
+
+#### Performance metrics tracked
+
+-   **Core Web Vitals**: First Contentful Paint (FCP), Largest Contentful Paint (LCP), Cumulative Layout Shift (CLS)
+-   **Interaction metrics**: Total Blocking Time (TBT), Time to Interactive (TTI)
+-   **Navigation metrics**: Time to First Byte (TTFB), DOM Load, Full Page Load
+-   **Component-level metrics**: Toggle operation time, memory usage, etc.
+
+#### Managing performance baselines
+
+After intentional performance changes or optimizations, update the baselines:
+
+```bash
+# Update performance baselines
+npm run test:update-performance
+```
+
+This will run all tests with the baseline update flag and save current metrics as the new baseline.
+
+#### Performance test file organization
+
+-   Performance tests are integrated into component-specific test files
+-   Each test file measures specific metrics relevant to that component
+-   The utils/performance-utils.js module provides shared testing utilities
+-   Baseline metrics are stored in the /performance directory as JSON files
+
+### Writing Effective Tests
 
 When adding new features, write Playwright tests that:
 
 1. Focus on **user journeys** rather than implementation details
 2. Use **accessibility-friendly selectors** like `getByRole` and `getByLabel`
 3. Test across **multiple browsers and devices**
-4. Include **visual regression** tests for UI components
+4. Include **visual regression** and **performance** tests
+5. Verify **accessibility** requirements are met
 
 Example of a good test case:
 
@@ -202,6 +246,10 @@ test('user can toggle theme', async ({ page }) => {
 		document.documentElement.classList.contains('dark-mode') ? 'dark' : 'light',
 	);
 	expect(newTheme).not.toBe(initialTheme);
+
+	// Check performance metrics for the operation
+	const metrics = await getBrowserPerformanceMetrics(page);
+	await assertPerformanceBaseline('theme-toggle-operation', metrics);
 });
 ```
 
@@ -219,15 +267,15 @@ This project uses Playwright's visual comparison testing to ensure UI consistenc
 
 ### Managing snapshots
 
--   **Update snapshots:** After intentional UI changes, run `npm run test:update-visual`
+-   **Update snapshots:** After intentional UI changes, run `npm run test:update-snapshots`
 -   **Clean temporary snapshots:** Remove diff and actual files with `npm run test:clean-snapshots`
 -   **View differences:** Check the Playwright report for side-by-side comparison of visual changes
 
 ### Snapshot organization
 
--   Baseline snapshots are stored in `tests/snapshots/`
--   Each test file has its own subfolder to organize screenshots
+-   Baseline snapshots are stored in `/snapshots/` with the naming convention `*-baseline.png`
 -   Only baseline snapshots are committed to git
+-   The snapshot directory uses a flat structure for simplicity
 
 ### Best practices
 

bin/baselines.js renamed to bin/regenerate-baselines.js

@@ -73,7 +73,7 @@ async function renameSnapshotsToBaselines() {
 
 async function main() {
 	try {
-		 // Ensure snapshots directory exists
+		// Ensure snapshots directory exists
 		try {
 			await fs.access(SNAPSHOTS_DIR);
 		} catch {

bin/screenshots.js renamed to bin/screenshots-generate.js

@@ -51,10 +51,7 @@ async function waitForServer() {
 			return false;
 		}
 
-		const [serverReady] = await Promise.all([
-			isServerReady(),
-			setTimeout(RETRY_DELAY)
-		]);
+		const [serverReady] = await Promise.all([isServerReady(), setTimeout(RETRY_DELAY)]);
 
 		if (serverReady) {
 			console.log('✅ Server is ready');

bin/snapshots.js renamed to bin/snapshots-clean.js

@@ -16,7 +16,7 @@ async function cleanSnapshots() {
 		// Check if snapshots directory exists
 		try {
 			await fs.access(SNAPSHOTS_DIR);
-		} catch {
+		} catch (err) {
 			console.log(`Creating snapshots directory at ${SNAPSHOTS_DIR}`);
 			await fs.mkdir(SNAPSHOTS_DIR, { recursive: true });
 			return;
@@ -31,21 +31,19 @@ async function cleanSnapshots() {
 		});
 
 		// Delete each file that's not a baseline
-		await Promise.all(
-			filesToRemove.map(async (file) => {
-				const filePath = path.join(SNAPSHOTS_DIR, file);
-				await fs.unlink(filePath);
-				console.log(`Deleted: ${file}`);
-			}),
-		);
+		for (const file of filesToRemove) {
+			const filePath = path.join(SNAPSHOTS_DIR, file);
+			await fs.unlink(filePath);
+			console.log(`Deleted: ${file}`);
+		}
 
 		console.log('Snapshot cleanup complete!');
 
 		// Try to restore baseline files from git if any were deleted
 		try {
 			execSync('git checkout -- ./snapshots/*baseline*', { stdio: 'inherit' });
 			console.log('Restored any missing baseline files from git');
-		} catch {
+		} catch (gitError) {
 			// It's okay if this fails, could be that there are no git-tracked baselines yet
 			console.log('Note: No baseline files needed to be restored from git');
 		}

bin/snapshots-update.js

@@ -0,0 +1,97 @@
+/**
+ * Script to regenerate snapshot baselines
+ * This script:
+ * 1. Runs the tests with --update-snapshots flag
+ * 2. Renames all snapshots to include "baseline" in the filename
+ */
+
+import { exec } from 'child_process';
+import fs from 'fs/promises';
+import path from 'path';
+
+const SNAPSHOTS_DIR = path.join(process.cwd(), 'snapshots');
+
+async function runTests() {
+	console.log('Running tests with --update-snapshots flag...');
+
+	return new Promise((resolve, reject) => {
+		exec('npx playwright test --update-snapshots', (error, stdout, stderr) => {
+			if (error) {
+				console.error('Error running tests:', error);
+				console.error(stderr);
+				reject(error);
+				return;
+			}
+
+			console.log(stdout);
+			resolve();
+		});
+	});
+}
+
+async function renameSnapshotsToBaselines() {
+	console.log('Renaming snapshots to include "baseline" in the filename...');
+
+	try {
+		// Ensure directory exists
+		try {
+			await fs.access(SNAPSHOTS_DIR);
+		} catch {
+			console.log(`Creating snapshots directory at ${SNAPSHOTS_DIR}`);
+			await fs.mkdir(SNAPSHOTS_DIR, { recursive: true });
+		}
+
+		const files = await fs.readdir(SNAPSHOTS_DIR);
+
+		const renamePromises = files.map(async (file) => {
+			// Skip files that already have "baseline" in the name or non-image files
+			if (file.includes('baseline') || !file.endsWith('.png')) {
+				return;
+			}
+
+			// Get file extension
+			const ext = path.extname(file);
+			const baseName = path.basename(file, ext);
+
+			// Create new filename with "baseline" suffix
+			const newFileName = `${baseName}-baseline${ext}`;
+
+			// Rename the file
+			await fs.rename(path.join(SNAPSHOTS_DIR, file), path.join(SNAPSHOTS_DIR, newFileName));
+
+			console.log(`Renamed: ${file} -> ${newFileName}`);
+		});
+
+		await Promise.all(renamePromises);
+
+		console.log('All snapshots renamed successfully!');
+	} catch (error) {
+		console.error('Error renaming snapshots:', error);
+		throw error;
+	}
+}
+
+async function main() {
+	try {
+		// Ensure snapshots directory exists
+		try {
+			await fs.access(SNAPSHOTS_DIR);
+		} catch {
+			console.log(`Creating snapshots directory at ${SNAPSHOTS_DIR}`);
+			await fs.mkdir(SNAPSHOTS_DIR, { recursive: true });
+		}
+
+		// Step 1: Run tests to generate new snapshots
+		await runTests();
+
+		// Step 2: Rename snapshots to include "baseline"
+		await renameSnapshotsToBaselines();
+
+		console.log('Baseline snapshots regenerated successfully!');
+	} catch (error) {
+		console.error('Failed to regenerate baseline snapshots:', error);
+		process.exit(1);
+	}
+}
+
+main();

package.json

@@ -17,20 +17,20 @@
 		"analyze": "lighthouse http://localhost:3000 --output json --output html --output-path ./lighthouse-report.html",
 		"kill": "npx kill-port 3000",
 		"lint": "eslint .",
+		"screenshots": "node bin/screenshots-generate.js",
+		"screenshots:prod": "node -e \"process.env.BASE_URL='https://your-production-url.com'\" && node bin/screenshots-generate.js",
 		"start": "npx serve ./www",
 		"test": "playwright test",
-		"test:staging": "node -e \"process.env.TEST_ENV='staging'\" && playwright test",
-		"test:ui": "playwright test --ui",
-		"test:update-snapshots": "playwright test --update-snapshots",
-		"test:regenerate-baselines": "node bin/baselines.js",
+		"test:clean-snapshots": "node bin/snapshots-clean.js",
 		"test:debug": "playwright test --debug",
+		"test:generate": "playwright codegen http://localhost:3000",
+		"test:perf": "node bin/perf-update.js",
 		"test:prod": "node -e \"process.env.TEST_ENV='production'\" && playwright test --project=chromium",
+		"test:regenerate-baselines": "node bin/snapshots-update.js",
 		"test:report": "playwright show-report",
-		"test:generate": "playwright codegen http://localhost:3000",
-		"test:performance": "playwright test performance.test.js --project=chromium",
-		"test:clean-snapshots": "node bin/clean-snapshots.js",
-		"screenshots": "node bin/screenshots.js",
-		"screenshots:prod": "node -e \"process.env.BASE_URL='https://your-production-url.com'\" && node bin/screenshots.js"
+		"test:staging": "node -e \"process.env.TEST_ENV='staging'\" && playwright test",
+		"test:ui": "playwright test --ui",
+		"test:update-snapshots": "playwright test --update-snapshots"
 	},
 	"type": "module"
 }