Build and maintain Playwright tests in hycommerce-e2e

01Overview & architecture

Every test in this repo is assembled from four layers that each have exactly one job. Keeping the boundaries clean is what lets the same flow logic run against four countries and four browsers without duplicating code.

The layered model

Smoke, e2e and integration

• Smoke (tests/smoke/) — fast, focused checks of one storefront surface at a time (cart, PDP, navigation, footer…). These run in parallel and make up the bulk of the suite (13 spec files).
• e2e (tests/e2e/) — broader, multi-page journeys: full purchase flows, real identity-provider login, HyCare sales-admin reordering, registration. Several run serial and/or --workers=1 because they share authenticated state.
• Integration (tests/integration/) — a single data-driven spec that replays the Hycommerce storefront API contract from CSV fixtures, with no browser at all (it uses Playwright's request context, project integration).

Where everything lives

The @/ import alias

tsconfig.json maps @/* to ./src/* (plus the narrower @page-objects/* and @test-data/* aliases). Always import internal modules through the alias instead of relative ../../ chains:

import { test, expect } from '@/fixtures/pages.fixture';
import { CartPage } from '@/page-objects/common/cart.page-object';
import { cartData, getCartData } from '@test-data/smoke/cart.data';

02Environment & setup

The suite talks to real acceptance storefronts behind Cloudflare Access, so setup is mostly about installing browsers and supplying the right credentials and service-token headers before the first run.

Required environment values

03Anatomy of a test

Walking through the real Cart smoke suite shows how the four layers fit together end to end.

1. The test-case — tests/smoke/test-cases/cart.smoke.spec.ts

Imports the fixtures, the step-definition functions, and the test data. Each test is one line of orchestration:

import { test } from '@/fixtures/pages.fixture';
import {
  runCartAutoOpensSmoke,
  runCartBadgeCountSmoke,
  // …other step-definition functions
} from '../step-definitions/cart.steps';
import { cartData, getCartData } from '@test-data/smoke/cart.data';

test.describe('Cart', () => {
  test.describe.configure({ mode: 'parallel' });
  test.setTimeout(cartData.timeoutMs);

  // TcSmokeAcct001: cart auto opens when item is added.
  test('TcSmokeAcct001 - cart auto opens when item added', { tag: ['@quick-smoke'] }, async ({
    page,
    productPage,
    cartPage,
    baseURL,
  }) => {
    await runCartAutoOpensSmoke({ page, productPage, cartPage }, getCartData(baseURL));
  });
});

Naming convention: Tc<Suite><Area><Number> - lowercase descriptive title, e.g. TcSmokeAcct001, TcSmokeCart009, TcSmokeNavg003. The numeric ID stays stable so historical runs in the Reports dashboard can be tracked across renames of the descriptive part. The second options argument, { tag: ['@quick-smoke'] }, is how a test opts into a suite — see Tags, suites & selective runs.

2. The step-definition — tests/smoke/step-definitions/cart.steps.ts

Owns the reusable flow logic and reports readable steps into the trace/report via reportStep:

async function runCartBadgeCountSmoke(
  context: CartSmokeContext,
  data: CartSmokeData
): Promise<void> {
  const { page } = context;
  const preparedCart = await prepareCartWithSingleProduct(context, data);

  await reportStep('Validate the cart badge increments by exactly one added unit', async () => {
    if (preparedCart.mode === 'login-gate') {
      expect(preparedCart.finalCartCount).toBe(preparedCart.initialCartCount);
      return;
    }
    expect(preparedCart.finalCartCount).toBe(preparedCart.initialCartCount + 1);
  });

  await attachVisitedUrls(preparedCart.visitedUrls);
  await attachSmokeContext('cart-badge-count-smoke-context', {
    finalURL: page.url(),
    initialCartCount: preparedCart.initialCartCount,
    finalCartCount: preparedCart.finalCartCount,
    productPath: data.productPath,
  });
}

reportStep, attachVisitedUrls and attachSmokeContext come from src/support/reporting/smoke.report.ts — thin wrappers around Playwright's test.step() and test.info().attach() so every smoke run leaves a structured trail (visited URLs, cart counts, product path) that shows up in the Reports dashboard under each test's attachments.

3. The test data — tests/test-data/smoke/cart.data.ts

function getCartData(baseURL?: string) {
  const country = getStorefrontCountry(baseURL) ?? 'nl';
  const countryConfig = manualTestData.smoke.cart.byCountry[country];

  return {
    timeoutMs: 180_000,
    maxAddToCartAttempts: 3,
    cartOpenTimeoutMs: 12_000,
    quantitySyncTimeoutMs: 20_000,
    productPath: getCountryEnv('TEST_PRODUCT_PATH', country, countryConfig.productPath),
    productNameContains: getCountryEnv('TEST_PRODUCT_NAME_CONTAINS', country, countryConfig.productNameContains),
    cartPath: countryConfig.cartPath,
    supportsAnonymousCart: countryConfig.supportsAnonymousCart,
    quantityInputSelector: 'input[aria-label="Input Number"]:visible',
    increaseButtonSelector: 'button[title="Increase"]:visible',
    decreaseButtonSelector: 'button[title="Decrease"]:visible',
    checkoutButtonPattern:
      /verder naar bestellen|afrekenen|checkout|continuer la commande|zur kasse|.../i,
    // …timeouts and localized text patterns for nl/be/fr/de
  };
}

Test data resolves country from the fixture's baseURL, then layers getCountryEnv('KEY', country, fallback) — a country-suffixed env var, then the bare env var (NL only), then a hardcoded fallback from manualTestData (tests/test-data/manual-test-data.ts / .json). This is why the same cart spec runs unmodified against NL, BE, FR and DE.

4. The page object — src/page-objects/common/cart.page-object.ts

class CartPage extends BasePage {
  async open(path = '/winkelwagen'): Promise<void> {
    await this.goto(path);
    await this.closeBlockingOverlays();
    await this.waitForCartMergeDialogToClose().catch(() => {});
    await expect(this.page).toHaveURL(this.cartUrlPattern);
  }

  async expectCartHasItems(): Promise<void> {
    await expect
      .poll(() => this.hasItems(), {
        timeout: 20_000,
        message: 'Expected the cart to contain at least one line item.',
      })
      .toBeTruthy();
  }
}

Every page object extends BasePage (src/page-objects/common/base.page-object.ts), which supplies a resilient goto(), clickFirstVisible() with a DOM-click fallback, and closeBlockingOverlays() for cookie/privacy/merge-cart dialogs — see Selectors & stability.

Fixtures — how the layers get wired together

• src/fixtures/test.fixture.ts extends the base Playwright test with an auto cookieConsent fixture that hides the country-selection modal, retries flaky page.goto() navigations, blocks the Trengo chat widget by default, and auto-dismisses the cookie banner on every domcontentloaded event.
• src/fixtures/pages.fixture.ts extends test.fixture.ts further and injects one fixture per page object / component (homePage, cartPage, checkoutPage, loginModal, siteHeader…), each a plain new SomePage(page).

import { test, expect } from '@/fixtures/pages.fixture';
// or, for page-level-only tests with no page objects:
import { test, expect } from '@/fixtures/test.fixture';

Use pages.fixture whenever a test needs page objects or components; use the lighter test.fixture for page-level-only checks.

04Writing a new smoke test

Follow the same order every time: data, then selectors, then flow, then the test case itself. That order keeps you from hardcoding a locale string or a selector directly into the spec file.

npx playwright test tests/smoke/test-cases/<area>.smoke.spec.ts --project=chrome
npm run typecheck

05Writing e2e & integration tests

e2e journeys and the integration spec both live outside the smoke tree because they carry different constraints: real authentication, multi-page state, or no browser at all.

e2e journeys

e2e specs (tests/e2e/test-cases/) chain several page objects together — listing → product → cart → checkout, or a full identity-provider login. Where a flow depends on shared authenticated state (impersonation, a single sales-admin session), the describe block runs serial and the npm script pins --workers=1:

test.describe('Order', () => {
  test.describe.configure({ mode: 'serial', timeout: orderData.timeoutMs });

  test(
    'OrderE2E001 - sales admin can impersonate a client and place a HyCare reorder',
    { tag: ['@hycare', '@full-regression', '@requires-auth', '@nl-only'] },
    async ({
      page,
      accountLoginPage,
      identityProviderPage,
      siteHeader,
      salesAdminPage,
      hyCareOrderPage,
      baseURL,
    }) => {
      /* … */
    },
  );
});

