Add docs API reference smoke test

The API reference had been crashing after hydration because we relied on CJS component shims that loaded a second copy of the docs plugin contexts. We already patched the runtime and aliased Docusaurus to fix the bug, but there was nothing preventing regressions. This commit adds a dedicated Playwright config and test that builds the docs site, serves the static bundle, loads /wordpress-playground/api, and fails if hydration throws page or console errors. A new Nx target and CI job run the smoke test with Chromium so every PR proves the API docs render before we deploy.

Author: adamziel

.github/workflows/ci.yml

@@ -254,6 +254,18 @@ jobs:
                   path: packages/playground/components/playwright-report/
                   if-no-files-found: ignore
 
+    test-docs-api-reference:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  submodules: true
+            - uses: ./.github/actions/prepare-playground
+            - name: Install Playwright Browsers
+              run: npx playwright install --with-deps chromium
+            - name: Verify docs API reference
+              run: npx nx run docs-site:api-e2e
+
     test-built-npm-packages:
         runs-on: ubuntu-latest
         steps:

packages/docs/site/playwright.config.ts

@@ -0,0 +1,25 @@
+import { defineConfig } from '@playwright/test';
+
+const port = process.env.DOCS_E2E_PORT ?? '4173';
+const host = process.env.DOCS_E2E_HOST ?? '127.0.0.1';
+const baseUrl = process.env.DOCS_E2E_BASE_URL ?? `http://${host}:${port}`;
+
+export default defineConfig({
+	testDir: './tests',
+	timeout: 60_000,
+	expect: {
+		timeout: 10_000,
+	},
+	use: {
+		baseURL: baseUrl,
+		trace: 'retain-on-failure',
+		screenshot: 'only-on-failure',
+		video: 'retain-on-failure',
+	},
+	webServer: {
+		command: `npx http-server dist/docs/build -p ${port} -c-1`,
+		url: `${baseUrl}/wordpress-playground/`,
+		reuseExistingServer: !process.env.CI,
+		timeout: 120_000,
+	},
+});

packages/docs/site/project.json

@@ -79,6 +79,16 @@
 			},
 			"dependsOn": ["build:json"]
 		},
+		"api-e2e": {
+			"executor": "nx:run-commands",
+			"options": {
+				"commands": [
+					"npm run build:docs",
+					"npx playwright test --config=packages/docs/site/playwright.config.ts --project=chromium"
+				],
+				"parallel": false
+			}
+		},
 		"lint": {
 			"executor": "@nx/linter:eslint",
 			"outputs": ["{options.outputFile}"],

packages/docs/site/tests/api-reference.spec.ts

@@ -0,0 +1,34 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('Docs API reference', () => {
+	test('loads without runtime errors', async ({ page }) => {
+		const pageErrors: Error[] = [];
+		const consoleErrors: string[] = [];
+
+		page.on('pageerror', (error) => {
+			pageErrors.push(error);
+		});
+
+		page.on('console', (message) => {
+			if (message.type() === 'error') {
+				const text = message.text();
+				// Ignore benign production React hint that is injected in dev.
+				if (text.includes('Download the React DevTools')) {
+					return;
+				}
+				consoleErrors.push(text);
+			}
+		});
+
+		await page.goto('/wordpress-playground/api', {
+			waitUntil: 'networkidle',
+		});
+		await expect(page.locator('.apiPage')).toBeVisible();
+
+		expect(
+			pageErrors,
+			pageErrors.map((error) => error.message).join('\n')
+		).toHaveLength(0);
+		expect(consoleErrors, consoleErrors.join('\n')).toHaveLength(0);
+	});
+});