Frontend Playwright E2E

Playwright E2E

Default to Vitest for unit/component work (see .claude/skills/testing_guidelines.md). Use Playwright for integration, e2e, and live testing. For ports, env file, and stack commands, read .claude/skills/frontend-overlay/SKILL.md.

MCP workflow

Use the configured Playwright MCP to manually inspect the relevant UI workflow before writing or changing an E2E test. Use accessible snapshots and locators, and reuse the existing commands and utilities afterward. When a browser failure is not explained by the Playwright trace, use Chrome DevTools MCP to inspect console messages, network requests, layout, or performance. Record the MCP validation performed in the handoff; never print credentials or secret values.

Writing tests

Begin Playwright test names with "should". Prefer editing existing specs and reusing playwright/commands/ over new helpers. Create a generic command when a pattern repeats.

Environment

Create playwright/.env (never commit secrets; never print values in chat):

PLATFORM_UI=http://localhost:4100
PLATFORM_USERNAME=your_username
PLATFORM_PASSWORD=your_password

Also used (overlay / shell):

export PLATFORM_SERVER='https://localhost:443'
# Standalone services if needed
export AWX_SERVER='https://localhost:8043'
export EDA_SERVER='http://localhost:8000'
export HUB_SERVER='http://localhost:5001'

Prerequisites: Node.js 20+ (engines in package.json). Live UI is typically https://localhost:4100.

Test structure

Always use at least one top-level describe block:

import { test, expect } from '@playwright/test';
import { setupBefore, setupAfter } from '../../commands/setup';

test.beforeEach(setupBefore({ path: '/your/path' }));
test.afterEach(setupAfter);

test.describe('Feature Name - Description', () => {
  test('should do the user-visible thing', { tag: ['@not_mock'] }, async ({ page }) => {
    // test body
  });
});

Test type guidelines

Critical Playwright rules

1. Use data-testid (NOT data-cy)

// BEST
await page.getByTestId('content-type').click();

// AVOID
await page.locator('[data-cy="content-type"]').click();

2. Selector best practices

await page.getByRole('textbox', { name: 'Name', exact: true }).fill('value');
await expect(page.locator('dialog').getByText('Success')).toBeVisible();
await page.getByRole('button', { name: 'Submit' }).click();

• exact: true when similar text exists (e.g. "Name" and "Name @ timestamp")
• Scope to containers (dialog, main, nav) when elements appear more than once
• Check playwright/commands/ for utilities before writing custom logic
• Search existing tests: rg "pattern" playwright/tests/

3. Table row selection — critical

Always use utilities in playwright/commands/ when available. Tests may run where data is paginated off screen. clickTableRow() / getTableRow filter so rows are not flaky.

import { getTableRow } from '../../../commands/getTableRow';

await clickTableRow({ filterLabel: 'Name', text: credentialTypeName }, page);

// NEVER — fails due to pagination
const roleRow = page.getByRole('row').filter({ hasText: roleName });

4. API response interception for dynamic values

Capture API-generated values instead of guessing patterns:

const copyResponsePromise = page.waitForResponse(
  (response) => response.url().includes('/copy/') && response.status() === 201
);

await page.getByRole('menuitem', { name: 'Duplicate template' }).click();

const copyResponse = await copyResponsePromise;
const copiedResource = (await copyResponse.json()) as ResourceType;
const copiedName = copiedResource.name;

5. Validate after writing — critical

Always run the spec after creating/updating it:

cd playwright && npx playwright test tests/path/to/test.spec.ts --project 'live chromium' --max-failures=1 --retries=0

cd playwright && npx playwright test tests/path/to/test.spec.ts --project 'live chromium' --debug

Never conclude test work until all tests pass and lint/TypeScript issues are resolved.

Do not start a second UI if port 4100 is already bound. To launch a run without dumping secrets, use the Running tests wizard below.

6. Web-first assertions & auto-waiting

expect(locator) assertions auto-retry until they pass or time out, and locator actions auto-wait for the element to be actionable. Rely on that — never add manual sleeps.

// GOOD — retries until the element appears / has the text
await expect(page.getByRole('heading', { name: 'Details' })).toBeVisible();
await expect(page.getByTestId('status')).toHaveText('Successful');

// AVOID — arbitrary sleep, flaky and slow
await page.waitForTimeout(3000);
expect(await page.getByTestId('status').textContent()).toBe('Successful');

Prefer waitForResponse (see rule #4) over waitForTimeout when you need to wait for data.

Common anti-patterns

• Hard sleeps — waitForTimeout() to "let things settle". Use a web-first assertion or waitForResponse instead.
• Manual retry/poll loops — re-implementing what expect(locator) already does. Assert on the locator.
• Reading then asserting — expect(await locator.textContent()) does not retry. Use await expect(locator).toHaveText(...).
• Asserting on detached elements — after a navigation or re-render, re-query the locator; do not hold a stale handle.
• Acting after navigation with no wait — follow a navigation with a web-first assertion on the new page before interacting.

Test development methodology

Validate workflows manually with browser automation (Playwright MCP) before writing tests:

1. Navigate the full user workflow
2. Identify selectors from snapshots
3. Test each interaction
4. Verify page state after actions
5. Identify dynamic values that need API interception
6. Write tests from verified selectors
7. Run tests as final validation

This avoids write → run → fix selector loops.

Browser setup:

1. Navigate to https://localhost:4100 (HTTPS)
2. SSL warning: type thisisunsafe on the warning page, or Advanced → Proceed
3. Log in with PLATFORM_USERNAME / PLATFORM_PASSWORD from playwright/.env. Never print those values (including any default in the env file).

Playwright MCP hits the same SSL warning on https://localhost:4100. Bypass it with thisisunsafe before interacting with the UI.