Create Run E2E Tests

Authoring Packmind E2E Tests

Overview

apps/e2e-tests/ runs Playwright against the real frontend (http://localhost:4200) and API. Tests drive the browser through a Page Object Model and seed irrelevant setup data through the API, not the UI. The dev stack must be running first (see michel-run-local-dev-stack).

Two rules dominate everything here, and both come from the project's .packmind standards:

1. Never use Playwright's raw test. Always use one of the project fixtures. They handle user creation, sign-up, and API-key setup so each test starts from a clean, authenticated state.
2. Drive the UI through Page Objects, never raw selectors in specs. A spec should read like a user story; selectors live inside page objects so a markup change breaks one file, not twenty tests.

Where files go

This mirrors the hexagonal split used across the repo: domain/ holds interfaces, infra/ holds implementations.

Choosing a fixture

The three fixtures form a chain — each extends the previous and adds one capability. Pick the lowest one that gives you what the test needs, so you don't pay for setup you won't use.

All three live in src/fixtures/packmindTest.ts. Import the one you need:

import { testWithApi } from '../../fixtures/packmindTest';

Example — UI-only test

import { testWithUserSignedUp } from '../../fixtures/packmindTest';
import { expect } from '@playwright/test';

testWithUserSignedUp('user sees an empty standards list', async ({ dashboardPage }) => {
  const standardsPage = await dashboardPage.openStandards();

  // eslint-disable-next-line playwright/no-standalone-expect
  expect(await standardsPage.hasNoStandards()).toBe(true);
});

Example — seed via API, assert via UI

Seed everything not under test through packmindApi (it's faster and less brittle than clicking through setup), then exercise the actual feature in the browser:

import { testWithApi } from '../../fixtures/packmindTest';
import { apiStandardFactory } from '../../domain/apiDataFactories/apiStandardFactory';
import { expect } from '@playwright/test';

testWithApi.describe('packages page', () => {
  testWithApi('lists a standard added to a package', async ({ packmindApi, dashboardPage }) => {
    const standard = await apiStandardFactory(packmindApi);
    // ...seed package referencing standard.id...

    const packagesPage = await dashboardPage.openPackages();
    const packagePage = await packagesPage.openPackage('My package');
    const standards = await packagePage.listStandardsInPackage();

    // eslint-disable-next-line playwright/no-standalone-expect
    expect(standards).toEqual([{ name: standard.name }]);
  });
});

The eslint-disable playwright/no-standalone-expect line is required: the lint rule can't tell that a fixture-extended testWithApi(...) callback is a real test body. Add it on any expect that ESLint flags.

Writing a Page Object

A page object is the typed API a spec uses to talk to one route. Adding one is four mechanical steps — keep them in sync or TypeScript will complain.

1. Declare the interface in src/domain/pages/index.ts. In-app pages extend IPackmindAppPage (gives openStandards, openSettings, etc. for free); pre-login pages extend IPackmindPage.

export interface IBillingPage extends IPackmindAppPage {
  listInvoices(): Promise<{ date: string; amount: string }[]>;
}

2. Implement it in src/infra/pages/BillingPage.ts, extending the matching abstract base, and define expectedUrl() as a RegExp (the project standard — Playwright's glob matching is too loose):

import { IBillingPage } from '../../domain/pages';
import { AbstractPackmindAppPage } from './AbstractPackmindAppPage';

export class BillingPage extends AbstractPackmindAppPage implements IBillingPage {
  async listInvoices(): Promise<{ date: string; amount: string }[]> {
    await this.page.locator('table tbody tr').first().waitFor();
    // ...read rows...
  }

  expectedUrl(): RegExp {
    return /.*\/billing$/;
  }
}

3. Register it in the factory — add a getter to IPageFactory and PageFactory. Navigation methods that land on this page return the page object, so specs chain naturally (dashboardPage.openBilling() → IBillingPage).

4. Prefer data-testid over text/role selectors for app chrome that's likely to be reworded. The codebase exports test-id enums from @packmind/frontend (e.g. SidebarNavigationDataTestId) — reuse them.

Why navigation returns a page object

After any navigation, the factory calls waitForLoaded() (which awaits expectedUrl) before handing back the typed page. That's the project's this.pageFactory()-after-navigation rule: it guarantees the URL actually changed before the next interaction runs, killing a whole class of race conditions. Never page.goto + interact directly in a spec — go through the factory.

Seeding data through the API

When a test needs a resource that already exists in the product, create it via the API rather than clicking through the UI. Add the capability bottom-up:

1. Add myThing: Gateway<ICreateMyThingUseCase>; to IPackmindApi (src/domain/api/IPackmindApi.ts). All gateway methods are typed with Gateway<IXxxUseCase> from @packmind/types.
2. Implement it in PackmindApi (src/infra/api/PackmindApi.ts) using the private post/get helpers — they inject the auth header and assert the status code.
3. Wrap it in an apiXxxFactory under src/domain/apiDataFactories/, reusing the shared @packmind/<domain>/test factory for default field values (see apiStandardFactory.ts / apiPackageFactory.ts for the shape).

This keeps specs declarative: const standard = await apiStandardFactory(packmindApi) instead of a paragraph of POST plumbing.