A drifted suite looks healthy from the outside. Four hundred tests, a class per page, ninety-four percent pass rate, a green badge in the README. Then production breaks: a coupon applies twice, the order total is wrong, and nobody can say whether a test covered it. Somebody checks. Eleven tests for the settings page, six for the avatar upload, two for checkout — and both of those stop at the order summary because the payment provider was \"hard to automate\".
\n\nNothing in that suite is badly written. Every page object is tidy. The problem is that page objects made every screen equally easy to test, and equal ease produced equal coverage of things carrying wildly unequal consequences.
\n\nRead the Playwright page on the pattern carefully. It says large test suites \"can be structured to optimize ease of authoring and maintenance\" and that page object models \"are one such approach\". The stated benefits are a higher-level API for authoring and locators captured in one place for maintenance. That is a claim about duplication, not about coverage.
\n\nThe pattern is also not privileged in the tooling. There is no PageObject base class in the library and nothing in the runner knows what a page object is; the fixtures guide simply shows them supplied as fixtures so the runner constructs them for you. It is your code, so it can be shaped by anything you like — including something other than the site map.
Keep page objects where they earn their place: holding a locator that appears in nine tests. Stop using the file tree of page classes as the answer to \"what does this suite protect?\"
\n\nRisk is impact multiplied by likelihood, and both halves need evidence rather than a vote.
\n\nImpact answers: if this fails silently for a day, what does it cost? Use categories your business already tracks — money moved, data corrupted, users locked out, regulatory exposure. \"Users cannot pay\" and \"the avatar crops badly\" are not two points apart on a five-point scale; they are different kinds of event.
\n\nLikelihood is not a guess. Three sources you already have: change frequency (git log --since=90.days --name-only over the app source, not the test source), defect history in your tracker, and integration count — every third party, queue or feature flag in a path multiplies the ways it can break.
| Capability | Impact | Likelihood signal | Decision |
|---|---|---|---|
| Checkout with a discount code | Money moved incorrectly | 18 commits/90d, 2 payment integrations | End-to-end, every commit |
| Password reset by email | Users locked out | 3 commits/90d, mail provider | End-to-end, nightly |
| Settings page field validation | Cosmetic, self-correcting | 1 commit/90d | Component/unit tests only |
| Marketing footer links | Negligible | CMS-driven, changes weekly | Do not automate |
The output is not a document. It is a list of named capabilities with a tier, which becomes the folder structure, the tags and the CI schedule. If the register never changes how tests run, it was theatre.
\n\nThe drift has a mechanism, worth naming precisely because it is not laziness.
\n\nA page object exposes a surface — every field, toggle and button on that screen becomes a method. A visible surface invites coverage; an untested method reads like a gap. So the settings page, thirty controls and no consequences, accumulates thirty tests. Checkout, three controls and all the consequences, accumulates three.
\n\nSecond, page objects are cheapest to write for self-contained screens. Checkout needs a seeded cart, a funded test account, a payment sandbox and an inventory hold; the settings page needs a login. Setup cost is inversely correlated with business risk in almost every product, so a suite following the path of least resistance ends up systematically inverted.
\n\nThird, page-shaped assertions test the page, not the outcome. Contrast these two tests of the same flow:
\n\n// Page-shaped: asserts that the checkout screen rendered.\ntest('checkout page shows totals', async ({ page }) => {\n const checkout = new CheckoutPage(page);\n await checkout.goto();\n await expect(checkout.subtotal).toHaveText('$120.00');\n await expect(checkout.taxRow).toBeVisible();\n await expect(checkout.payButton).toBeEnabled();\n});Every assertion above passes if the payment capture silently fails, because the page renders identically either way. The risk-shaped version asserts what the business would notice:
\n\n// Risk-shaped: asserts that money moved and the order exists server-side.\ntest('discounted order is captured at the discounted amount', {\n tag: ['@critical', '@payments'],\n annotation: { type: 'risk', description: 'impact=revenue likelihood=high' },\n}, async ({ page, request, seededCart }) => {\n await page.goto(`/checkout/${seededCart.id}`);\n await page.getByLabel('Discount code').fill('SAVE25');\n await page.getByRole('button', { name: 'Apply' }).click();\n await expect(page.getByTestId('order-total')).toHaveText('$90.00');\n await page.getByRole('button', { name: 'Pay now' }).click();\n await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();\n\n // The assertion that actually protects revenue.\n const order = await request.get(`/api/orders/${seededCart.id}`);\n expect(order.ok()).toBeTruthy();\n expect(await order.json()).toMatchObject({ status: 'captured', amountCents: 9000 });\n});The request fixture there is the built-in APIRequestContext, which inherits baseURL and extraHTTPHeaders from your config — a server-side post-condition costs one line, not a second HTTP client.
Replace \"one file per page\" with \"one file per capability, one test per risk\". A journey helper spans whatever pages the journey touches, and it is allowed to call three page objects — that is the correct dependency direction.
\n\nPlaywright's tool for making journeys readable in the report is test.step(). The non-obvious part is the box option, added in v1.39. Without it, a failure inside a shared helper points the error at a line inside the helper — the same line for every one of the forty tests that call it. With { box: true }, the error points at the call site in the failing test.
// journeys/purchase.ts — a capability-shaped helper, not a page-shaped one.\nimport { expect, type Page } from '@playwright/test';\nimport { test } from '@playwright/test';\n\nexport async function completePurchase(\n page: Page,\n opts: { cartId: string; discount?: string },\n) {\n await test.step(`Purchase cart ${opts.cartId}`, async () => {\n await page.goto(`/checkout/${opts.cartId}`);\n if (opts.discount) {\n await page.getByLabel('Discount code').fill(opts.discount);\n await page.getByRole('button', { name: 'Apply' }).click();\n }\n await page.getByRole('button', { name: 'Pay now' }).click();\n await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();\n }, { box: true, timeout: 60_000 });\n}The step-level timeout option (v1.50) is the other half: a journey step that must finish in sixty seconds says so without raising the whole test timeout and hiding a slow regression elsewhere.
Push the setup for these journeys below the UI. A fixture that seeds through the API stops a checkout test from failing because the sign-up form changed:
\n\nimport { test as base } from '@playwright/test';\n\ntype Fixtures = { seededCart: { id: string } };\n\nexport const test = base.extend<Fixtures>({\n seededCart: async ({ request }, use) => {\n const created = await request.post('/api/test/carts', {\n data: { items: [{ sku: 'DESK-01', qty: 1, priceCents: 12000 }] },\n });\n const cart = await created.json();\n await use(cart);\n await request.delete(`/api/test/carts/${cart.id}`);\n },\n});A tier that only exists in a spreadsheet decays. Encode it where the runner can act on it.
\n\nTags go in the test declaration or in the title with an @ prefix, filtered with --grep. Two facts worth memorising: --grep \"@critical|@payments\" is a logical OR, and AND requires regex lookaheads — --grep \"(?=.*@critical)(?=.*@payments)\". There is no dedicated AND syntax.
Projects bind a tier to an execution policy, and dependencies guarantees ordering:
// playwright.config.ts — tiers as projects, not as folders alone.\nimport { defineConfig } from '@playwright/test';\n\nexport default defineConfig({\n fullyParallel: true,\n projects: [\n { name: 'setup', testMatch: /.*\\.setup\\.ts/, teardown: 'cleanup' },\n { name: 'cleanup', testMatch: /global\\.teardown\\.ts/ },\n {\n name: 'critical', // runs on every push\n grep: /@critical/,\n retries: 0, // a retry here hides a real defect\n use: { trace: 'on' },\n dependencies: ['setup'],\n },\n {\n name: 'extended', // runs nightly\n grepInvert: /@critical/,\n retries: 2,\n use: { trace: 'on-first-retry' },\n dependencies: ['setup'],\n },\n ],\n});Three details there are load-bearing. teardown on the setup project runs after all dependent projects finish, so cleanup needs no separate CI step. Filtering with --grep or --shard selects only the primary tests, but dependency projects still run — pass --no-deps to skip them. And retries: 0 on the critical project is the point of the tier: a flaky pass on a revenue path is indistinguishable from a real intermittent defect.
Set fullyParallel: true when you shard. Without it Playwright shards at file granularity, so one fat capability file lands entirely in one shard and the tier is as slow as its largest file.
The pyramid is not a rule about ratios. It is a statement that a test should run at the lowest level that can still observe the failure you care about.
\n\nField validation on a form is observable in a component test. \"The discount is applied before tax, and the captured amount matches\" is not — it spans the browser, the pricing service and the payment provider, and only an end-to-end test sees the composition. Push the case down when the failure is local; keep it up when the failure lives in a seam between systems.
\n\nThe costliest seam is the third party you do not control. Playwright's best-practices guide is explicit: do not test third-party dependencies, and use routing to guarantee the response. That is a risk decision, not just a speed one — a test failing because of someone else's cookie banner trains the team to ignore red.
\n\ntest('order survives a slow fraud-check response', async ({ page }) => {\n await page.route('**/fraud-check/v2/score', async route => {\n await new Promise(r => setTimeout(r, 3_000));\n await route.fulfill({\n status: 200,\n contentType: 'application/json',\n body: JSON.stringify({ decision: 'review', score: 71 }),\n });\n });\n await page.goto('/checkout/seed-1');\n await page.getByRole('button', { name: 'Pay now' }).click();\n await expect(page.getByText('We are reviewing your order')).toBeVisible();\n});That buys a deterministic test of your behaviour in a state the real provider produces rarely and on its own schedule — a state previously untested precisely because it was unreachable through the UI.
\n\nThe hardest architectural decision is subtraction. Four rules that hold up:
\n\nWhen you retire a test, delete it. If it must stay visible, use the annotation that describes reality: test.fixme() marks it failing and does not run it, which is what you want when the test is slow or crashes; test.fail() runs it and complains if it unexpectedly passes; test.skip() means \"not applicable in this configuration\". A commented-out block means nothing.
--only-changed [ref] selects test files changed between HEAD and the ref. It does not compute which tests exercise changed application code — Playwright has no such dependency graph. Using it as your risk-based selection strategy means a pure application change runs nothing.The register that never re-scores. Tiers assigned once at kick-off go stale the first time a service is rewritten, because scoring lives outside the workflow. Re-derive likelihood from git log on the application source each quarter and diff it against the current tags; anything with commits and no @critical tag is a promotion candidate.
Tier inflation. Every team wants its area in the critical project, so within a year that tier is the whole suite and fast feedback is gone. The cause is a tier with no budget. Cap the critical project by wall-clock time — if it exceeds ten minutes, something is demoted before anything is added.
\n\nRetries laundering real defects. A critical capability configured with retries: 2 reports intermittent revenue bugs as green. The cause is a global retry setting applied to a tier that should not have one. Use per-project retries, and turn on --fail-on-flaky-tests in the critical job so a test that only passes on retry fails the build.
Journeys collapsed into one giant test. Reorganising by journey tempts people to write a single test that signs up, browses, buys and refunds. When it fails at step nine you learn nothing about steps one to eight, and the whole thing reruns. The cause is confusing \"structure by journey\" with \"one test per journey\". One test per risk: capture amount and refund amount are two risks, so two tests, even though both traverse checkout.
\n\nTake one hour today. Run npx playwright test --list and paste the output into a sheet next to a second column: the business consequence of that test failing to catch a defect. Any test whose consequence column reads \"none that I can name\" is a deletion candidate.
Then run git log --since=90.days --name-only --pretty=format: over your application source, count changes per directory, and check whether the three most-changed areas have a test tagged @critical. Capture two numbers: tests you could not justify, and high-change areas with no critical-tier coverage. That is the argument for the restructure, and it is more persuasive than any diagram.
Does this mean I should delete my page objects? No. Keep them as locator repositories consumed by journey helpers. What changes is that no page object gets a test file named after it, and the count of methods on a class stops being a coverage target.
\n\nHow do I score risk when I have no defect history? Use change frequency and integration count alone; both are available on day one. Add defect history as it accumulates. Do not delay the structure waiting for perfect data — the ranking is what matters, not the absolute score.
\n\nWhere do exploratory findings fit? A bug found by hand is direct evidence that a capability's likelihood is higher than you scored it. Re-score first, then decide whether the specific regression test is worth writing; often the correct response is a new critical-tier journey rather than a narrow test for that one bug.
\n\nShould tiers be separate projects or separate config files? Projects. One config keeps the shared setup dependency, one report, and one --project critical invocation in CI. Separate config files duplicate the setup project and drift apart.
teardown, per-project retries, and the rule that filtering still runs dependencies unless --no-deps is passed.--grep OR versus lookahead AND, and the semantics of skip, fail and fixme.test.step() with the box (v1.39) and timeout (v1.50) options.request fixture and its inheritance of baseURL and extraHTTPHeaders.fullyParallel.--only-changed, --fail-on-flaky-tests, --no-deps, --shard.