Set up Playwright for local, manual e2e testing (LS-2335)

.gitignore

@@ -105,3 +105,10 @@ lightspeed.code-workspace
 .cache/
 .aider*
 .continue/
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

CHANGELOG.md

@@ -49,6 +49,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added a portable `theme-color-token-enforcer` skill to audit or fix semantic colour token usage.
 - Added a theme-local `pattern-extractor` skill and matching `extract-pattern` prompt wrapper for Figma-to-pattern workflows that honour semantic tokens and CSS-versus-GSAP motion routing.
 - Added a CSS-only `Card - Feature` group treatment, a matching inline CTA paragraph style, and an insertable single-card pattern at `patterns/cards/card-feature.php`.
+- Added a Playwright end-to-end testing setup (LS-2335), matching the official `create-playwright` scaffold: `@playwright/test`, `dotenv`, and `@types/node` as dev dependencies, and `playwright.config.ts` configured for all 3 browser projects (Chromium, Firefox, WebKit) with `baseURL` read from a local, gitignored `.env` (`BASE_URL=`) so each developer points tests at their own environment — no CI wiring, run manually via `npx playwright test`. Added a real spec (`tests/specs/work-archive.spec.ts`) exercising all 6 generic assertion helpers from `tests/helpers/assertions.ts` (LS-2244) against the live Work Archive template — section order, category-card count/parts, hero link href, related-routes grid reflow at mobile, and stats-grid divider styling.
 
 ### Changed
 

package.json

@@ -15,7 +15,10 @@
 		"watch:css": "npm run sync:breakpoints && sass --watch --no-source-map --no-charset --style=expanded src/scss/animations.scss:assets/css/animations.css src/scss/gsap-animations.scss:assets/css/gsap-animations.css"
 	},
 	"devDependencies": {
+		"@playwright/test": "^1.62.1",
+		"@types/node": "^26.1.2",
 		"ajv": "^8.17.1",
+		"dotenv": "^17.4.2",
 		"glob": "^11.0.1",
 		"sass": "^1.99.0"
 	},

playwright.config.ts

@@ -0,0 +1,84 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Read environment variables from file.
+ * https://github.com/motdotla/dotenv
+ */
+import dotenv from 'dotenv';
+import path from 'path';
+// This repo's package.json has "type": "module", so __dirname (assumed by
+// Playwright's own generated template) isn't available here — using
+// Node's documented ESM equivalent instead: https://nodejs.org/api/esm.html#importmetadirname
+dotenv.config({ path: path.resolve(import.meta.dirname, '.env') });
+
+/**
+ * See https://playwright.dev/docs/test-configuration.
+ */
+export default defineConfig({
+	// Deviation from the installer default ('./tests'): this repo's tests
+	// live under tests/specs (established in LS-2244, before this ticket).
+	testDir: './tests/specs',
+	/* Run tests in files in parallel */
+	fullyParallel: true,
+	/* Fail the build on CI if you accidentally left test.only in the source code. */
+	forbidOnly: !!process.env.CI,
+	/* Retry on CI only */
+	retries: process.env.CI ? 2 : 0,
+	/* Opt out of parallel tests on CI. */
+	workers: process.env.CI ? 1 : undefined,
+	/* Reporter to use. See https://playwright.dev/docs/test-reporters */
+	reporter: 'html',
+	/* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */
+	use: {
+		/* Base URL to use in actions like `await page.goto('')`. */
+		baseURL: process.env.BASE_URL,
+
+		/* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */
+		trace: 'on-first-retry',
+	},
+
+	/* Configure projects for major browsers */
+	projects: [
+		{
+			name: 'chromium',
+			use: { ...devices['Desktop Chrome'] },
+		},
+
+		{
+			name: 'firefox',
+			use: { ...devices['Desktop Firefox'] },
+		},
+
+		{
+			name: 'webkit',
+			use: { ...devices['Desktop Safari'] },
+		},
+
+		/* Test against mobile viewports. */
+		// {
+		//   name: 'Mobile Chrome',
+		//   use: { ...devices['Pixel 5'] },
+		// },
+		// {
+		//   name: 'Mobile Safari',
+		//   use: { ...devices['iPhone 12'] },
+		// },
+
+		/* Test against branded browsers. */
+		// {
+		//   name: 'Microsoft Edge',
+		//   use: { ...devices['Desktop Edge'], channel: 'msedge' },
+		// },
+		// {
+		//   name: 'Google Chrome',
+		//   use: { ...devices['Desktop Chrome'], channel: 'chrome' },
+		// },
+	],
+
+	/* Run your local dev server before starting the tests */
+	// webServer: {
+	//   command: 'npm run start',
+	//   url: 'http://localhost:3000',
+	//   reuseExistingServer: !process.env.CI,
+	// },
+});

tests/helpers/assertions.ts

