Switch E2E tests to BDD format

.github/workflows/push.yml

@@ -22,6 +22,8 @@ jobs:
       matrix:
         node: [20.18, 20, 22, 24]
     runs-on: ubuntu-latest
+    outputs:
+      lcov-artifact-id: ${{ steps.upload-lcov.outputs.artifact-id }}
     services:
       postgres:
         image: postgres
@@ -48,6 +50,7 @@ jobs:
         env:
           FORCE_COLOR: true
       - uses: actions/upload-artifact@v4
+        id: upload-lcov
         if: vars.ENABLE_COVERALLS == 'true'
         with:
           name: lcov-${{ matrix.node }}
@@ -59,11 +62,11 @@ jobs:
 
   coverage:
     runs-on: ubuntu-latest
-    if: vars.ENABLE_COVERALLS == 'true'
+    needs: [nodejs]
+    if: always() && vars.ENABLE_COVERALLS == 'true' && needs.nodejs.outputs.lcov-artifact-id
     environment:
       name: coveralls
       url: https://coveralls.io/github/${{ github.repository }}
-    needs: [nodejs]
     steps:
       - uses: actions/checkout@v4
       - run: |

.gitignore

@@ -3,6 +3,7 @@
 api/static/
 coverage/
 e2e/blob-report/
+e2e/.generated/
 e2e/playwright/.cache/
 e2e/playwright-report/
 e2e/test-results/

e2e/features/about.feature

@@ -0,0 +1,9 @@
+Feature: About page
+
+	Scenario: Check page heading
+		Given I am on about page
+		Then I see in heading "About"
+
+	Scenario: Check accessibility
+		Given I am on about page
+		Then it meets accessibility guidelines

e2e/features/home.feature

@@ -0,0 +1,18 @@
+Feature: Home page
+
+	Scenario: Check page title
+		Given I am on home page
+		Then I see in title "Vite + React"
+
+	Scenario: Check accessibility
+		Given I am on home page
+		Then it meets accessibility guidelines
+
+	Scenario: Check server connection
+		Given I am on home page
+		Then I see in page "Server says: Hello, world!"
+
+	Scenario: Check Vite link
+		Given I am on home page
+		When I click the "Vite logo" link
+		Then I am taken to "https://vite.dev/"

e2e/tests/fixtures.js → e2e/features/steps/fixtures.js

@@ -1,20 +1,27 @@
 import AxeBuilder from "@axe-core/playwright";
-import { test as base } from "@playwright/test";
+import { test as base, createBdd } from "playwright-bdd";
 
 /**
  * @typedef {import("@playwright/test").PlaywrightTestArgs & import("@playwright/test").PlaywrightTestOptions} T
  * @typedef {import("@playwright/test").PlaywrightWorkerArgs & import("@playwright/test").PlaywrightWorkerOptions} W
  */
 
 /**
- * @type {import("@playwright/test").TestType<T & { a11yTags: string[]; axe: AxeBuilder }, W>}
+ * @type {import("@playwright/test").TestType<T & { a11yTags: string[]; axe: AxeBuilder; ctx: Record<string, any> }, W>}
  */
 export const test = base.extend({
 	a11yTags: [["wcag2a"], { option: true }],
 	axe: async ({ a11yTags, page }, use) => {
 		const axe = new AxeBuilder({ page }).withTags(a11yTags);
 		await use(axe);
 	},
+	// eslint-disable-next-line no-empty-pattern -- required, see e.g. microsoft/playwright#21566
+	ctx: async ({}, use) => {
+		const ctx = {};
+		await use(ctx);
+	},
 });
 
+export const { Given, When, Then } = createBdd(test);
+
 export { expect } from "@playwright/test";

e2e/features/steps/steps.js

@@ -0,0 +1,36 @@
+import { expect, Given, When, Then } from "./fixtures.js";
+
+Given("I am on home page", async ({ page }) => {
+	await page.goto("/");
+});
+
+Given("I am on about page", async ({ page }) => {
+	await page.goto("/nested/about/path");
+});
+
+When("I click the {string} link", async ({ ctx, page }, name) => {
+	ctx.newPageEvent = page.waitForEvent("popup");
+	await page.getByRole("link", { name }).click();
+});
+
+Then("I am taken to {string}", async ({ ctx }, url) => {
+	const newPage = await ctx.newPageEvent;
+	await expect(newPage.url()).toBe(url);
+});
+
+Then("I see in heading {string}", async ({ page }, text) => {
+	await expect(page.getByRole("heading", { level: 1 })).toHaveText(text);
+});
+
+Then("I see in page {string}", async ({ page }, text) => {
+	await expect(page.getByText(text)).toBeAttached();
+});
+
+Then("I see in title {string}", async ({ page }, title) => {
+	await expect(page).toHaveTitle(title);
+});
+
+Then("it meets accessibility guidelines", async ({ axe }) => {
+	const { violations } = await axe.analyze();
+	expect(violations).toHaveLength(0);
+});

e2e/package.json

@@ -6,12 +6,14 @@
 	"author": "Jonathan Sharpe <[email protected]>",
 	"type": "module",
 	"scripts": {
+		"pree2e": "bddgen",
 		"e2e": "playwright test"
 	},
 	"devDependencies": {
 		"@axe-core/playwright": "^4.10.1",
 		"@playwright/test": "^1.52.0",
 		"eslint-plugin-playwright": "^2.2.0",
-		"playwright": "^1.40.1"
+		"playwright": "^1.40.1",
+		"playwright-bdd": "^8.1.0"
 	}
 }

e2e/playwright.config.js

@@ -4,6 +4,7 @@ import { fileURLToPath } from "node:url";
 
 import { defineConfig, devices } from "@playwright/test";
 import { configDotenv } from "dotenv";
+import { defineBddConfig } from "playwright-bdd";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -17,8 +18,14 @@ const logs =
 
 const port = process.env.PORT ?? "3000";
 
+const testDir = defineBddConfig({
+	features: "./features/*.feature",
+	outputDir: "./.generated/",
+	steps: "./features/steps/*.js",
+});
+
 export default defineConfig({
-	testDir: "./tests",
+	testDir,
 	/* Run tests in files in parallel */
 	fullyParallel: true,
 	/* Fail the build on CI if you accidentally left test.only in the source code. */
@@ -56,26 +63,6 @@ export default defineConfig({
 			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 */

eslint.config.js

@@ -102,6 +102,9 @@ export default [
 	{
 		files: ["e2e/**"],
 		...playwrightPlugin.configs["flat/recommended"],
+		rules: {
+			"playwright/no-standalone-expect": "off",
+		},
 	},
 	{
 		files: ["web/**/*.js?(x)"],
@@ -149,6 +152,11 @@ export default [
 		},
 	},
 	{
-		ignores: ["api/static", "e2e/playwright-report", "e2e/test-results"],
+		ignores: [
+			"api/static",
+			"e2e/.generated",
+			"e2e/playwright-report",
+			"e2e/test-results",
+		],
 	},
 ];