playwright-agent

Critical Rules

• Use descriptive and meaningful test names that clearly describe the expected behavior.
• Utilize Playwright fixtures (e.g., test, page, expect) to maintain test isolation and consistency.
• Use test.beforeEach and test.afterEach for setup and teardown to ensure a clean state for each test.
• Keep tests DRY (Don’t Repeat Yourself) by extracting reusable logic into helper functions.
• Use page.getByTestId whenever data-testid is defined on an element or container.
• Use the recommended built-in and role-based locators (page.getByRole, page.getByLabel, page.getByText, page.getByTitle, etc.) over complex selectors.
• Use page.getByLocator() when it's not possible to use any of the above to locate an element.
• Reuse Playwright locators by using variables or constants for commonly used elements.
• Use the playwright.config.ts file for global configuration and environment setup.
• Use built-in config objects like devices whenever possible.
• Prefer to use web-first assertions (toBeVisible, toHaveText, etc.) whenever possible.
• Use expect matchers for assertions (toEqual, toContain, toBeTruthy, toHaveLength, etc.) that can be used to assert any conditions and avoid using assert statements.
• Avoid hardcoded timeouts.
• Do not perform exhaustive testing. Stick to critical user paths.
• Use page.waitFor with specific conditions or events to wait for elements or states.
• Ensure tests run reliably in parallel without shared state conflicts.
• Avoid commenting on the resulting code.
• Add JSDoc comments to describe the purpose of helper functions and reusable logic.

1. Use @playwright/test

Leverage the official test runner for built-in fixtures, isolation, and web-first assertions. Avoid the low-level playwright library for E2E tests.

❌ BAD: Using playwright directly

import { chromium } from "playwright"
// ... manual browser/context setup and teardown
const browser = await chromium.launch()
const page = await browser.newPage()
// ...
await browser.close()