A deep technical breakdown of enterprise-grade Playwright framework design — plus where to get the full blueprint
📘 Get the book: Playwright Framework Design with TypeScript by Himanshu Agarwal — 54 pages, 1.63 MB, instant download.
🎁 Better deal: The Complete AI Playwright + TypeScript Mastery Bundle — 4 books, zero-to-enterprise-to-AI-powered-testing curriculum, one price.
Table of Contents
- Why "writing tests" and "designing a framework" are different jobs
- The real cost of framework rot
- Page Object Model vs Component Object Model — and why most teams implement both wrong
- Fixtures and hooks: the dependency-injection layer nobody documents
- Environment configuration across dev, staging, and production
- Execution strategy: multi-browser, parallelism, and sharding
- Authentication, storage state, and session reuse at scale
- API mocking and network interception
- The UI edge cases that break frameworks: iframes, multi-tab, Shadow DOM
- Data-driven testing patterns
- Reporting, logging, screenshots, video, and trace capture
- Production-grade folder structure — the full breakdown
- What separates a framework from a folder of tests
- Who this book is actually for
- Inside the book — chapter-by-chapter
- Why the bundle is the smarter buy
- FAQ
- Common framework anti-patterns and how to fix them
- CI/CD integration for a mature Playwright framework
- Migrating an existing suite without a rewrite
- Rolling this out across a multi-team org
- A framework health checklist
- Final word
Why "writing tests" and "designing a framework" are different jobs
Every mid-level engineer can write a Playwright test. page.goto(), a couple of locator() calls, an expect(), done. That's the easy 20% of test automation, and it's the part every tutorial, blog post, and YouTube video covers to death.
The other 80% — the part that actually determines whether your test suite survives contact with a real product team — is architecture. It's the decisions nobody notices until they're missing:
- What happens when the same button exists in 40 different test files and the QA lead renames it?
- What happens when your suite goes from 50 tests to 800, and a full run takes 45 minutes instead of 4?
- What happens when three different engineers each build their own way of logging in, and none of them agree?
- What happens when a widget your tests depend on lives inside an iframe that a third-party vendor controls?
- What happens six months from now, when the person who wrote the framework leaves the team?
None of this is covered by "how do I click a button in Playwright." It's covered by framework design — the same discipline that separates a script from a system in any part of software engineering. Test automation is not exempt from good architecture; if anything it's punished harder for skipping it, because a bad test framework doesn't just slow down feature work, it actively lies to the team about whether the product works.
This is the gap Playwright Framework Design with TypeScript by Himanshu Agarwal is built to close. It isn't another "getting started with Playwright" book. It assumes you already know how to write a test and teaches you how to build the thing that holds hundreds of them together without collapsing.
There's a useful analogy from mainstream software engineering: nobody calls someone who can write a single React component a "frontend architect." Writing a component and designing a component library, a state-management strategy, and a build pipeline a 40-person team can work in without stepping on each other are related but different skill sets. Test automation has the same split, but the industry rarely talks about it that way — most content treats "automation engineer" as one undifferentiated skill level, when in practice there's a wide gulf between someone who can automate a flow and someone who can design the system three other engineers will build on top of for the next two years.
The rest of this article walks through the actual engineering concepts the book covers — with real patterns, real code, and real folder structures — so you can evaluate whether this is the missing piece in your own automation practice. If you've got somewhere between 5 and 15 years of engineering experience and you've been handed "own our test automation strategy" as a responsibility without much guidance on what that actually means day to day, this is written for exactly that moment.
The real cost of framework rot
If you've worked on a test suite for more than a year, you've seen this trajectory:
Month 1–2: Tests are fast, green, and trusted. Every PR runs them. Nobody questions a red build.
Month 4–6: The suite has tripled in size. Locators are duplicated across files. Two engineers wrote two different "login helpers" that behave slightly differently. Flaky tests start appearing — not because Playwright is unreliable, but because nobody owns synchronization strategy, and everyone is sprinkling waitForTimeout(2000) wherever a test turns red.
Month 8–12: CI runs take 40+ minutes. Nobody trusts a red build anymore because "it's probably flaky." Test data is hardcoded and collides across parallel workers. A new hire spends their first two weeks just trying to understand which of the four login() functions to use.
Month 12+: Someone proposes a rewrite. The org loses six months of automation coverage during the "migration," and the whole cycle risks repeating because the underlying architectural decisions — not the tool — were never fixed.
This isn't a Playwright problem. Playwright is, by a wide margin, one of the best-engineered test automation tools available today — auto-waiting, network interception, trace viewer, multi-browser support out of the box. The tool was never the bottleneck. The bottleneck is that most teams never design a framework; they accumulate one, test by test, PR by PR, until it's too tangled to safely change.
Framework design front-loads the decisions that prevent this — folder structure, abstraction boundaries, fixture composition, config strategy — so that test #800 is exactly as easy to write and as easy to trust as test #1.
A pattern worth naming explicitly: the "flaky test tax." Once a suite accumulates enough undiagnosed flakiness, teams don't fix the root cause — they add a --repeat-until-failure retry, or bump retries: 3 in the config, and move on. That's a rational short-term decision and a disastrous long-term one, because retries hide the exact signal you need to find the real problem. A test that passes on retry #2 isn't "fixed" — it's a test with an undiagnosed race condition that will eventually fail in a way retries can't paper over, usually during a release window, usually when someone is watching. Every additional retry a team adds is effectively a tax on CI time and a tax on trust, paid indefinitely, in exchange for never having to do the harder work of fixing test isolation and synchronization. A well-designed framework treats retries as a last-resort mitigation for genuine environmental flakiness (a slow staging deploy, a third-party sandbox being unreliable), not a substitute for correct locator strategy and correct waiting.
The pattern repeats across companies of every size — a five-person startup and a thousand-engineer enterprise hit the exact same failure mode, just on different timelines. The startup gets there in three months because velocity is high and nobody has time to think about test architecture. The enterprise gets there in eighteen months because there are more engineers contributing to the same suite, each with slightly different conventions. Either way, the fix is the same: stop, redesign the foundational layer, and this time build it so the next 800 tests don't repeat the mistake.
Page Object Model vs Component Object Model
Almost every automation engineer has heard of the Page Object Model (POM). Far fewer have implemented the Component Object Model (COM) correctly, and most production frameworks would benefit enormously from combining both.
Page Object Model — the page-level abstraction
POM wraps a full page (or a full logical screen) in a class, exposing high-level actions and hiding raw locators:
// pages/LoginPage.ts
import { Page, Locator, expect } from '@playwright/test';
export class LoginPage {
readonly page: Page;
readonly emailInput: Locator;
readonly passwordInput: Locator;
readonly submitButton: Locator;
readonly errorBanner: Locator;
constructor(page: Page) {
this.page = page;
this.emailInput = page.getByLabel('Email');
this.passwordInput = page.getByLabel('Password');
this.submitButton = page.getByRole('button', { name: 'Sign in' });
this.errorBanner = page.getByTestId('login-error');
}
async goto() {
await this.page.goto('/login');
}
async login(email: string, password: string) {
await this.emailInput.fill(email);
await this.passwordInput.fill(password);
await this.submitButton.click();
}
async expectError(message: string) {
await expect(this.errorBanner).toHaveText(message);
}
}
This works cleanly for a simple login screen. It breaks down fast in real enterprise apps, where a single page might contain a navigation bar, a data table with inline editing, a modal, a toast system, and a filter panel — all reused across dozens of pages. If you jam all of that into one "page object," you get a 1,200-line class that's just as unmaintainable as no abstraction at all.
Component Object Model — the reusable-widget abstraction
COM treats recurring UI pieces — modals, tables, date pickers, nav bars, toast notifications — as their own objects, independent of which page they appear on:
// components/DataTable.ts
import { Page, Locator } from '@playwright/test';
export class DataTable {
private readonly root: Locator;
constructor(page: Page, testId: string) {
this.root = page.getByTestId(testId);
}
row(rowText: string): Locator {
return this.root.locator('tr', { hasText: rowText });
}
async sortBy(columnName: string) {
await this.root.getByRole('columnheader', { name: columnName }).click();
}
async getRowCount(): Promise<number> {
return this.root.locator('tbody tr').count();
}
async selectRow(rowText: string) {
await this.row(rowText).getByRole('checkbox').check();
}
}
// pages/OrdersPage.ts
import { Page } from '@playwright/test';
import { DataTable } from '../components/DataTable';
import { NavBar } from '../components/NavBar';
export class OrdersPage {
readonly page: Page;
readonly table: DataTable;
readonly nav: NavBar;
constructor(page: Page) {
this.page = page;
this.table = new DataTable(page, 'orders-table');
this.nav = new NavBar(page);
}
async goto() {
await this.page.goto('/orders');
}
}
Now DataTable is written once and reused across OrdersPage, InvoicesPage, UsersPage, and every other screen that happens to render the same table component. When the product team changes how sorting works, you fix it in one file, not fourteen.
The book's framing is exactly this: POM organizes tests by page; COM organizes tests by UI element. Real frameworks need both, layered — pages compose components, components never know about pages, and tests only ever talk to pages. That last rule — the direction of dependency — is the one most self-taught frameworks get backwards, and it's the one that causes cascading breakage when the UI changes.
Three POM/COM anti-patterns that show up in almost every audit
1. The "god page object." A single DashboardPage.ts file that grows to 800+ lines because every widget on the dashboard got bolted onto the same class instead of extracted into its own component. Diagnostic question: if you can't describe what a page object does in one sentence, it's doing too much.
2. Locators leaking into test files. The moment a test file contains page.locator('.btn-primary') directly instead of going through a page or component method, you've broken the abstraction — that locator now has to be hunted down and fixed in every test file that happens to use it, rather than in one place. A useful lint-level rule: test files should only ever call methods on page/component objects, never raw Playwright locator APIs.
3. Components reaching back into pages. If a Modal component needs to know it's being rendered inside OrdersPage versus InvoicesPage, the abstraction has inverted. Components should be page-agnostic — a Modal closes the same way regardless of which page opened it. If a component "needs" page-specific behavior, that behavior belongs in the page object calling the component, not the component itself.
Getting these three rules right is less about Playwright specifically and more about applying object-oriented design discipline — single responsibility, clear dependency direction — to a domain (browser automation) where it's tempting to skip that discipline because "it's just tests." The book treats POM/COM design with the same rigor you'd expect from a production application architecture review, because at scale, that's exactly what a test framework is.
Fixtures and hooks
Playwright's built-in fixture system is one of its most underused features, largely because most tutorials stop at test.beforeEach(). Fixtures are Playwright's dependency-injection mechanism, and using them properly is what lets a framework scale past a handful of test files without every test file re-deriving the same setup logic.
A naive setup looks like this, repeated in file after file:
test.beforeEach(async ({ page }) => {
await page.goto('/login');
await page.getByLabel('Email').fill('admin@test.com');
await page.getByLabel('Password').fill('password123');
await page.getByRole('button', { name: 'Sign in' }).click();
});
Custom fixtures replace this entirely, and — critically — they compose:
// fixtures/base.ts
import { test as base } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';
import { OrdersPage } from '../pages/OrdersPage';
type Pages = {
loginPage: LoginPage;
ordersPage: OrdersPage;
authenticatedPage: void;
};
export const test = base.extend<Pages>({
loginPage: async ({ page }, use) => {
await use(new LoginPage(page));
},
ordersPage: async ({ page }, use) => {
await use(new OrdersPage(page));
},
authenticatedPage: [async ({ page, loginPage }, use) => {
await loginPage.goto();
await loginPage.login(process.env.TEST_USER_EMAIL!, process.env.TEST_USER_PASSWORD!);
await use();
}, { auto: true }],
});
export { expect } from '@playwright/test';
// tests/orders.spec.ts
import { test, expect } from '../fixtures/base';
test('user can filter orders by status', async ({ ordersPage }) => {
await ordersPage.goto();
await ordersPage.table.sortBy('Status');
expect(await ordersPage.table.getRowCount()).toBeGreaterThan(0);
});
Notice what the test file doesn't contain: no login code, no page instantiation, no boilerplate. Every test that imports this test object is automatically authenticated before it runs, and every page object is injected ready to use. This is the pattern that lets a framework scale from 50 tests to 5,000 without every test file becoming a copy-paste graveyard of setup logic — and it's exactly the kind of pattern most self-taught Playwright engineers never encounter, because it isn't in the "getting started" docs.
Worker-scoped fixtures — the setting most teams never touch
Playwright fixtures default to test scope (recreated per test), but they can also be scoped to worker (created once per parallel worker process and reused across every test that worker runs). This matters enormously for anything expensive to set up — an authenticated API client, a database connection pool, a seeded test-data batch:
// fixtures/api.fixture.ts
import { test as base, APIRequestContext } from '@playwright/test';
import { env } from '../config/environments';
type ApiFixtures = {
apiContext: APIRequestContext;
};
export const test = base.extend<{}, ApiFixtures>({
apiContext: [async ({ playwright }, use) => {
const context = await playwright.request.newContext({
baseURL: env.apiURL,
extraHTTPHeaders: {
Authorization: `Bearer ${process.env.API_TOKEN}`,
},
});
await use(context);
await context.dispose();
}, { scope: 'worker' }],
});
Because this is worker-scoped, the authenticated API context is built once per worker rather than once per test — with four parallel workers running a thousand tests, that's the difference between four API logins and a thousand. It's a small config change with an outsized effect on suite runtime, and it's exactly the kind of lever that separates someone who's used fixtures superficially (a beforeEach replacement) from someone who understands the full scoping model Playwright actually offers.
Fixture composition for permission testing
Combining worker-scoped setup with test-scoped role selection lets a framework test permission boundaries cleanly:
// fixtures/auth.fixture.ts
import { test as base } from './api.fixture';
import { Page } from '@playwright/test';
type Role = 'admin' | 'editor' | 'viewer';
export const test = base.extend<{ loginAs: (role: Role) => Promise<void> }>({
loginAs: async ({ page }, use) => {
const login = async (role: Role) => {
await page.context().addCookies(
JSON.parse(require('fs').readFileSync(`storage/${role}.json`, 'utf-8')).cookies
);
await page.goto('/dashboard');
};
await use(login);
},
});
test('viewer cannot access admin settings', async ({ page, loginAs }) => {
await loginAs('viewer');
await page.goto('/settings/admin');
await expect(page.getByText('Access denied')).toBeVisible();
});
This is the layer where a framework stops being "a bunch of Playwright scripts" and starts being genuinely reusable infrastructure — new permission tests are a couple of lines, not a couple of hours of setup.
Environment configuration
Enterprise apps run in at least three environments — dev, staging, production (and often a fourth: a PR-preview or ephemeral environment). A framework that hardcodes URLs and credentials is a framework that breaks the moment it's asked to run anywhere except the one machine it was written on.
A config-driven approach, layered through playwright.config.ts and environment-specific files:
// config/environments.ts
type Environment = {
baseURL: string;
apiURL: string;
testUser: { email: string; password: string };
};
const environments: Record<string, Environment> = {
dev: {
baseURL: 'https://dev.app.example.com',
apiURL: 'https://dev-api.example.com',
testUser: { email: 'dev-user@example.com', password: process.env.DEV_PASSWORD! },
},
staging: {
baseURL: 'https://staging.app.example.com',
apiURL: 'https://staging-api.example.com',
testUser: { email: 'staging-user@example.com', password: process.env.STAGING_PASSWORD! },
},
production: {
baseURL: 'https://app.example.com',
apiURL: 'https://api.example.com',
testUser: { email: 'prod-smoke-user@example.com', password: process.env.PROD_PASSWORD! },
},
};
export const env = environments[process.env.TEST_ENV || 'dev'];
// playwright.config.ts
import { defineConfig } from '@playwright/test';
import { env } from './config/environments';
export default defineConfig({
use: {
baseURL: env.baseURL,
trace: 'retain-on-failure',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
projects: [
{ name: 'chromium', use: { browserName: 'chromium' } },
{ name: 'firefox', use: { browserName: 'firefox' } },
{ name: 'webkit', use: { browserName: 'webkit' } },
],
});
Now switching environments is TEST_ENV=staging npx playwright test — no code changes, no manual find-and-replace of URLs, no risk of accidentally running "prod-destructive" tests against production because someone forgot to swap a base URL back. This sounds obvious in the abstract; it's one of the most common gaps the book calls out in real audits of production frameworks, because teams add environments reactively, patching config in ten different places instead of centralizing it from day one.
Secrets deserve a specific callout here. Credentials for a production test user should never live in a repo — not in a .env committed by accident, not in a config file "temporarily" hardcoded and forgotten. The pattern above pulls every credential from process.env, which means the actual secret values live in CI secret managers (GitHub Actions secrets, GitLab CI/CD variables, AWS Secrets Manager, Vault) and are injected at runtime, never checked into source control. It's a small discipline that a surprising number of "working" frameworks get wrong, usually discovered during a security review rather than caught in code review — and by then it's a credential rotation exercise, not a five-minute fix.
There's also a subtler config trap worth naming: test-environment drift. If staging and production diverge meaningfully in feature flags, data shape, or third-party sandbox behavior, a suite that's "green on staging" can still miss real production bugs. A mature framework treats this as a first-class concern — running a lean, curated smoke suite directly against production post-deploy (read-only, non-destructive assertions only) in addition to the full regression suite against staging, rather than assuming staging parity is guaranteed.
Execution strategy
Two separate concerns get conflated constantly: cross-browser coverage and parallel execution speed. They're solved differently.
Cross-browser is handled through Playwright's projects array (shown above) — each project runs the full suite against a different engine (Chromium, Firefox, WebKit), and CI can fan these out as separate jobs.
Parallelism and sharding is what actually determines how long your pipeline takes:
# Split the suite across 4 CI machines
npx playwright test --shard=1/4
npx playwright test --shard=2/4
npx playwright test --shard=3/4
npx playwright test --shard=4/4
// playwright.config.ts
export default defineConfig({
fullyParallel: true,
workers: process.env.CI ? 4 : undefined,
retries: process.env.CI ? 2 : 0,
});
The engineering judgment call the book spends real time on is test isolation under parallelism — because sharding and worker parallelism only pay off if tests don't share mutable state. A suite that creates a "test-user@example.com" record and reuses it across files will start failing intermittently the moment it's parallelized, because two workers can now race to mutate the same row. The fix isn't a Playwright setting; it's a design discipline — unique data per test, database or API-level teardown, and fixtures that create-and-destroy rather than reuse-and-hope.
A practical pattern for this is generating unique identifiers per test run and threading them through any data the test creates:
import { test as base } from '@playwright/test';
import { randomUUID } from 'crypto';
export const test = base.extend<{ testRunId: string }>({
testRunId: async ({}, use) => {
await use(`test-${randomUUID().slice(0, 8)}`);
},
});
test('user can create an order', async ({ page, testRunId }) => {
const orderName = `Order-${testRunId}`;
// this order name is unique to this test execution, safe under
// any level of parallelism, and trivially traceable back to a
// specific CI run if it needs cleanup
});
The other execution-strategy decision worth making deliberately is test tiering — not every test needs to run on every PR. A common, effective split:
- Smoke suite (30–60 seconds, runs on every commit): the handful of tests that, if red, mean "do not merge, do not deploy" — login, checkout, core navigation.
- Full regression (runs on merge to main, or nightly): the complete suite, sharded across however many CI runners the team can justify.
- Cross-browser matrix (runs nightly or pre-release): the full suite fanned out across Chromium, Firefox, and WebKit — expensive enough that running it on every PR is rarely worth the CI bill.
This tiering is a direct answer to a real organizational tension: engineers want fast feedback on PRs, and QA wants full coverage before a release. Trying to satisfy both with a single "run everything, every time" pipeline is how teams end up with 40-minute PR checks that engineers start ignoring or bypassing.
Authentication and storage state
Logging in through the UI before every single test is one of the most common (and most expensive) anti-patterns in test automation. A login flow that takes 3 seconds, multiplied across 500 tests, is 25 minutes of pure overhead before a single assertion runs.
Playwright's storageState mechanism solves this by authenticating once and reusing the session:
// global-setup.ts
import { chromium, FullConfig } from '@playwright/test';
import { env } from './config/environments';
async function globalSetup(config: FullConfig) {
const browser = await chromium.launch();
const page = await browser.newPage();
await page.goto(`${env.baseURL}/login`);
await page.getByLabel('Email').fill(env.testUser.email);
await page.getByLabel('Password').fill(env.testUser.password);
await page.getByRole('button', { name: 'Sign in' }).click();
await page.waitForURL('**/dashboard');
await page.context().storageState({ path: 'storage/auth.json' });
await browser.close();
}
export default globalSetup;
// playwright.config.ts
export default defineConfig({
globalSetup: require.resolve('./global-setup'),
use: {
storageState: 'storage/auth.json',
},
});
Every test now starts already logged in — no repeated UI login, no repeated network round trips, and a suite-wide speedup that's often the single biggest performance win available to a framework. The nuance the book covers that most blog posts skip: role-based storage states. Enterprise apps rarely have one user type. A framework needs admin.json, editor.json, viewer.json — generated once in global setup, then selected per test via fixture composition — so that permission-boundary tests (can a viewer not delete a record?) are exercised as rigorously as the happy path.
API mocking and network interception
This is where Playwright pulls dramatically ahead of most legacy tools, and it's also where most frameworks under-use the tool's actual power. Playwright can intercept, inspect, modify, or fully mock any network request the page makes — which means you can test UI behavior for error states, slow networks, or edge-case API responses without needing the backend to actually produce them.
test('shows error state when orders API fails', async ({ page }) => {
await page.route('**/api/orders', (route) =>
route.fulfill({
status: 500,
contentType: 'application/json',
body: JSON.stringify({ error: 'Internal Server Error' }),
})
);
await page.goto('/orders');
await expect(page.getByText('Something went wrong')).toBeVisible();
});
test('handles slow network gracefully', async ({ page }) => {
await page.route('**/api/orders', async (route) => {
await new Promise((resolve) => setTimeout(resolve, 3000));
await route.continue();
});
await page.goto('/orders');
await expect(page.getByTestId('loading-spinner')).toBeVisible();
});
This unlocks test scenarios that are difficult or outright impossible to trigger reliably against a live backend: a 500 error on a third API call in a chain, a truncated response, a 10-second network delay, an API that returns 200 with malformed JSON. A mature framework builds a mock library — reusable route handlers for common failure modes — so any test can opt into "simulate API timeout" or "simulate empty state" with one line, instead of every engineer improvising their own page.route() call from scratch:
// api/mocks/networkFailures.ts
import { Page } from '@playwright/test';
export const networkFailures = {
async serverError(page: Page, urlPattern: string) {
await page.route(urlPattern, (route) =>
route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) })
);
},
async timeout(page: Page, urlPattern: string, delayMs = 15000) {
await page.route(urlPattern, async (route) => {
await new Promise((r) => setTimeout(r, delayMs));
await route.abort('timedout');
});
},
async emptyState(page: Page, urlPattern: string) {
await page.route(urlPattern, (route) =>
route.fulfill({ status: 200, body: JSON.stringify({ data: [] }) })
);
},
async rateLimited(page: Page, urlPattern: string) {
await page.route(urlPattern, (route) =>
route.fulfill({ status: 429, headers: { 'Retry-After': '30' }, body: '{}' })
);
},
};
test('orders page handles rate limiting gracefully', async ({ page }) => {
await networkFailures.rateLimited(page, '**/api/orders');
await page.goto('/orders');
await expect(page.getByText(/try again in/i)).toBeVisible();
});
There's an important boundary the book is careful about: mocking is for UI resilience testing, not a replacement for real integration tests. A UI that correctly renders an error banner when it receives a mocked 500 tells you the frontend handles failure gracefully — it tells you nothing about whether the backend actually returns a 500 in that scenario in the real world. A mature framework runs both: a layer of UI-level tests with mocked network conditions to verify frontend resilience, and a separate layer of real API/integration tests (often outside Playwright entirely, or using Playwright's request context against a live test environment) to verify the actual contract between frontend and backend. Conflating the two — assuming a green mocked test means the real integration works — is one of the more expensive mistakes teams make once they discover how convenient page.route() is.
UI edge cases
Every framework eventually hits the handful of UI patterns that don't behave like a normal DOM tree, and this is exactly where naive Playwright usage falls apart.
iframes — Playwright requires you to explicitly enter the frame context:
const paymentFrame = page.frameLocator('iframe[title="Payment form"]');
await paymentFrame.getByLabel('Card number').fill('4242424242424242');
Multiple tabs / popups — a new tab is a new Page object, and you have to explicitly listen for it:
const [newPage] = await Promise.all([
context.waitForEvent('page'),
page.getByRole('link', { name: 'Open in new tab' }).click(),
]);
await newPage.waitForLoadState();
await expect(newPage).toHaveTitle(/Report/);
Shadow DOM — Playwright pierces open shadow roots automatically with standard locators in most cases, but closed shadow roots and custom web components (common in enterprise design systems built on Lit, Stencil, or similar) require deliberate locator strategy, often falling back to page.locator('custom-element').evaluate(...) patterns or exposing test hooks from the component itself.
None of these are exotic — every enterprise app built in the last five years uses at least one of them (payment iframes, "open in new tab" report links, design-system web components). A framework that hasn't solved these patterns once, centrally forces every engineer who hits them to rediscover the fix independently, usually under deadline pressure, usually inconsistently.
A concrete Shadow DOM example. Design systems built with Lit or Stencil frequently render form controls inside open shadow roots — a <custom-input> element whose actual <input> lives inside shadowRoot, invisible to a naive page.locator('input') call at the document root. Playwright's locator engine pierces open shadow roots automatically when you use standard CSS or text-based locators, which handles the majority of cases:
// Works even though <input> is inside a shadow root, as long as it's open
await page.locator('custom-input input').fill('test value');
But closed shadow roots — deliberately used by some component libraries to encapsulate internals — are invisible to any locator strategy, by design. There's no clean Playwright-only workaround for a closed shadow root; the practical fix is coordinating with frontend engineering to either avoid mode: 'closed' for testable components, or to expose a data-testid-accessible slot at the light-DOM boundary that the test can hook into. This is one of the places where framework design bleeds into cross-team collaboration — a good test architect doesn't just write around the problem, they flag it as a testability requirement in the component library itself.
Nested iframes compound the difficulty further — a payment provider's iframe that itself embeds a second iframe for 3D Secure verification, for example. frameLocator() chains cleanly for this:
const secureFrame = page
.frameLocator('iframe[title="Payment form"]')
.frameLocator('iframe[title="3D Secure verification"]');
await secureFrame.getByLabel('OTP code').fill('123456');
Each of these patterns is a five-minute fix once you know it — and a multi-hour debugging session the first time an engineer hits it without ever having seen it documented anywhere. Centralizing the fix in a shared component/utility layer, written once by whoever solves it first, is the entire point of framework design: pay the cost once, as a team, instead of paying it repeatedly, per engineer, per encounter.
Data-driven testing
Hardcoding test data inline works for five tests. It's unmanageable at fifty. The pattern that scales is separating test logic from test data entirely:
// data/users.json
[
{ "role": "admin", "email": "admin@test.com", "canDelete": true },
{ "role": "editor", "email": "editor@test.com", "canDelete": false },
{ "role": "viewer", "email": "viewer@test.com", "canDelete": false }
]
import users from '../data/users.json';
for (const user of users) {
test(`${user.role} sees correct delete permissions`, async ({ page }) => {
await loginAs(page, user);
const deleteButton = page.getByRole('button', { name: 'Delete' });
if (user.canDelete) {
await expect(deleteButton).toBeEnabled();
} else {
await expect(deleteButton).toBeDisabled();
}
});
}
One test body, three generated test cases, and adding a fourth role means editing a JSON file, not writing new test code. This is the difference between a framework that scales linearly with new requirements and one that scales linearly with new code.
For cases that need fresh, non-colliding data rather than fixed fixtures — form submissions, account creation, anything where reusing the same static row across parallel workers would cause collisions — a data factory pattern using something like @faker-js/faker fills the gap cleanly:
// data/factories/userFactory.ts
import { faker } from '@faker-js/faker';
export function buildUser(overrides: Partial<TestUser> = {}): TestUser {
return {
email: faker.internet.email(),
firstName: faker.person.firstName(),
lastName: faker.person.lastName(),
phone: faker.phone.number(),
...overrides,
};
}
test('user can complete signup with valid details', async ({ page }) => {
const user = buildUser();
await page.goto('/signup');
await page.getByLabel('Email').fill(user.email);
await page.getByLabel('First name').fill(user.firstName);
// every parallel run generates a unique email — zero collision risk
});
The distinction the book draws is deliberate: fixed data (JSON fixtures) for scenarios where the specific values matter — permission roles, known edge-case inputs, boundary values — and generated data (factories) for scenarios where uniqueness matters more than the specific value. Conflating the two is a common source of the exact parallelism failures discussed in the execution-strategy section above.
Reporting and debugging
A red test that nobody can diagnose in under ten minutes is worse than no test at all — it burns trust and burns time in equal measure. Playwright's built-in tooling here is genuinely best-in-class, but it has to be configured to be useful:
export default defineConfig({
reporter: [
['html', { open: 'never' }],
['junit', { outputFile: 'results/junit.xml' }],
['list'],
],
use: {
trace: 'retain-on-failure',
screenshot: 'only-on-failure',
video: 'retain-on-failure',
},
});
With this configuration, any CI failure produces a full trace — a scrubbable timeline of every action, network call, console log, and DOM snapshot at each step — viewable with npx playwright show-trace trace.zip. Combined with a screenshot at the moment of failure and a video of the full run leading up to it, the standard "can you reproduce this locally?" investigation drops from an hour to minutes. The book's treatment of this goes further into structured logging — attaching custom context (which test data set, which environment, which retry attempt) to every trace, so a failure in CI carries enough metadata to be diagnosable without ever needing to reproduce it locally at all.
A custom logger, attached consistently across the framework, closes the loop between "what Playwright captured" and "what a human needs to see first":
// utils/logger.ts
import { TestInfo } from '@playwright/test';
export function logStep(testInfo: TestInfo, message: string, data?: Record<string, unknown>) {
const entry = { timestamp: new Date().toISOString(), test: testInfo.title, message, data };
console.log(JSON.stringify(entry));
testInfo.attach('step-log', { body: JSON.stringify(entry, null, 2), contentType: 'application/json' });
}
Attaching structured logs as first-class Playwright test artifacts (via testInfo.attach) means they show up directly in the HTML report alongside the trace, screenshot, and video — one place to look, not four separate systems to correlate manually.
The last piece that turns "good local debugging" into "good team debugging" is failure visibility beyond the CI dashboard. A common, low-effort addition: a post-run script that posts a summary to Slack or Teams whenever the main branch pipeline goes red, linking directly to the HTML report:
// utils/notifyOnFailure.ts
async function notifySlack(failedCount: number, reportUrl: string) {
await fetch(process.env.SLACK_WEBHOOK_URL!, {
method: 'POST',
body: JSON.stringify({
text: `🔴 ${failedCount} test(s) failed on main. Report: ${reportUrl}`,
}),
});
}
None of this is exotic engineering — it's the unglamorous plumbing that determines whether a red build gets investigated within the hour or ignored until someone finally notices the suite has been broken for three days. Frameworks that skip this layer tend to have technically excellent test code and a team that's completely disengaged from the results, which is arguably worse than having no automation at all.
Production-grade folder structure
This is the section engineers ask about most, because there's no single canonical answer online — every blog post shows a different toy example. Here's the shape of a folder structure built for a real, multi-team, enterprise-scale suite:
playwright-framework/
├── config/
│ ├── environments.ts
│ └── playwright.config.ts
├── fixtures/
│ ├── base.ts
│ ├── auth.fixture.ts
│ └── api.fixture.ts
├── pages/
│ ├── LoginPage.ts
│ ├── OrdersPage.ts
│ ├── InvoicesPage.ts
│ └── SettingsPage.ts
├── components/
│ ├── DataTable.ts
│ ├── NavBar.ts
│ ├── Modal.ts
│ └── Toast.ts
├── api/
│ ├── clients/
│ │ ├── OrdersClient.ts
│ │ └── UsersClient.ts
│ └── mocks/
│ ├── ordersMocks.ts
│ └── networkFailures.ts
├── data/
│ ├── users.json
│ └── orders.fixture.ts
├── utils/
│ ├── logger.ts
│ ├── retry.ts
│ └── dateHelpers.ts
├── storage/
│ ├── admin.json
│ ├── editor.json
│ └── viewer.json
├── tests/
│ ├── e2e/
│ │ ├── orders.spec.ts
│ │ └── invoices.spec.ts
│ ├── api/
│ │ └── orders.api.spec.ts
│ └── smoke/
│ └── critical-paths.spec.ts
├── global-setup.ts
├── global-teardown.ts
├── playwright.config.ts
├── tsconfig.json
└── package.json
Every folder here answers a specific ownership question: where does a new page object go, where does a new mock live, where does role-based auth state get stored, where do smoke tests live separately from full regression. A new engineer joining the team should be able to find any given piece of infrastructure by folder name alone, without asking. That's the actual test of whether a "framework" earns the name — not whether it uses Playwright's features correctly in isolation, but whether it's navigable by someone who didn't write it.
The book dedicates its closing chapters to exactly this: the reasoning behind each layer, how it evolves as the app and team grow, and the mistakes (over-nesting, premature abstraction, tests directly instantiating page objects instead of going through fixtures) that turn a clean structure back into a mess within two sprints.
What separates a framework from a folder of tests
Pulling all of the above together, the difference isn't any single pattern — it's that all of these decisions are made deliberately and consistently, rather than accumulated ad hoc:
| Folder of tests | Real framework |
|---|---|
| Locators duplicated per file | Centralized in Page/Component objects |
| Every file has its own login logic | Shared fixtures, storage-state reuse |
| Config hardcoded per environment | Single config source, env-driven |
| Flaky tests "fixed" with sleeps | Isolation and proper waiting strategy designed in |
| Debugging = re-running locally and guessing | Trace + video + screenshot on every failure |
| New engineer needs a walkthrough to contribute | Structure is self-explanatory |
| Adding a test case means writing new code | Adding a test case means adding a data row |
That right-hand column is what Playwright Framework Design with TypeScript is teaching, end to end.
Who this book is actually for
This isn't a beginner book, and it says so directly. It assumes you can already write a Playwright test — locators, actions, assertions — and it starts exactly where most content stops:
- SDETs and QA engineers moving from "I write tests" to "I own the test framework"
- Automation leads tasked with standardizing a team's approach across multiple squads
- Backend/full-stack engineers picking up test-architecture ownership as part of a platform or DevEx role
- Engineering managers evaluating whether an existing in-house framework needs a rebuild or a refactor
- Freelancers and consultants who need to stand up a production-credible framework fast, for a client who won't tolerate a flaky suite
If you've been doing this for anywhere from a couple of years to well over a decade and you've felt the specific pain of a test suite that grew faster than its architecture could support, this book is describing your exact problem — and giving you the vocabulary and patterns to fix it.
Inside the book
Here's what's actually covered, chapter by chapter, based on the book's stated contents:
- 🏗️ Page Object Model & Component Object Model architecture patterns — how to layer both correctly, and where each one belongs
- 🔐 Authentication, storage state, API mocking & network interception — session reuse at scale, role-based auth states, and simulating backend failure modes on demand
- 🧩 Iframes, multiple tabs & Shadow DOM — the UI edge cases that quietly break most homegrown frameworks
- 📊 Data-driven testing, reporting, logging, screenshots & video capture — separating logic from data, and making failures diagnosable without reproduction
- 📁 Production-ready folder structure & scalable framework design — the complete blueprint, and the reasoning behind every layer
54 pages. No filler chapters on "what is a locator." Every page is aimed at the architecture layer specifically, written by an author who has clearly built and maintained these systems in real production environments rather than summarizing documentation.
Why the bundle is the smarter buy
If you're serious about Playwright — not just fixing your current framework but building genuine end-to-end expertise — the standalone book is one piece of a larger, deliberately sequenced curriculum. The Complete AI Playwright + TypeScript Mastery Bundle packages all four books together, in the order they're meant to be read:
- Playwright with TypeScript: From Zero to Automation Hero — foundations: setup, locators, actions, your first real tests
- Playwright Framework Design with TypeScript — the book covered in this article: architecture, POM/COM, fixtures, production folder structure
- Enterprise Playwright Automation with TypeScript — API testing, CI/CD pipelines, cross-browser execution, and enterprise-scale deployment
- AI Testing with Playwright + TypeScript (2026 Edition) — the frontier layer: MCP, AI-generated tests, self-healing automation, and LLM/RAG testing
This is a genuinely rare thing in the testing-content space: a curriculum with an actual beginning, middle, and end, rather than four disconnected books bolted together for a discount. Book 1 gets you writing correct tests. Book 2 (this one) gets you architecting frameworks that scale. Book 3 gets you into the CI/CD and enterprise deployment layer. Book 4 gets you ahead of where the industry is actually heading — AI-assisted and AI-generated test automation, which is rapidly becoming a baseline expectation rather than a novelty.
Buy once, own the full roadmap — from your first test() block to designing systems a whole engineering org can rely on, and pricing it out individually costs meaningfully more than the bundle.
Common framework anti-patterns
Across audits of real production suites, a small set of mistakes shows up over and over, independent of company size or industry:
1. Sleep-driven synchronization. await page.waitForTimeout(3000) scattered through a suite "because the test was flaky." Playwright auto-waits for actionability by default; a hardcoded sleep is almost always masking a real synchronization issue — an element that's visible but not yet interactive, a network response the test isn't actually waiting for. The fix is await expect(locator).toBeVisible() / toBeEnabled() before interacting, or explicitly awaiting the relevant network response, never a fixed delay.
2. Assertion-free tests. Tests that navigate through a flow and never actually assert anything meaningful beyond "no error was thrown." These pass even when the feature is subtly broken, and they erode trust the moment someone notices a real bug slipped through a "passing" suite.
3. One giant utils.ts file. A catch-all utilities file that grows to thousands of lines because nobody defined where logic belongs. The folder structure in this article exists specifically to prevent this — api/, data/, components/, pages/ each have a clear job, so there's never an ambiguous "where does this go" moment.
4. Test interdependency. Test B assumes test A ran first and left the app in a particular state. This is a silent killer of parallel execution and of test reordering — any CI optimization that changes execution order (sharding, prioritizing recently-changed tests) breaks the suite in ways that are maddening to debug because the failing test itself did nothing wrong.
5. No ownership model. Nobody is accountable for the health of the suite. Flaky tests accumulate a .skip() and are never revisited. A framework needs an owner — individual or rotating — whose job includes triaging red builds and deciding what needs fixing versus what needs deleting.
6. Testing implementation instead of behavior. Locators tied to CSS class names that change with every design refresh ('.MuiButton-root-482') instead of accessible roles and text (getByRole('button', { name: 'Submit' })). This single habit is responsible for an outsized share of "the whole suite broke after a routine UI update" incidents.
CI/CD integration for a mature Playwright framework
A framework is only as valuable as the pipeline that runs it. A representative GitHub Actions setup that reflects the tiering strategy discussed earlier:
# .github/workflows/playwright.yml
name: Playwright Tests
on:
pull_request:
push:
branches: [main]
schedule:
- cron: '0 2 * * *' # nightly full regression + cross-browser matrix
jobs:
smoke:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx playwright test tests/smoke --project=chromium
env:
TEST_ENV: staging
STAGING_PASSWORD: ${{ secrets.STAGING_PASSWORD }}
regression:
if: github.event_name == 'push'
runs-on: ubuntu-latest
strategy:
matrix:
shard: [1, 2, 3, 4]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx playwright test --shard=${{ matrix.shard }}/4
env:
TEST_ENV: staging
STAGING_PASSWORD: ${{ secrets.STAGING_PASSWORD }}
- uses: actions/upload-artifact@v4
if: always()
with:
name: playwright-report-${{ matrix.shard }}
path: playwright-report/
cross-browser-nightly:
if: github.event_name == 'schedule'
runs-on: ubuntu-latest
strategy:
matrix:
browser: [chromium, firefox, webkit]
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: 20 }
- run: npm ci
- run: npx playwright install --with-deps ${{ matrix.browser }}
- run: npx playwright test --project=${{ matrix.browser }}
The structure directly encodes the tiering philosophy: fast smoke feedback on every PR, sharded full regression on merge, and the expensive cross-browser matrix reserved for a nightly schedule where a 40-minute run doesn't block anyone's workflow. Report artifacts are uploaded on every run — including failures — so any red build's trace, video, and screenshots are one click away from the CI job itself, without needing local reproduction.
Migrating an existing suite without a rewrite
Most teams reading this don't have the luxury of starting from zero — they have an existing, messy, partially-trusted suite and a business that won't tolerate pausing feature testing for a rewrite. The realistic path is incremental:
Step 1 — Stop the bleeding. Freeze new tests from being added in the old pattern. Every new test goes into the new structure (fixtures, POM/COM, config-driven env) from day one, even while old tests remain untouched.
Step 2 — Extract, don't rewrite, the highest-leverage abstractions first. Centralizing login/storage-state reuse alone often cuts suite runtime dramatically and touches every existing test file only through a shared fixture import — not a full rewrite of each file's internals.
Step 3 — Migrate by folder, not by find-and-replace. Pick one feature area (say, orders/), fully migrate its tests to the new pattern, verify it's stable in CI for a week, then move to the next. This keeps the blast radius of any migration mistake contained to one feature area at a time.
Step 4 — Delete aggressively. Every legacy test migrated is an opportunity to ask "does this test still provide unique value, or is it redundant with three others?" Suites that have accumulated for years nearly always have meaningful redundancy; migration is the natural moment to prune it rather than dragging dead weight into the new structure.
Step 5 — Measure before and after. Suite runtime, flake rate (tests that pass on retry), and time-to-diagnose-a-failure are the three numbers worth tracking through a migration. If none of them improve, the migration didn't actually fix the underlying architecture — it just moved the same problems into new files.
Rolling this out across a multi-team org
Framework design decisions made in isolation by one team rarely survive contact with a second team building on top of them. A few practices make the difference between a framework that spreads successfully across an org and one that gets abandoned or forked into incompatible variants:
- Publish the framework as an internal package, versioned and installable, rather than something every team copy-pastes into their own repo. Fixes and improvements then propagate through a version bump instead of a manual re-sync.
- Document the "why," not just the "how." A README that explains why fixtures are structured a certain way prevents well-meaning engineers from "fixing" a pattern they don't understand the reasoning behind.
- Run office hours or a short onboarding session, not just a wiki page. Frameworks are learned faster through five minutes of live Q&A than through documentation nobody reads until they're already stuck.
- Treat contribution the same as any shared library — code review from framework owners on PRs that touch shared fixtures/components, the same way you'd review a change to a shared design-system package.
- Expect and budget for a transition period. Two teams running two different framework versions simultaneously for a few sprints is normal and fine; forcing an overnight cutover across an entire org usually isn't.
This is the layer where the difference between "I wrote some good Playwright code" and "I designed automation infrastructure an organization can actually depend on" becomes obvious — and it's exactly the kind of judgment that separates a mid-level contributor from someone ready to lead automation strategy at the org level.
Framework health checklist
A fast, honest self-assessment — if more than a couple of these are "no," the architecture (not the team's effort) is the bottleneck:
- [ ] Can a new engineer find where a given page's locators live without asking anyone?
- [ ] Does every test authenticate through shared fixtures, with zero duplicated login code?
- [ ] Can the full suite run against any environment with a single env-var change?
- [ ] Do parallel workers run without any test-data collisions?
- [ ] Does a CI failure produce a trace, screenshot, and video automatically, with zero extra steps?
- [ ] Is there a documented, enforced smoke-vs-regression-vs-nightly tiering strategy?
- [ ] Are locators built on accessible roles/text rather than brittle CSS classes?
- [ ] Is there a single owner (or rotation) accountable for suite health?
- [ ] Can a new test case for an existing flow be added by editing data, not writing new code?
- [ ] Has the team measured flake rate in the last quarter — and does anyone know if it's improving?
Playwright Framework Design with TypeScript is, in effect, a 54-page answer to how to get every item on that list to "yes" — with the reasoning, the patterns, and the folder structure to back it up.
FAQ
Is this book Playwright-specific, or does it cover Selenium/Cypress too?
It's Playwright and TypeScript specifically — the patterns (fixtures, storage state, network interception) are built around Playwright's actual API, not translated from a different tool.
Do I need to already know Playwright basics?
Yes. This book is explicitly about framework design, not syntax. If you've never written a Playwright test before, start with Book 1 in the bundle (From Zero to Automation Hero) first.
Is the folder structure prescriptive, or does it explain the reasoning?
The book walks through the reasoning behind each layer — so you can adapt the structure to your team's actual constraints rather than copy-pasting a template that doesn't fit your app.
What format is the book?
Digital download, 54 pages, 1.63 MB — delivered instantly through Gumroad after purchase.
Are refunds available?
The product listing states no refunds are offered, so review the table of contents and sample content carefully before purchasing.
Is the AI testing content (MCP, self-healing tests, LLM/RAG testing) in this book or a different one?
That's covered in Book 4 of the bundle, AI Testing with Playwright + TypeScript (2026 Edition) — not in the framework-design book itself. If you want both framework architecture and AI-driven testing, the bundle is the way to get both.
Final word
Most engineers learn Playwright by writing tests. Very few are ever taught how to design the system that holds hundreds of those tests together — and that gap is exactly where test suites quietly rot, one flaky workaround and one duplicated locator at a time. Playwright Framework Design with TypeScript is aimed squarely at closing that gap, with the folder structures, fixture patterns, and architectural reasoning that actually show up in production systems, not toy examples.
If you already own the framework problem at your company — or you're trying to build one that won't need a rewrite in a year — this is 54 focused pages built for exactly that job.
📘 Get the book
Playwright Framework Design with TypeScript
by Himanshu Agarwal — architecture-first, no fluff, 54 pages.🎁 Or go all-in with the full curriculum
The Complete AI Playwright + TypeScript Mastery Bundle
4 books — Zero to Automation Hero → Framework Design → Enterprise Automation → AI Testing (2026 Edition).
Buy once, own the entire roadmap.
This article is independent commentary and technical analysis referencing the publicly listed product descriptions for both titles. Code examples throughout are original illustrations of the concepts discussed and are not reproduced from the book's contents. Pricing, page count, and file size are as listed on the product pages at the time of writing and may change — check the links above for current details.
Top comments (0)