refactor(e2e): implement Page Object Model pattern

Introduce POM abstraction layer for Playwright e2e tests. Create BasePage
class and page objects for all tested pages, extend fixtures to provide
them automatically, refactor all existing tests, and add smoke tests.

Author: thostetler

e2e/README.md

@@ -141,3 +141,55 @@ pnpm test:e2e:docker
 lsof -ti:8000 | xargs kill -9
 lsof -ti:18080 | xargs kill -9
 ```
+
+## Page Object Model
+
+Tests use the Page Object Model (POM) pattern. Page objects live in `e2e/pages/` and encapsulate selectors and actions for each page.
+
+### Directory structure
+
+```
+e2e/
+├── fixtures/
+│   ├── nectar.fixture.ts   — Playwright fixtures (provides page objects + helpers)
+│   └── helpers.ts           — Cookie/response utility functions
+├── pages/
+│   ├── base.page.ts         — Abstract base class (navigation, cookies, scenarios)
+│   ├── home.page.ts         — Landing page
+│   ├── login.page.ts        — Login form page
+│   ├── search.page.ts       — Search results page
+│   ├── register.page.ts     — Registration page
+│   ├── forgot-password.page.ts — Forgot password page
+│   ├── verify.page.ts       — Email verification page
+│   ├── settings.page.ts     — User settings page
+│   └── index.ts             — Barrel export
+└── tests/
+    ├── middleware/           — Middleware integration tests
+    └── smoke/                — Smoke/navigation tests
+```
+
+### Adding a new page object
+
+1. Create `e2e/pages/my-page.page.ts` extending `BasePage`
+2. Set the `path` property (e.g., `/my-page`)
+3. Add selectors as private readonly properties
+4. Add action methods (e.g., `fillForm`, `submit`)
+5. Export from `e2e/pages/index.ts`
+6. Add a fixture in `e2e/fixtures/nectar.fixture.ts`
+
+### Using page objects in tests
+
+```typescript
+import { test, expect } from '../../fixtures/nectar.fixture';
+
+test('example', async ({ loginPage, searchPage }) => {
+  await loginPage.addSessionCookie('anonymous-session');
+  await loginPage.setScenarioHeader('bootstrap-anonymous');
+  await loginPage.goto();
+
+  await loginPage.fillCredentials('user@example.com', 'pass');
+  await loginPage.submit();
+});
+```
+
+Page objects are provided automatically via Playwright fixtures — destructure them in the test signature.

e2e/fixtures/nectar.fixture.ts

@@ -1,22 +1,66 @@
+/* eslint-disable react-hooks/rules-of-hooks -- Playwright fixture `use` is not React */
 import { test as base, expect } from '@playwright/test';
+import { HomePage } from '../pages/home.page';
+import { LoginPage } from '../pages/login.page';
+import { SearchPage } from '../pages/search.page';
+import { RegisterPage } from '../pages/register.page';
+import { ForgotPasswordPage } from '../pages/forgot-password.page';
+import { VerifyPage } from '../pages/verify.page';
+import { SettingsPage } from '../pages/settings.page';
 
 export type NectarTestContext = {
   nectarUrl: string;
+  homePage: HomePage;
+  loginPage: LoginPage;
+  searchPage: SearchPage;
+  registerPage: RegisterPage;
+  forgotPasswordPage: ForgotPasswordPage;
+  verifyPage: VerifyPage;
+  settingsPage: SettingsPage;
   setTestScenario: (scenario: string) => Promise<void>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- __NEXT_DATA__ is untyped
   getNextData: () => Promise<any>;
   assertCookieRewritten: (cookie: string | undefined, expectedValue: string) => void;
+  resetStub: () => Promise<void>;
 };
 
+const STUB_URL = process.env.STUB_URL || 'http://127.0.0.1:18080';
+
 export const test = base.extend<NectarTestContext>({
   nectarUrl: async ({}, use) => {
     await use(process.env.NECTAR_URL || process.env.BASE_URL || 'http://127.0.0.1:8000');
   },
 
-  setTestScenario: async ({ context }, use) => {
-    let currentScenario: string | null = null;
+  homePage: async ({ page, context, nectarUrl }, use) => {
+    await use(new HomePage(page, context, nectarUrl));
+  },
+
+  loginPage: async ({ page, context, nectarUrl }, use) => {
+    await use(new LoginPage(page, context, nectarUrl));
+  },
+
+  searchPage: async ({ page, context, nectarUrl }, use) => {
+    await use(new SearchPage(page, context, nectarUrl));
+  },
+
+  registerPage: async ({ page, context, nectarUrl }, use) => {
+    await use(new RegisterPage(page, context, nectarUrl));
+  },
+
+  forgotPasswordPage: async ({ page, context, nectarUrl }, use) => {
+    await use(new ForgotPasswordPage(page, context, nectarUrl));
+  },
+
+  verifyPage: async ({ page, context, nectarUrl }, use) => {
+    await use(new VerifyPage(page, context, nectarUrl));
+  },
+
+  settingsPage: async ({ page, context, nectarUrl }, use) => {
+    await use(new SettingsPage(page, context, nectarUrl));
+  },
 
+  setTestScenario: async ({ context }, use) => {
     await use(async (scenario: string) => {
-      currentScenario = scenario;
       await context.route('**/*', async (route) => {
         const headers = route.request().headers();
         if (scenario) {
@@ -45,6 +89,12 @@ export const test = base.extend<NectarTestContext>({
       expect(cookie).not.toContain('Domain=');
     });
   },
+
+  resetStub: async ({ request }, use) => {
+    await use(async () => {
+      await request.post(`${STUB_URL}/__test__/reset`);
+    });
+  },
 });
 
 export { expect };

e2e/pages/base.page.ts

@@ -0,0 +1,91 @@
+import { Page, BrowserContext, Response, expect } from '@playwright/test';
+
+export abstract class BasePage {
+  constructor(protected readonly page: Page, protected readonly context: BrowserContext, readonly baseUrl: string) {}
+
+  protected abstract readonly path: string;
+
+  get url(): string {
+    return this.page.url();
+  }
+
+  buildUrl(params?: string): string {
+    const base = `${this.baseUrl}${this.path}`;
+    if (!params) {
+      return base;
+    }
+    const url = new URL(base);
+    const extra = new URLSearchParams(params.replace(/^\?/, ''));
+    extra.forEach((value, key) => url.searchParams.set(key, value));
+    return url.toString();
+  }
+
+  async goto(options?: { waitUntil?: 'load' | 'commit' | 'networkidle' }): Promise<Response | null> {
+    return this.page.goto(`${this.baseUrl}${this.path}`, options);
+  }
+
+  async gotoWithParams(
+    params: string,
+    options?: { waitUntil?: 'load' | 'commit' | 'networkidle' },
+  ): Promise<Response | null> {
+    return this.page.goto(this.buildUrl(params), options);
+  }
+
+  async gotoUrl(url: string, options?: { waitUntil?: 'load' | 'commit' | 'networkidle' }): Promise<Response | null> {
+    return this.page.goto(url, options);
+  }
+
+  async waitForUrl(pattern: string | RegExp, options?: { timeout?: number }): Promise<void> {
+    await this.page.waitForURL(pattern, options);
+  }
+
+  async waitForLoadState(state: 'load' | 'domcontentloaded' | 'networkidle'): Promise<void> {
+    await this.page.waitForLoadState(state);
+  }
+
+  async clearCookies(): Promise<void> {
+    await this.context.clearCookies();
+  }
+
+  async addSessionCookie(value: string): Promise<void> {
+    await this.context.addCookies([{ name: 'ads_session', value, url: this.baseUrl }]);
+  }
+
+  async setScenarioHeader(scenario: string): Promise<void> {
+    await this.page.setExtraHTTPHeaders({
+      'x-test-scenario': scenario,
+    });
+  }
+
+  async setScenarioViaRoute(scenario: string): Promise<void> {
+    await this.context.route('**/*', async (route) => {
+      const headers = route.request().headers();
+      headers['x-test-scenario'] = scenario;
+      await route.continue({ headers });
+    });
+  }
+
+  async setExtraHeaders(headers: Record<string, string>): Promise<void> {
+    await this.page.setExtraHTTPHeaders(headers);
+  }
+
+  async interceptRoute(pattern: string, handler: Parameters<Page['route']>[1]): Promise<void> {
+    await this.page.route(pattern, handler);
+  }
+
+  async getCookies() {
+    return this.context.cookies();
+  }
+
+  urlContains(substring: string): void {
+    expect(this.page.url()).toContain(substring);
+  }
+
+  urlEquals(expected: string): void {
+    expect(this.page.url()).toBe(expected);
+  }
+
+  urlMatches(pattern: RegExp): void {
+    expect(this.page.url()).toMatch(pattern);
+  }
+}

e2e/pages/forgot-password.page.ts

@@ -0,0 +1,10 @@
+import { Page, BrowserContext } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class ForgotPasswordPage extends BasePage {
+  protected readonly path = '/user/forgotpassword';
+
+  constructor(page: Page, context: BrowserContext, baseUrl: string) {
+    super(page, context, baseUrl);
+  }
+}

e2e/pages/home.page.ts

@@ -0,0 +1,18 @@
+import { Page, BrowserContext } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class HomePage extends BasePage {
+  protected readonly path = '/';
+
+  private readonly searchInput = '[data-testid="search-input"]';
+  private readonly searchSubmit = '[data-testid="search-submit"]';
+
+  constructor(page: Page, context: BrowserContext, baseUrl: string) {
+    super(page, context, baseUrl);
+  }
+
+  async search(query: string): Promise<void> {
+    await this.page.fill(this.searchInput, query);
+    await this.page.click(this.searchSubmit);
+  }
+}

e2e/pages/index.ts

@@ -0,0 +1,8 @@
+export { BasePage } from './base.page';
+export { HomePage } from './home.page';
+export { LoginPage } from './login.page';
+export { SearchPage } from './search.page';
+export { RegisterPage } from './register.page';
+export { ForgotPasswordPage } from './forgot-password.page';
+export { VerifyPage } from './verify.page';
+export { SettingsPage } from './settings.page';

e2e/pages/login.page.ts

@@ -0,0 +1,43 @@
+import { Page, BrowserContext } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class LoginPage extends BasePage {
+  protected readonly path = '/user/account/login';
+
+  private readonly emailInput = 'input[name="email"]';
+  private readonly passwordInput = 'input[name="password"]';
+  private readonly submitButton = 'button[type="submit"]';
+
+  constructor(page: Page, context: BrowserContext, baseUrl: string) {
+    super(page, context, baseUrl);
+  }
+
+  async gotoWithNext(nextUrl: string): Promise<void> {
+    await this.gotoWithParams(`?next=${encodeURIComponent(nextUrl)}`);
+  }
+
+  async fillCredentials(email: string, password: string): Promise<void> {
+    await this.page.fill(this.emailInput, email);
+    await this.page.fill(this.passwordInput, password);
+  }
+
+  async submit(): Promise<void> {
+    await this.page.click(this.submitButton);
+  }
+
+  async mockLoginSuccess(): Promise<void> {
+    await this.interceptRoute('**/api/auth/login', async (route) => {
+      await route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ success: true }),
+      });
+    });
+  }
+
+  async login(email: string, password: string): Promise<void> {
+    await this.fillCredentials(email, password);
+    await this.mockLoginSuccess();
+    await this.submit();
+  }
+}

e2e/pages/register.page.ts

@@ -0,0 +1,10 @@
+import { Page, BrowserContext } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class RegisterPage extends BasePage {
+  protected readonly path = '/user/account/register';
+
+  constructor(page: Page, context: BrowserContext, baseUrl: string) {
+    super(page, context, baseUrl);
+  }
+}

e2e/pages/search.page.ts

@@ -0,0 +1,24 @@
+import { Page, BrowserContext, Response, expect } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class SearchPage extends BasePage {
+  protected readonly path = '/search';
+
+  private readonly searchInput = '[data-testid="search-input"]';
+  private readonly searchSubmit = '[data-testid="search-submit"]';
+
+  constructor(page: Page, context: BrowserContext, baseUrl: string) {
+    super(page, context, baseUrl);
+  }
+
+  async search(query: string): Promise<void> {
+    await this.page.fill(this.searchInput, query);
+    await this.page.click(this.searchSubmit);
+  }
+
+  async gotoAndExpect(options?: { waitUntil?: 'load' | 'commit' | 'networkidle' }): Promise<Response> {
+    const response = await this.goto(options);
+    expect(response).not.toBeNull();
+    return response!;
+  }
+}

e2e/pages/settings.page.ts

@@ -0,0 +1,10 @@
+import { Page, BrowserContext } from '@playwright/test';
+import { BasePage } from './base.page';
+
+export class SettingsPage extends BasePage {
+  protected readonly path = '/user/settings';
+
+  constructor(page: Page, context: BrowserContext, baseUrl: string) {
+    super(page, context, baseUrl);
+  }
+}