I Built 3 Playwright Frameworks So You Can Learn What Actually Scales

From Script‑Based to Enterprise Playwright: Frameworks That Actually Scale

When I started learning Playwright, every article told me the same things:

• “Use Page Object Model”
• “Create fixtures”
• “Don’t use waitForTimeout”

Nobody showed me:

• What a real project should look like
• How folders should be organized
• When POM becomes too big
• How teams handle authentication cleanly
• Why tests become flaky (and how to actually fix them)

So I learned by making mistakes.

Lots of mistakes.

After months of trial and error – and building automation frameworks from scratch at my job – I decided to document everything that worked. Not as a collection of tips, but as complete, runnable frameworks.

That’s why I built playwright-best-practices.

---

What makes this different from most Playwright repositories

Most GitHub repos show you one “perfect” architecture. You clone it, run it, and… you don’t know why it’s built that way.

This repo shows you the evolution:

Script‑based (no patterns)
↓
Simple Page Object Model
↓
Advanced POM (layered architecture)

You can compare each approach side‑by‑side and understand when complexity becomes worthwhile.

---

What’s inside (no fluff, no guessing)

Three runnable frameworks (clone and npm test)

Framework	What it teaches	Best for
01-script-based	Raw, inline interactions – the “I just need it to run” baseline	Understanding the pain that patterns solve
02-simple-pom	Classic Page Object Model – locators + actions in one class	Most teams (80% of use cases)
03-advanced-pom	Separate layers: locators, actions, assertions	Large suites where simple POM becomes a 1000‑line monster

One documentation folder (anti‑patterns)

Folder	What it is
04-anti-pattern-lab	Not runnable – a written guide of common mistakes

Why no runnable anti‑pattern code? Because broken examples can be confusing if they don’t fail clearly. Instead, I documented them – so you can recognize the smell before it infects your suite.

Additional production‑ready goodies

• Worker‑scoped login fixture – one login for the whole suite
• Environment‑based credentials – clean .env example
• GitHub Actions + Jenkins CI configs – ready to drop into your project
• Flaky test strategies – not just retries, but structural fixes

---

Advanced POM explained (because it’s often misunderstood)

When I say “Advanced POM”, I don’t mean bigger. I mean separated responsibilities:

Layer	Responsibility	Example
Locators	Store element selectors only	loginPage.emailInput
Actions	Perform business interactions	loginPage.loginWithCredentials()

This prevents your Page Objects from turning into 1000‑line files as your project grows. It also makes tests dramatically easier to refactor – change a selector in one place, and everything updates.

---

Lessons I learned building Playwright frameworks (the hard way)

Mistake #1: Putting assertions inside Page Objects

Why it failed:

Page Objects became tied to specific test flows. Reusability dropped. Changing a button’s text broke unrelated tests.

What I do now:

Keep assertions in dedicated assertion classes or test files. Page Objects should only expose state and actions.

Mistake #2: Logging in before every test

Why it failed:

Test suite took 3x longer. Rate‑limiting kicked in. Flakiness spiked.

What I do now:

Worker‑scoped login fixtures – one authentication per worker, shared across tests.

Mistake #3: Using waitForTimeout(5000) as a lazy fix

Why it failed:

Tests became slow and still flaky – just slower flaky.

What I do now:

waitForSelector, waitForResponse, or auto‑waiting assertions. The repo has concrete examples.

---

Who should use this repository

Role	Why it’s valuable
Junior SDET	Skip the painful trial‑and‑error phase – see what a real project looks like
Cypress → Playwright mover	Understand Playwright’s different approach (fixtures, worker scope, trace viewer)
Team lead	Hand this to juniors as a reference architecture
Anyone fighting flaky tests	The anti‑pattern lab + flaky test strategies will save your weekends

---

How to use the repo (the way I intended)

1. Clone it
   
   git clone https://github.com/ZeeaanNawazHarall/playwright-best-practices

2. Run the script‑based framework – feel the mess
   
   cd examples/script-framework && npm install && npx playwright test

3. Run the simple POM – see how much cleaner it gets

4. Run the advanced POM – understand how teams scale

5. Read the anti‑pattern lab – recognize mistakes you might be making right now

You’ll leave with a mental map of why each pattern exists – not just copy‑pasted code.

---

A final honest note

I’m not claiming this is the only way. But these patterns come from real work at my job (AccuraSol). They saved my weekends, made my scripts stable, and helped me sleep better.

I open‑sourced it because I remember being overwhelmed when I started. If this repo saves you one late night of debugging a flaky test, it’s done its job.

---

Repository link & call to action

If you’re learning Playwright or mentoring junior automation engineers, check it out:

👉 github.com/ZeeaanNawazHarall/playwright-best-practices

Feedback, issues, and pull requests are welcome.

Found a better pattern? Open a PR. Found a mistake? Tell me. Let’s make this the actual best‑practices repo, no gatekeeping.

---

— Zeeaan

SDET @ AccuraSol

Comments

[xulingfeng]

The progression from script-based \u2192 simple POM \u2192 advanced POM is exactly how I wish Playwright was taught. Most tutorials jump straight to \u201cuse fixtures\u201d without showing the pain that fixtures solve.

The \u201canti-pattern lab\u201d folder is the real MVP here \u2014 documenting why things break is more valuable than showing the perfect solution. Did you consider adding a section on parallel execution gotchas? That\u2019s been the biggest source of flakiness in my experience.