identityProviderPage (src/page-objects/common/identity-provider.page-object.ts) drives the real Schippers identity provider login page (not a mocked auth step), asserting the URL matches login.schippers.cloud / *.auth.hycommerce.schippers.cloud before filling the password and submitting. The matching npm script cross-browsers the journey while keeping it serial:

"test:hycare:nl:cross-browser": "playwright test tests/e2e/test-cases/order.e2e.spec.ts --project=firefox --project=chrome --project=safari --project=edge --workers=1"

HyCare currently ships NL-only test data, so playwright.config.ts excludes tests/e2e/test-cases/order.e2e.spec.ts from the BE/FR/DE projects (nlOnlyHyCareSpecs) until matching customer data exists for those storefronts.

Integration: the data-driven API contract spec

tests/integration/test-cases/api-endpoints.integration.spec.ts is a single spec file that generates one Playwright test() per row of every CSV file in tests/integration/testdata/ — no page objects, no browser, just request context calls against the Hycommerce API:

const csvFiles = fs
  .readdirSync(testDataDirectory)
  .filter((fileName) => fileName.endsWith('.csv'))
  .sort((left, right) => left.localeCompare(right));

test.describe('@integration API endpoint coverage', () => {
  test.setTimeout(30_000);

  for (const csvFileName of csvFiles) {
    const rows = readCsvRows(path.join(testDataDirectory, csvFileName));

    for (const row of rows) {
      test(
        `${row.case_id} - ${row.description} [${csvFileName}]`,
        { tag: ['@full-regression'] },
        async ({}, testInfo) => {
          const apiContext = await createStoreRequestContext(playwrightRequest);
          const response = await apiContext.fetch(row.url, createRequestOptions(row));

          expect(response.status()).toBe(Number(row.expected_status));
          // …asserts required_json_path / expected_json_values / min_array_lengths from the row
        },
      );
    }
  }
});

