Test Standards

Test Standards

Critical

• Imports: Import test and expect from fixtures/pom/test-options.ts. NEVER from @playwright/test in spec files.
• Single-tag rule: Each test has exactly one tag chosen from @smoke | @sanity | @regression | @e2e | @api | @destructive. NEVER combine tags. NEVER use @functional. NEVER put tags on test.describe() blocks.
• @destructive is the heaviest tag and always wins — but only for shared/global state. A test that mutates state other tests or users depend on (locale, permissions, roles, guest access, feature flags, global settings) is tagged only @destructive. A test that creates and deletes only its own data is isolated, not destructive — tag it by importance (@smoke / @sanity / @regression / @e2e / @api).
• Every state-mutating test must have test.afterEach() or test.afterAll() cleanup that reverts the change — both @destructive shared-state tests and isolated tests that write their own data.
• Web-first assertions only (await expect(locator).toBeVisible(), .toHaveText(), .toBeEnabled(), .toHaveCount(...), etc.). NEVER page.waitForTimeout(...).
• Use test.step() for Given/When/Then structure when a test has more than one distinct phase (setup, action, assertion).
• Tests must be independent. No ordering dependencies, no shared mutable state across tests.
• NEVER commit explore-only or debug test files (.spec.ts containing console.log(await page.content()), temporary probes, etc.).
• Static test data is imported from .ts modules (test-data/static/**/*.ts) via named as const exports. NEVER .json.
• Dynamic happy-path data comes from Faker factories (test-data/factories/{area}/); universal type-mismatch arrays from test-data/static/util/invalid-values.ts; domain-specific curated sets from test-data/static/{area}/*.ts. See the data-strategy skill.
• Page objects are consumed via the fixture (async ({ appPage }) => ...). NEVER new PageObject(page) inside a test.
• After adding or modifying a test file, run the affected tests and confirm zero failures before finishing the task.

Test File Location and Type

{area} is a placeholder. Before creating or referencing any path below, run ls tests/ to discover the real subdirectory names in this repo (e.g., front-office, back-office) and use those instead.

Functional vs E2E distinction:

• A functional test isolates and verifies a single behaviour (e.g., "adding a todo updates the count"). Each test covers one thing.
• An E2E test chains multiple features together in one test that mirrors a real user journey from start to finish (e.g., add items → complete → filter → clear → verify final state). An E2E file typically contains one or a few high-level scenario tests.

Instructions

Phase 1: Classify the test type and pick the location

Determine whether the work is a functional, E2E, API, or setup test, then run ls tests/ to resolve {area} and place the file in tests/{area}/<type>/[name].spec.ts (or tests/{area}/[name].setup.ts for setup). Never guess the area.

Phase 2: Write the imports and file skeleton

Every spec file starts with:

import { expect, test } from '../../../fixtures/pom/test-options';

test.describe('Feature Name', () => {
    test.beforeEach(async ({ appPage }) => {
        await appPage.openHomePage();
    });

    test(
        'should do expected behavior',
        { tag: '@smoke' },
        async ({ appPage }) => {
            // ...
        }
    );
});

• Imports come from fixtures/pom/test-options.ts, not @playwright/test.
• test.describe(...) groups related tests; the describe name has no tag.
• test.beforeEach(...) handles navigation and per-test setup (see Phase 7 for destructive cleanup and Phase 6 for resetStorageState).

Phase 3: Tag the test (single-tag rule)

Each test gets exactly one tag. Pick the right one:

@destructive overrides any other importance tag — for shared/global state mutation only. If a test would otherwise be @smoke but changes global settings, it is tagged only @destructive. A test that creates and cleans up only its own data is isolated, not destructive — keep its importance tag (@smoke/@regression/@api/…).

// CORRECT
test('should login successfully', { tag: '@smoke' }, async ({ appPage }) => {
    /* ... */
});
test('should validate cart flow', { tag: '@e2e' }, async ({ checkoutPage }) => {
    /* ... */
});
test('should return user profile', { tag: '@api' }, async ({ apiRequest }) => {
    /* ... */
});
test(
    'should delete all users',
    { tag: '@destructive' },
    async ({ apiRequest }) => {
        /* ... */
    }
);

// WRONG -- @functional is not a valid tag
test('should login', { tag: '@functional' }, async ({ appPage }) => {
    /* ... */
});

// WRONG -- combining tags is forbidden
test(
    'should delete all users',
    { tag: ['@regression', '@destructive'] },
    async () => {
        /* ... */
    }
);

// WRONG -- tag belongs on the test, not the describe
test.describe('Feature @smoke', () => {
    /* ... */
});

Phase 4: Structure the test body with test.step

Use test.step() to split the test into Given / When / Then blocks. This produces readable HTML reports and makes debugging faster.

test(
    'should show error for invalid login',
    { tag: '@regression' },
    async ({ appPage }) => {
        await test.step('GIVEN user is on the login page', async () => {
            await expect(appPage.loginButton).toBeVisible();
        });

        await test.step('WHEN user enters invalid credentials', async () => {
            // generateLoginCredentials() is illustrative -- build the factory
            // via the data-strategy skill or use process.env.* + a known-bad password.
            const { email, password } = generateLoginCredentials();
            await appPage.login(email, password);
        });

        await test.step('THEN error message is displayed', async () => {
            await expect(appPage.errorMessage).toBeVisible();
        });
    }
);

For API tests with multiple calls, test.step is mandatory — see the api-testing skill (Phase 4).

Phase 5: Use web-first assertions

Web-first assertions auto-wait and retry until the condition is met or a timeout elapses. Never use hard waits.

// CORRECT -- web-first assertions
await expect(locator).toBeVisible();
await expect(locator).toHaveText('Expected text');
await expect(locator).toBeEnabled();
await expect(locator).toHaveCount(3);

// FORBIDDEN -- hard waits mask real timing issues
await page.waitForTimeout(1000);

If a response must be awaited, use page.waitForResponse(...) inside a page-object action method, not inside the spec.

Phase 6: Handle setup / teardown and storage state

• Use test.beforeEach() for per-test navigation and setup.
• Use test.afterEach() for per-test cleanup when fixtures don't handle it.
• Use the resetStorageState fixture when testing login/logout flows so each test starts unauthenticated:

test.beforeEach(async ({ resetStorageState, appPage }) => {
    await resetStorageState();
    await appPage.openHomePage();
});

For API-driven setup/teardown reused across many files, see the api-testing skill (Phase 8, helper-fixture rule of thumb).