hoerdle/docs/TESTING.md

Integration Testing

Hördle uses Playwright for end-to-end (E2E) integration testing. These tests ensure that critical flows like gameplay, authentication, and admin management function correctly across different browsers.

Prerequisites

Ensure you have the Playwright browsers installed:

npx playwright install

Running Tests

Headless Mode (CI/CLI)

To run all tests in headless mode (Chromium, Firefox, WebKit):

npm run test:e2e

UI Mode (Interactive)

To run tests with a UI to inspect traces and watch execution:

npm run test:e2e:ui

Specific Test File

To run a specific test file:

npx playwright test tests/gameplay.spec.ts

Specific Project (Browser)

To run tests only on a specific browser (e.g., Chromium):

npx playwright test --project=chromium

Configuration

The Playwright configuration is located in playwright.config.ts. It sets up the base URL (default: http://localhost:3000) and the web server command to start the app if it's not running.

Environment Variables

• ADMIN_PASSWORD: The tests assume the admin password is 'admin123'.
  • In app/api/admin/login/route.ts, the login logic has been enhanced to check if ADMIN_PASSWORD is a bcrypt hash (starts with $2b$) or plain text.
  • For local testing, you can set ADMIN_PASSWORD="admin123" in your .env or .env.local (though the default fallback in the code also handles this).
• Curator Credentials: The mock Curator login page (app/[locale]/curator/page.tsx) mocks validation for testing.
  • Username: elpatron
  • Password: example_password

Test Structure

Tests are located in the tests/ directory:

• auth.spec.ts: Verifies public access and admin login flows.
• admin.spec.ts: Checks the Admin Dashboard, including access protection and visibility of sections (Dashboard, Daily Puzzles, etc.).
• curator.spec.ts: Verifies the Curator login form and authentication flows (valid/invalid credentials).
• gameplay.spec.ts: Tests the core game loop: loading the game, playing audio, interaction with the prompt, and submitting a guess.

Troubleshooting & Known Issues

Next.js Development Overlay (nextjs-portal)

In development mode (npm run dev), Next.js injects an overlay (<nextjs-portal>) for hot reloading feedback. This overlay can sometimes intercept clicks intended for UI elements, causing tests to fail with "element is not clickable" or timeout errors.

Solution: We inject a CSS style in the beforeEach hook of our tests to hide this overlay:

test.beforeEach(async ({ page }) => {
    await page.addStyleTag({ content: 'nextjs-portal, #nextjs-dev-overlay, [data-nextjs-dev-overlay] { display: none !important; }' });
});

WebKit (Safari) Stability

WebKit can be slower or more sensitive to timing in some environments. If tests fail on WebKit but pass on other browsers:

1. Try increasing the timeout in playwright.config.ts.
2. Use await page.waitForTimeout(500) or specific assertions like await expect(page).toHaveURL(...) to allow for transition times, as implemented in tests/admin.spec.ts.