Each CSV row is a self-contained contract check — method, URL, expected status/content-type, and one or more JSON paths that must be populated:

case_id,description,method,url,request_headers,request_body,expected_status,expected_content_type,required_json_path,additional_required_json_paths,expected_json_values,min_array_lengths
IntegrationAPI001,fetch product details,GET,https://acc.api.hycommerce.schippers.cloud/product/web/product/0301313?locale=nl-NL,,,200,application/json,sku,"[""name"",""brand"",""fullSlug""]","{""sku"":""0301313"",""brand"":""MS Schippers""}","{""variants.items"":1}"

To add a new contract check, add a row to an existing CSV (or a new *.csv file — it's picked up automatically) rather than editing the spec. Run the whole set with npm run test:integration, which targets the dedicated integration Playwright project (no browser use.baseURL beyond the default storefront origin).

06Tags, suites & selective runs

Every test carries one suite tag and, where relevant, one or more scoping tags. The suite tags decide which npm script picks the test up; the scoping tags decide which country/browser projects it runs under.

Suite tags

Scoping tags

Direct Playwright invocations

npx playwright test --grep @quick-smoke --project=chrome --project=chrome-be
npx playwright test --grep @quick-regression --project=chrome --project=chrome-be
npx playwright test --grep @full-regression --project=chrome --project=chrome-be
npm run test:smoke:cart
npm run test:hycare:nl:cross-browser
npm run test:storefront-journeys

Browser projects are named <browser> for NL and <browser>-<country> for BE/FR/DE (e.g. chrome, chrome-be, firefox-fr, edge-de) — 4 browsers × 4 countries, plus the standalone integration project. Narrow either axis with PLAYWRIGHT_BROWSERS / PLAYWRIGHT_COUNTRIES or with explicit --project flags.

07Selectors & stability best practices

These tests run against live acceptance storefronts in four languages, so resilience isn't optional — a hardcoded English label or a one-shot waitForTimeout will flake the first time content or network timing shifts.

08Maintaining tests & CI

Every local or CI run produces this same dashboard, so the Reports page is both your results view and your primary triage tool.

Reporter & dashboard

scripts/reporting/dashboard.reporter.js is registered as a Playwright reporter in playwright.config.ts. After every run it writes a static site to playwright-report/ (this Manual page, the Reports overview, and the build-copied Coverage page) and retains run history in .report-history/. If REPORT_DATABASE_URL is set, the same run is also persisted to Postgres, and npm run report:rebuild can rehydrate the latest stored runs and regenerate the site without re-running any tests.

GitHub Actions workflows

Each of the four deploy workflows follows the same pipeline:

1. Validates the Postgres report-history connection (npm run report:test-db).
2. Resolves the selected browsers, countries and environment override from the workflow inputs.
3. Runs the corresponding Playwright command.
4. Persists the latest run to Postgres.
5. Rebuilds the static dashboard and uploads it as a workflow artifact.
6. Deploys playwright-report/ to Azure Static Web Apps and writes the live dashboard URL to the job summary.

Manual workflow dispatch defaults to chromium on NL with the current environment (other choices: acc, tst, dev). Required secrets: AZURE_WEBBAPP_DEPLOYMENT_TOKEN, BASE_URL, BASE_URL_BE, CF_ACCESS_CLIENT_ID, CF_ACCESS_CLIENT_SECRET, REPORT_DATABASE_URL.

Triaging a flaky live-site failure

1. Open the failed test in the Reports dashboard — check the failure screenshot, trace, and any attachSmokeContext payload (visited URLs, cart counts, etc.) first.
2. Reproduce locally against the same browser/country project: npx playwright test <spec> --project=<browser>[-<country>] --headed.
3. Decide what changed: storefront copy/price drift, a genuine regression, or infra reachability (Cloudflare Access creds, acceptance environment downtime).
4. If it's a real timing flake, tighten the wait (a more specific expect.poll() condition or locator) rather than adding blind retries — the base config runs with retries: 0 outside CI-specific overrides.
5. If it's content drift, update the test-data pattern/value (and tests/test-data/manual-test-data.ts/.json if it's a shared fallback) rather than the assertion logic.

