DevOps & Tooling · Any coding agent
Playwright End-to-End Testing ARCHITECTURE.md
An ARCHITECTURE.md for Playwright End-to-End Testing: module responsibilities, data flow and the boundaries code changes must keep.
- Path
- ARCHITECTURE.md
- Loads
- Read when referenced
- Format
- Markdown (.md)
- Used by
- Any coding agent
What this file tells the agent
ARCHITECTURE.md describes module responsibilities, state boundaries and data flow, so a coding agent knows where code belongs before it changes anything. Point to it from CLAUDE.md or AGENTS.md so agents read it.
- Strictly ban hardcoded delays (page.waitForTimeout()); rely exclusively on Playwright web-first auto-waiting assertions (expect(locator).toBeVisible()).
- Prioritize user-facing accessible locators: page.getByRole(), page.getByLabel(), and page.getByTestId(); never write fragile CSS selectors or brittle XPaths.
- Encapsulate multi-step interactions inside modular Page Object Models (POM) with typed parameters.
- Ensure total test isolation: authenticate via storage state (storageState) instead of repeating manual UI logins in every test.
- Configure trace viewer and video capture on first retry (trace: 'on-first-retry') for painless CI debugging.
Code to avoid, and what to write instead
The rule steers the agent away from the left and toward the right.
// Flaky: Brittle selectors, arbitrary sleep timeouts, and no auto-waiting
test("bad test", async ({ page }) => {
await page.goto("/catalog");
await page.click("div.col-md-4 > button:nth-child(2)"); // Breaks on minor CSS tweak!
await page.waitForTimeout(5000); // Flaky anti-pattern!
const text = await page.innerText("#cart-total");
expect(text).toBe("1");
});import { test, expect } from "@playwright/test";
test.describe("Checkout Flow", () => {
test("allows user to complete cart purchase", async ({ page }) => {
await page.goto("/catalog");
// Accessible, user-facing locators
await page.getByRole("button", { name: "Add to Cart" }).first().click();
await page.getByRole("link", { name: "Cart (1)" }).click();
// Auto-waiting assertions
await expect(page.getByRole("heading", { name: "Your Shopping Cart" })).toBeVisible();
await page.getByRole("button", { name: "Proceed to Checkout" }).click();
await expect(page).toHaveURL(/.*checkout/);
});
});Install it in one command
- 01
Go to your project root
The file goes at ARCHITECTURE.md, relative to the root.
- 02
Download the file
Run the command on the right. It downloads this preset and writes the file.
- 03
Make sure it gets used
Agents read it when your CLAUDE.md or AGENTS.md points to it. Add a line such as "Read ARCHITECTURE.md before structural changes".
$ curl -fsSL "https://www.devscratchpad.tech/api/raw/architecture-md/playwright-e2e" -o "ARCHITECTURE.md"
writes ARCHITECTURE.md
ARCHITECTURE.md
To write the file from your own code instead, use Read your code or Convert Legacy Rules in the editor above.
More for Playwright End-to-End Testing
Questions
- What belongs in ARCHITECTURE.md?
- How the main modules relate, how state and data flow, and the boundaries every change must keep.
- How does ARCHITECTURE.md help AI agents?
- It tells them where code belongs and which boundaries to keep, so they are less likely to add circular dependencies or skip layers. Point to it from CLAUDE.md or AGENTS.md so they read it.