@@ -0,0 +1,130 @@
+import { expect, type Page } from '@playwright/test';
+
+/**
+ * Generic Playwright assertion helpers for ls-theme.
+ *
+ * None of these know about any specific page, pattern, or template — every
+ * input (selector, text, count, viewport width, expected value) is a
+ * parameter. They were extracted from testing the Work Archive template,
+ * but apply to any pattern in the theme with the same shape.
+ */
+
+/**
+ * Asserts a list of text markers appears on the page in that exact order.
+ * Matching is case-insensitive so callers can write natural-case marker
+ * text without coupling the test to a `text-transform` CSS style.
+ */
+export async function expectSectionOrder(page: Page, markers: string[]) {
+	const bodyText = (await page.locator('body').innerText()).toLowerCase();
+	const positions = markers.map((marker) => bodyText.indexOf(marker.toLowerCase()));
+
+	positions.forEach((pos, i) => {
+		expect(pos, `Expected to find "${markers[i]}" on the page`).toBeGreaterThan(-1);
+	});
+
+	for (let i = 1; i < positions.length; i++) {
+		expect(
+			positions[i],
+			`Expected "${markers[i]}" to appear after "${markers[i - 1]}"`
+		).toBeGreaterThan(positions[i - 1]);
+	}
+}
+
+/** Asserts a selector matches exactly `count` elements. */
+export async function expectElementCount(page: Page, selector: string, count: number) {
+	await expect(page.locator(selector)).toHaveCount(count);
+}
+
+/**
+ * Asserts every element matching `cardSelector` contains all of its
+ * `requiredParts` (each a sub-selector, e.g. 'a', '.wp-block-post-excerpt').
+ */
+export async function expectCardParts(page: Page, cardSelector: string, requiredParts: string[]) {
+	const cards = page.locator(cardSelector);
+	const count = await cards.count();
+	expect(count, `Expected at least one "${cardSelector}" card`).toBeGreaterThan(0);
+
+	for (let i = 0; i < count; i++) {
+		const card = cards.nth(i);
+		for (const part of requiredParts) {
+			await expect(
+				card.locator(part).first(),
+				`Card ${i} (${cardSelector}) is missing required part "${part}"`
+			).toBeAttached({ timeout: 2000 });
+		}
+	}
+}
+
+/** Asserts a link, found by its visible text, has the expected href. */
+export async function expectLinkHref(page: Page, linkText: string, expectedHref: string) {
+	const link = page.getByRole('link', { name: linkText, exact: false });
+	await expect(link).toHaveAttribute('href', expectedHref);
+}
+
+/**
+ * Resizes the viewport to `viewportWidth` and asserts the grid at
+ * `gridSelector` shows exactly `expectedColumns` columns — works for both
+ * CSS Grid (reads grid-template-columns) and flex-wrap layouts (groups
+ * elements by their top offset).
+ */
+export async function expectGridColumnsAtViewport(
+	page: Page,
+	gridSelector: string,
+	viewportWidth: number,
+	expectedColumns: number,
+	viewportHeight = 900
+) {
+	await page.setViewportSize({ width: viewportWidth, height: viewportHeight });
+
+	const grid = page.locator(gridSelector).first();
+	const display = await grid.evaluate((el) => getComputedStyle(el).display);
+
+	if (display === 'grid') {
+		const columns = await grid.evaluate(
+			(el) => getComputedStyle(el).gridTemplateColumns.split(' ').length
+		);
+		expect(columns, `Expected ${expectedColumns} grid columns at ${viewportWidth}px`).toBe(
+			expectedColumns
+		);
+		return;
+	}
+
+	// Flex/columns layout: count distinct items sharing the first row's top offset.
+	const tops: number[] = await grid.evaluate((el) =>
+		[...el.children].map((child) => Math.round(child.getBoundingClientRect().top))
+	);
+	const firstRowCount = tops.filter((t) => t === tops[0]).length;
+	expect(
+		firstRowCount,
+		`Expected ${expectedColumns} items in the first row at ${viewportWidth}px`
+	).toBe(expectedColumns);
+}
+
+/**
+ * Asserts a computed CSS property on `selector` equals `expectedValue`,
+ * optionally after resizing to `viewportWidth` first.
+ */
+export async function expectComputedStyle(
+	page: Page,
+	selector: string,
+	property: string,
+	expectedValue: string,
+	viewportWidth?: number,
+	viewportHeight = 900
+) {
+	if (viewportWidth) {
+		await page.setViewportSize({ width: viewportWidth, height: viewportHeight });
+	}
+
+	const value = await page
+		.locator(selector)
+		.first()
+		.evaluate((el, prop) => getComputedStyle(el).getPropertyValue(prop).trim(), property);
+
+	expect(
+		value,
+		`Expected ${selector} to have ${property}: ${expectedValue}${
+			viewportWidth ? ` at ${viewportWidth}px` : ''
+		}`
+	).toBe(expectedValue);
+}