Maintenance checklist

• Run npm run typecheck before pushing — tsconfig.json covers playwright.config.ts, src/**/*.ts and tests/**/*.ts.
• Run npm run validate:test-data after touching tests/test-data/manual-test-data.json to make sure every country entry is complete.
• Keep .env.example in sync whenever a test introduces a new environment variable.
• Double-check the suite tag and any scoping tags (@nl-only/@be-only/@not-fr) match where the flow is actually expected to run.
• When adding a page object, confirm it's registered in src/fixtures/pages.fixture.ts if any spec needs to request it as a fixture.
• Prefer updating an existing CSV row over hand-editing the integration spec when an API contract changes.

09Building tests with GitHub Copilot

This repo is set up so GitHub Copilot writes tests that already follow the layered conventions above. There are three files to know, a recommended mode and model, and a one-command way to scaffold a new test.

The files Copilot uses

Recommended model

Which Copilot features to use

• Agent mode — the create/edit mode that can touch several files and run the test. Use it for building tests (Ask mode is only for questions).
• Context references — #file:<path> to pin a specific file, #codebase (or @workspace) to let Copilot search the repo, and #selection for highlighted code.
• Prompt files — /new-smoke-test runs the reusable prompt above. Requires the chat.promptFiles setting (on by default in current Copilot).

Workflow

Example prompts

/new-smoke-test
area: product comparison
behaviour: adding a third product keeps the comparison bar stable and removable
tag: @full-smoke

#file:docs/AI-TEST-AUTHORING-GUIDE.md #codebase
Add a @quick-smoke test that asserts the PDP breadcrumb links back to its category
listing. Follow the layering: selectors only on the product page object, assertions in
the step-definition, wiring only in the spec. Then typecheck and run it on Chrome.