DEV Community: Anton Gulin

Page Object Model in Playwright with TypeScript: The Complete Guide

Anton Gulin — Tue, 01 Sep 2026 15:00:46 +0000

What is the Page Object Model?

The Page Object Model (POM) is a design pattern that creates an abstraction layer between your tests and your web pages. Instead of writing locators directly in tests, you encapsulate page elements and actions inside reusable classes.

Without POM (hard to maintain):

test('user can login', async ({ page }) => {
  await page.goto('/login');
  await page.locator('#email').fill('user@example.com');
  await page.locator('#password').fill('password123');
  await page.locator('button[type="submit"]').click();
  await expect(page.locator('.dashboard-welcome')).toBeVisible();
});

With POM (scalable):

test('user can login', async ({ page }) => {
  const loginPage = new LoginPage(page);
  await loginPage.goto();
  await loginPage.login('user@example.com', 'password123');
  await expect(loginPage.welcomeMessage).toBeVisible();
});

When the login form changes, you update one file, not 50 tests.

Why Use Page Objects?

1. Maintainability

Locators live in one place. When UI changes, update once.

2. Readability

Tests read like user stories: loginPage.login(), dashboard.navigateToSettings().

3. Reusability

4. Separation of concerns

Tests focus on behavior. Page objects handle implementation.

5. Team scalability

New team members understand tests faster.

Project Structure

Here's the structure I use for all my Playwright projects:

tests/
├── pages/
│   ├── BasePage.ts
│   ├── LoginPage.ts
│   ├── DashboardPage.ts
│   └── CheckoutPage.ts
├── components/
│   ├── Header.ts
│   ├── Modal.ts
│   └── Sidebar.ts
├── fixtures/
│   └── fixtures.ts
├── specs/
│   ├── login.spec.ts
│   ├── dashboard.spec.ts
│   └── checkout.spec.ts
└── playwright.config.ts

Creating a Base Page Class

Start with a base class that all pages extend:

// tests/pages/BasePage.ts
import { Page, Locator } from '@playwright/test';
export abstract class BasePage {
  protected page: Page;
  constructor(page: Page) {
    this.page = page;
  }
  async goto(): Promise<void> {
    await this.page.goto(this.url);
  }
  abstract get url(): string;
  // Common elements across all pages
  get header(): Locator {
    return this.page.getByRole('banner');
  }
  get footer(): Locator {
    return this.page.getByRole('contentinfo');
  }
  // Common actions
  async waitForPageLoad(): Promise<void> {
    await this.page.waitForLoadState('networkidle');
  }
}

Creating a Login Page Object

Now create a specific page class:

// tests/pages/LoginPage.ts
import { Page, Locator, expect } from '@playwright/test';
import { BasePage } from './BasePage';
export class LoginPage extends BasePage {
  constructor(page: Page) {
    super(page);
  }
  get url(): string {
    return '/login';
  }
  // Locators (use getters for lazy evaluation)
  get emailInput(): Locator {
    return this.page.getByLabel('Email address');
  }
  get passwordInput(): Locator {
    return this.page.getByLabel('Password');
  }
  get submitButton(): Locator {
    return this.page.getByRole('button', { name: 'Sign in' });
  }
  get errorMessage(): Locator {
    return this.page.getByRole('alert');
  }
  get forgotPasswordLink(): Locator {
    return this.page.getByRole('link', { name: 'Forgot password?' });
  }
  // Actions
  async login(email: string, password: string): Promise<void> {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
  async loginAndExpectDashboard(email: string, password: string): Promise<void> {
    await this.login(email, password);
    await expect(this.page).toHaveURL(/.*dashboard/);
  }
  async loginWithInvalidCredentials(email: string, password: string): Promise<void> {
    await this.login(email, password);
    await expect(this.errorMessage).toBeVisible();
  }
}

Creating a Dashboard Page Object

// tests/pages/DashboardPage.ts
import { Page, Locator } from '@playwright/test';
import { BasePage } from './BasePage';
export class DashboardPage extends BasePage {
  constructor(page: Page) {
    super(page);
  }
  get url(): string {
    return '/dashboard';
  }
  // Locators
  get welcomeMessage(): Locator {
    return this.page.getByRole('heading', { name: /Welcome/ });
  }
  get userMenu(): Locator {
    return this.page.getByRole('button', { name: 'User menu' });
  }
  get logoutButton(): Locator {
    return this.page.getByRole('menuitem', { name: 'Logout' });
  }
  get settingsLink(): Locator {
    return this.page.getByRole('link', { name: 'Settings' });
  }
  // Actions
  async logout(): Promise<void> {
    await this.userMenu.click();
    await this.logoutButton.click();
  }
  async navigateToSettings(): Promise<void> {
    await this.settingsLink.click();
  }
}

Using Page Objects in Tests

Now your tests are clean and readable:

// tests/specs/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';
import { DashboardPage } from '../pages/DashboardPage';
test.describe('Login functionality', () => {
  test('user can login with valid credentials', async ({ page }) => {
    const loginPage = new LoginPage(page);
    const dashboardPage = new DashboardPage(page);
    await loginPage.goto();
    await loginPage.login('valid@example.com', 'password123');
    await expect(dashboardPage.welcomeMessage).toBeVisible();
  });
  test('user sees error with invalid credentials', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.loginWithInvalidCredentials('invalid@example.com', 'wrong');
    await expect(loginPage.errorMessage).toContainText('Invalid credentials');
  });
  test('user can navigate to forgot password', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.forgotPasswordLink.click();
    await expect(page).toHaveURL(/.*forgot-password/);
  });
});

Advanced: Component Objects

For reusable UI components (modals, headers, sidebars), create component classes:

// tests/components/Modal.ts
import { Page, Locator } from '@playwright/test';
export class Modal {
  private page: Page;
  private container: Locator;
  constructor(page: Page) {
    this.page = page;
    this.container = page.getByRole('dialog');
  }
  get title(): Locator {
    return this.container.getByRole('heading');
  }
  get closeButton(): Locator {
    return this.container.getByRole('button', { name: 'Close' });
  }
  get confirmButton(): Locator {
    return this.container.getByRole('button', { name: 'Confirm' });
  }
  get cancelButton(): Locator {
    return this.container.getByRole('button', { name: 'Cancel' });
  }
  async close(): Promise<void> {
    await this.closeButton.click();
  }
  async confirm(): Promise<void> {
    await this.confirmButton.click();
  }
}

Use it in page objects:

// In DashboardPage.ts
async openDeleteModal(): Promise<Modal> {
  await this.deleteButton.click();
  return new Modal(this.page);
}

Advanced: Using Playwright Fixtures

For even cleaner tests, integrate page objects with Playwright fixtures:

// tests/fixtures/fixtures.ts
import { test as base } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';
import { DashboardPage } from '../pages/DashboardPage';
type MyFixtures = {
  loginPage: LoginPage;
  dashboardPage: DashboardPage;
};
export const test = base.extend<MyFixtures>({
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page));
  },
  dashboardPage: async ({ page }, use) => {
    await use(new DashboardPage(page));
  },
});
export { expect } from '@playwright/test';

Now tests are even cleaner:

// tests/specs/login.spec.ts
import { test, expect } from '../fixtures/fixtures';
test('user can login', async ({ loginPage, dashboardPage }) => {
  await loginPage.goto();
  await loginPage.login('user@example.com', 'password123');
  await expect(dashboardPage.welcomeMessage).toBeVisible();
});

Best Practices

1. Use getters for locators

Getters are lazily evaluated. The locator is resolved when accessed, not when the class is instantiated.

// Good
get submitButton(): Locator {
  return this.page.getByRole('button', { name: 'Submit' });
}
// Avoid (evaluated too early)
submitButton = this.page.getByRole('button', { name: 'Submit' });

2. Keep actions atomic

Each method should do one logical thing:

// Good
async login(email: string, password: string) { ... }
async fillEmail(email: string) { ... }
// Avoid combining unrelated actions
async loginAndCheckSettings() { ... }

3. Don't add assertions in page objects (usually)

Assertions belong in tests. Page objects encapsulate interactions.

Exception: Verification methods like loginAndExpectDashboard() can include assertions for convenience.

4. Use role-based locators

More resilient than CSS selectors:

// Good
page.getByRole('button', { name: 'Submit' })
// Fragile
page.locator('#submit-btn-primary')

Common Mistakes to Avoid

1. God page objects

If your page object has 50+ methods, break it into smaller components.

2. Exposing raw locators everywhere

Encapsulate interactions: loginPage.login() instead of loginPage.submitButton.click().

3. Not waiting for navigation

After clicks that navigate, wait for the URL or element:

await this.submitButton.click();

await this.page.waitForURL(/.*dashboard/);

4. Sharing state between tests

Each test should be independent. Don't rely on previous test state.

Folder Structure for Large Projects

For 100+ tests, organize by feature:

tests/
├── pages/
├── components/
├── fixtures/
├── auth/
│   ├── login.spec.ts
│   ├── register.spec.ts
│   └── password-reset.spec.ts
├── checkout/
│   ├── cart.spec.ts
│   ├── payment.spec.ts
│   └── confirmation.spec.ts
└── admin/
    ├── users.spec.ts
    └── settings.spec.ts

Need Architecture Help?

If you're building a test automation framework and want it done right from the start, I can help design the architecture, set up page objects, and train your team on best practices.

Get in touch

Anton Gulin is the AI QA Architect, the first person to claim this title on LinkedIn. He builds AI-powered test automation systems where AI agents and human engineers collaborate on quality. Former Apple SDET (Apple.com / Apple Card pre-release testing). Find him at anton.qa or on LinkedIn.

You Were Handed Testing and No One Trained You: A Developer's Field Guide

Anton Gulin — Sat, 29 Aug 2026 15:00:41 +0000

Your team moved testing to the left. That is the industry's word for it: shift-left. Testing that used to happen at the end, done by a separate QA team, now happens earlier, done by the people writing the code.

On my most recent project, that meant the developers. Most had never opened Playwright. None of them thought like a tester. And they still had to ship tested code every sprint.

The same five questions came in every week. This is the field guide I wish I could have handed each of them on day one. If testing just landed on your desk, start here.

1. "How do I wait for the page to be ready?"

The instinct is to sleep for a few seconds and hope. Do not. A sleep is a guess. Guess too short and the test is flaky. Guess too long and your suite crawls.

Playwright already waits for you. When you act on an element, it waits until that element is ready to use. Visible, stable, clickable. Then it acts.

// Fragile: a blind guess
await page.waitForTimeout(3000);
await page.locator('#save').click();

// Correct: Playwright waits for the button to be ready, then clicks
await page.getByRole('button', { name: 'Save' }).click();

Wait for the thing, never for the clock.

2. "Why does my test pass, then fail with no change?"

That is a flaky test. It is not bad luck. It means two things raced and your test did not say which one had to finish first.

The fix is not to add a sleep. The fix is to wait for the real signal, the row appears, the spinner is gone, the network call returned.

// Flaky: asserts before the row has rendered
await page.getByRole('button', { name: 'Add' }).click();
await expect(page.getByRole('row')).toHaveCount(1);

// Stable: web-first assertion retries until the state is true
await page.getByRole('button', { name: 'Add' }).click();
await expect(page.getByRole('row', { name: 'New item' })).toBeVisible();

A flaky test is not a small annoyance. It teaches the team to ignore red, and an ignored red is where real bugs ship.

3. "What am I even supposed to check?"

Check what the user gets. Not what the console logs, not that the page loaded, the actual outcome on the screen.

// Weak: proves the page rendered, nothing more
await expect(page).toHaveURL(/checkout/);

// Strong: proves the user sees the right total
await expect(page.getByTestId('order-total')).toHaveText('$41.00');

If your assertion would still pass when the feature is broken, it is decoration, not proof.

4. "My tests are so slow."

Most slow suites log in through the UI before every single test. If you have 200 tests, that is 200 logins. Do it once.

// One-time setup: save the signed-in state
await page.context().storageState({ path: 'auth.json' });

// Every test reuses it, no login step
test.use({ storageState: 'auth.json' });

Testing the login belongs in one test. The other 199 should assume it works.

5. "It works on my machine."

Then it is not tested. It is remembered. A test that only passes with your leftover data and your logged-in browser is not proof anyone else can trust.

Run it clean and isolated, every time: fresh data, no shared login, no state left behind from the last run. If it passes on a machine that knows nothing about you, it is real.

The one habit under all five

A test is a claim that the software works. Your job is to make that claim honest. Wait for real signals, check what the user sees, keep each test independent, and when a test fails, read the evidence before you touch it. Playwright's trace viewer records exactly what the browser did, so you can tell a real bug from a broken test in about two minutes.

Shift-left handed you testing. Nobody handed you the manual. Now you have a start.

Your Regression Suite Is a Museum: 5 Questions That Decide Delete vs Keep

Anton Gulin — Sat, 22 Aug 2026 15:00:46 +0000

Every sprint adds tests. Almost no sprint deletes one.

That one-way flow has a predictable end. The suite gets slower. Flaky tests
(tests that fail randomly) pile up. Engineers stop trusting red builds.
Eventually someone suggests rewriting everything, and the cycle restarts.

There is a cheaper fix. Audit the suite with five questions.
On the last suite I inherited, they retired a third of the tests.
Nothing those tests "guarded" ever broke.

Question 1: When did this test last fail for a real reason?

Your CI history (the record of server test runs) already knows.

A test that has been green for a year has two possible explanations.
Either the code it guards never changed, or the test cannot detect change.
Both are worth knowing. Only one deserves compute on every commit.

Practical rule: pull the last 90 days of runs. Tag every test that failed
only for environment reasons, or never failed at all. Those are audit candidates.

Question 2: What user risk does it guard?

Write the risk in one sentence, naming a user.

"It tests the profile page" is not a risk.
"A user loses saved work when the session expires" is a risk.

If nobody on the team can produce that sentence, the test is guarding
an implementation detail, not a user. Details change on purpose all the time.
Tests guarding them fail on purpose all the time. That is where flakiness lives.

Question 3: Would anyone notice if it vanished?

Run the experiment instead of debating it:

# in a branch: skip the suspect test, run everything else
npx playwright test --grep-invert "@museum-candidate"

If coverage of the named risk survives through other tests, and no gap
appears in the risk list from Question 2, the test was furniture.

Delete it in the branch. Keep the branch open a week. Merge with confidence.

Question 4: Does it check results or steps?

A test that clicks through checkout and asserts the button was clickable
is a tour, not a test.

// a tour: asserts the step happened
await page.getByRole('button', { name: 'Pay' }).click();
await expect(page).toHaveURL(/confirmation/);

// a test: asserts the outcome is real
await expect(page.getByTestId('invoice-total')).toHaveText('$34.20');
await expect(page.getByTestId('invoice-number')).not.toBeEmpty();

The URL can change while the invoice ships blank. Assert on the thing
the user came for.

Question 5: Can it fail at all?

Flip the condition and run it.

// original
await expect(status).toBe('paid');
// flipped: this MUST fail. If it passes, the test is dead.
await expect(status).not.toBe('paid');

A test that passes both ways asserts nothing. AI-written tests fail this
check more than any other kind, because generators optimize for green.

Sixty seconds per suspicious test. The flip never lies.

What you get back

Five questions, one afternoon, on the oldest third of your suite.

The suite you keep is faster, and every test in it can answer
"what breaks if I go red?" That is what makes a red build mean something.

And when an AI agent starts writing tests into your suite, this audit
is the contract you hold its work against. A generated test enters
only if it survives the same five questions.

How to Review AI-Generated Tests: Seven Checks Before You Keep Them

Anton Gulin — Sat, 15 Aug 2026 15:00:43 +0000

Review AI-generated tests with seven checks. Name the user risk. Break the product. Check the final result. Change the data. Read the failure. Repeat the run. Then decide whether the test could stop a bad release.

AI can write a clean test in seconds. The file may look finished. The names may sound correct. The test may even pass.

None of those facts prove value. A useful test catches a failure that matters to users. Your review must find that proof before the test joins your suite.

I use seven checks for that decision.

1. Name the user risk

Start with the person who could get hurt. Write the risk in one sentence.

For example: "A customer sees the wrong total and pays too much."

Avoid risks like "checkout may fail." That sentence does not name the damage. It also gives the test no clear target.

Ask two questions:

Who loses something?
What do they lose?

Money, time, access, and trust are clear answers. "The feature breaks" is not.

2. Break the product

A test should fail when its protected behavior breaks. Prove that before keeping it.

AI often writes a test that follows the correct steps. The test may never check the important result.

test('customer can pay', async ({ page }) => {
  await page.goto('/checkout')
  await page.getByRole('button', { name: 'Pay' }).click()
  await expect(page.getByText('Success')).toBeVisible()
})

This test checks a message. It does not check the charged amount.

Remove the payment action or return the wrong total. The test must fail. A passing result means the test protects nothing useful.

3. Check the final result

Clicks are steps. Results are proof.

The test above clicks the right button. A stronger test checks the amount and payment record.

await expect(page.getByTestId('order-total')).toHaveText('$120.00')
await expect(page.getByTestId('payment-status')).toHaveText('Paid')

An assertion means a result check. Playwright provides assertions that wait for results. The tool can wait. You still choose the right result.

Review every assertion. Ask what user outcome it proves. Rewrite assertions that only confirm page activity.

4. Change the data

AI tends to generate a clean example. Real users bring missing, wrong, and extreme values.

Test more than one amount. Include zero, a large value, and invalid text.

for (const amount of ['0', '999999', 'wrong']) {
  await page.getByLabel('Amount').fill(amount)
  await page.getByRole('button', { name: 'Pay' }).click()
  await expect(page.getByRole('alert')).toBeVisible()
}

The exact values depend on your product. The review question stays simple. Can one neat example hide a serious failure?

5. Read the failure

Run the test against a broken result. Then read its message.

Another engineer should understand the problem without opening the whole file. Compare these messages:

Expected: "$20.00"
Received: "$120.00"

Timeout after 30000ms

The first message points to the product error. The second sends someone searching through logs.

Use clear result checks and useful test names. A failure should shorten the investigation.

6. Run it twice

Use the same input twice. You should get the same result.

Repeated runs catch shared data and timing problems. They also expose tests that depend on another test.

Do not accept a passing second run as proof. Compare both runs. Investigate any difference before keeping the test.

7. Make the release decision

Finish with one question: Would this test stop a bad release?

Name the release it could stop. For example: "This test blocks checkout when totals are wrong."

Keep the test when the answer is clear. Rewrite or delete it when the answer stays vague.

This step protects the review queue. Teams do not need every generated test. They need the small set that proves important behavior.

A five-minute review example

Imagine that AI writes a checkout test. The test adds one product and completes payment. It checks the success message.

First, name the risk. A customer could pay the wrong total.

Next, change the price calculation. The test still passes because the message appears. You found the missing proof.

Add a check for the order total. Then try an expired coupon and an empty cart. The test should explain each failed result.

Run the test twice with the same data. Both runs should match.

Finish with the release question. This test should stop checkout when the charged total is wrong. The answer now names one clear release failure.

That review improved one test without adding more code than needed. The team gained useful proof instead of another passing file.

Use the card during review

You can complete this review in a few minutes:

Name the user risk.
Break the protected behavior.
Check the final result.
Change the input data.
Read the failure message.
Repeat the same run.
Name the bad release it stops.

AI can handle test volume. You still decide what deserves trust. Keep tests that fail correctly and explain why the release should stop.

Anton Gulin builds AI systems and measurement tools. He tests software for a living and applies that discipline to AI. He runs independent LLM benchmarks and builds production test systems. Find him at anton.qa or on LinkedIn.

Test Retries Hide Real Bugs: When a Rerun Helps and When It Lies

Anton Gulin — Sat, 08 Aug 2026 15:00:40 +0000

Your build is green. One of your tests failed five minutes ago. Both of those things are true, because the test passed on a retry. Here is the short answer. A retry never fixes anything. Keep retries on in CI, but treat a retried pass as a bug report. It opens a ticket. It never closes one.

Last Saturday I posted about rerunning failed tests in isolation. Two readers pushed back, and both were more right than my post.

The first said flakiness is a signal. Turning the alarm off does not put out the fire.

The second was more specific. A team reruns the failed test alone. It passes. Everyone moves on. And the real cause, a race condition, ships to production. A race condition means two things run at the same time and collide.

This post is the concession, and the setup I now recommend.

What the rerun actually changed

Look at what happens when a test fails in CI and someone reruns it alone.

The code did not change. The data did not change. One thing changed: the test ran without the other tests around it.

So the rerun did not prove the test is fine. It proved the test is fine when nothing else is running. That is a different sentence. Your users do not visit your app one at a time.

The race that a rerun hides

Here is the simplest version of the trap:

test('admin can rename a user', async () => {
  await renameUser('user-42', 'New Name');
  await expect(profileName).toHaveText('New Name');
});

test('report shows user names', async () => {
  const report = await openReport();
  await expect(report.row('user-42')).toContainText('New Name');
});

Both tests touch the same record. Run together, they sometimes collide, and one fails. Run alone, each passes every time.

The failing run was the only honest one. It was telling you the app has a timing bug. The rerun in isolation deleted the evidence.

Playwright already tells you the truth

Here is the part most teams never look at. When a Playwright test fails and then passes on a retry, the report does not say "passed."

It says flaky.

  3 passed
  1 flaky

The tool is honest. The habit is not. Most dashboards only show green or red, so a flaky pass reads as a pass, and the count nobody reads keeps growing.

The setup that keeps retries useful

Retries have one honest job: telling infrastructure noise apart from real signal. A container that started slowly is noise. A race condition is signal. You cannot tell them apart without evidence, so collect it:

export default defineConfig({
  retries: process.env.CI ? 2 : 0,
  use: { trace: 'on-first-retry' },
});

Two lines, two jobs. The retry detects. The trace records everything about the failing run, so you can diagnose it later instead of shrugging.

Locally, retries stay at zero. On your own machine you want the failure loud and immediate.

The rule

A retried pass opens a ticket. It never closes one.

Once a week, read the flaky list. Every entry is one of two things. Infrastructure noise you should fix in the pipeline. Or a real timing bug in the app that your tests found first. Both are work. Neither is "passed."

My Saturday post said rerunning a flaky test in isolation makes things worse. These two readers explained the mechanism better than I did. The rerun does not just waste time. It manufactures false confidence and deletes the only evidence you had.

The green build is not the goal. The true build is.

Reuse One Page Object Method for Success and Failure Cases

Anton Gulin — Sat, 01 Aug 2026 15:00:51 +0000

Your login helper exists twice. One version expects the dashboard. One version expects the error. Ninety percent of the two bodies is the same code. Here is the short answer. Keep one method per user action. Let an options object say what it waits for. The test still decides what the result means.

Last week I wrote about where test assertions belong. A reader came back with the harder version of the question. If business checks live in the test, how does one method serve both cases? Good question. This post is the answer.

The duplicate everyone has

Open any page object that is more than a year old. You will find this:

async login(user: string, pass: string) {
  await this.username.fill(user);
  await this.password.fill(pass);
  await this.submit.click();
  await this.page.waitForURL('**/dashboard');
}

async loginExpectingError(user: string, pass: string) {
  await this.username.fill(user);
  await this.password.fill(pass);
  await this.submit.click();
  await this.errorBanner.waitFor();
}

Two methods. Three identical lines each. One real difference: what the method waits for at the end.

Now the login form changes. Someone adds a "remember me" checkbox. You fix the first method. You forget the second. The negative test starts failing for a reason unrelated to the negative case.

That is the cost of the duplicate. Not ugliness. Drift.

Why the boolean flag makes it worse

The first fix everyone tries is a flag:

async login(user: string, pass: string, success: boolean) { ... }

Then the test reads like this:

await loginPage.login('anton', 'wrong-password', false);

False what? You have to open the page object to find out. And flags multiply. Six months later the same method takes three of them, and nobody can read the call site at all:

await loginPage.login('anton', 'pw', false, true, false);

A flag saves a method and costs a reader. Bad trade.

Copy the shape Playwright already uses

Playwright's own API solves this everywhere. Every action takes an optional options object with named keys:

await page.getByRole('button').click({ timeout: 5000, force: true });

You never pass a bare true to Playwright. You pass a name and a value. Do the same in your page objects:

type LoginOptions = { waitFor?: 'dashboard' | 'error' };

async login(user: string, pass: string, options: LoginOptions = {}) {
  const { waitFor = 'dashboard' } = options;
  await this.username.fill(user);
  await this.password.fill(pass);
  await this.submit.click();
  if (waitFor === 'dashboard') {
    await this.page.waitForURL('**/dashboard');
  } else {
    await this.errorBanner.waitFor();
  }
}

Two things make this work. The default keeps the common call short. The named key makes the rare call readable:

// happy path, unchanged
await loginPage.login('anton', 'correct-password');

// negative path, and you can read it without opening the class
await loginPage.login('anton', 'wrong-password', { waitFor: 'error' });

One method. One place to fix when the form changes.

Notice what the option does not say

The option is called waitFor, not expectSuccess. That is deliberate.

expectSuccess: false puts a judgment inside the page object. The class starts deciding what a correct login looks like. That breaks the rule from last week: business checks live in the test.

waitFor: 'error' only says which element the method should wait for before it returns. It is a timing instruction, not a verdict. The verdict stays where a reader expects it:

test('rejects a wrong password', async ({ loginPage }) => {
  await loginPage.login('anton', 'wrong-password', { waitFor: 'error' });
  await expect(loginPage.errorBanner).toHaveText('Wrong password');
});

Read that test aloud. It says what it does and what should be true. You never open the page object.

When two methods really are right

Sometimes the duplicate is not a duplicate. Keep separate methods when the steps themselves differ:

async loginWithPassword(user: string, pass: string) { ... }
async loginWithSso(user: string) { ... }

Different fields, different clicks, different waits. These are two user actions that happen to end in the same place.

The test: if the bodies differ by more than the final wait, keep them apart. If they differ only by the final wait, merge them.

And name methods after the action, never after the outcome. loginExpectingError names a result. login names what the user does. Results belong in the test name.

The rule, in three lines

One method per user action.
An options object says what it waits for, with a default for the common case.
The test says what the result means.

Apply it once to your login helper. Then look at your checkout helper, your search helper, and your upload helper. The same pair is usually hiding in all of them.

Should Page Objects Assert? Where Test Assertions Belong

Anton Gulin — Sat, 25 Jul 2026 15:00:40 +0000

Should a page object contain assertions? Here is the short answer: business assertions belong in the test. Technical guards belong in the page object. A test must show what "correct" means for its scenario. A page object must only promise that the page is ready to use. Mixing the two is why suites become hard to read and hard to trust.

Last week I published the modern page object model. One sign of legacy design was "page objects that assert." A senior QA engineer pushed back in the comments. His position: business checks go in the test layer, but technical checks, did the page reach the right state?, can hide inside the class.

It was a fair challenge. This post is the full answer.

The two kinds of checks

Every check in a UI test is one of two kinds.

Business checks answer: did the product do the right thing? The order total is $41.97. The welcome message names the user. The discount applied.

Technical guards answer: is the page ready? The form finished loading. The spinner went away. The URL changed.

They look similar in code. They serve different readers. A business check speaks to the person deciding "is this feature broken?" A technical guard speaks to the machine deciding "can I click now?"

The rule

Put business checks in the test, always:

test('applies the discount', async ({ checkoutPage }) => {
  await checkoutPage.applyCode('SAVE10');
  await expect(checkoutPage.total).toHaveText('$35.97');
});

The expected value sits in the test file. When this fails at 2 a.m., the reader sees what "correct" was supposed to be. No file jumping.

Handle technical guards inside the page object, but prefer waiting over asserting:

export class CheckoutPage {
  readonly total: Locator;

  async applyCode(code: string) {
    await this.codeInput.fill(code);
    await this.applyButton.click();
    await this.priceUpdate.waitFor({ state: 'visible' });
  }
}

The page object does not judge the total. It makes one promise: when applyCode returns, the page finished reacting. That is a technical guard, and note it is a wait, not an assert. Playwright's web-first assertions and auto-waiting handle most of these guards for free.

Why hidden business asserts hurt

Three costs show up at scale.

The expected value disappears. checkoutPage.verifyTotal() hides $35.97 in another file. The failing test cannot tell you what it believed.

The page object takes sides. Fifty tests share that class. One scenario needs a different expected total, and the shared method becomes a maze of parameters.

Failures point at the wrong layer. When an assert fires inside a page object, the stack trace blames plumbing. The reader has to dig to find which business rule broke.

Where it gets honestly debatable

My commenter's position (hidden technical assertions are fine) is workable. Plenty of strong suites do it. My preference is stricter for one reason: an assert stops the test with a verdict; a wait just holds the door. Verdicts belong to tests. But if your team hides technical guards as asserts and everyone can read the failures, that is a style choice, not a defect.

What is a defect: expected business values living anywhere except the test body.

The migration path

Same as the POM modernization: no big rewrite. When a change touches a page object that asserts, move the business expectation up into the tests that call it, and convert the technical remainder into a wait. Each class takes minutes.

Run this to find your candidates:

grep -rn "expect(" src/pages/

Every hit is either a business check to promote or a guard to convert.

The takeaway

Business checks: in the test, expected values written out.
Technical guards: in the page object, as waits, not verdicts.
Playwright's auto-waiting already covers most guards, delete before you migrate.

The Modern Page Object Model: Less Shared Code, Easier Changes

Anton Gulin — Sat, 18 Jul 2026 15:00:40 +0000

A page object model (POM) organizes browser tests by app page. Each page or component gets one class. The class stores element finders, called locators. It also stores user actions. Tests call those actions instead of using selectors directly. When a page changes, you fix one class. You do not fix two hundred tests.

The basic idea is old. Modern Playwright changes how we should build it.

Many page objects still follow Selenium tutorials from 2015. They work, but they ignore useful Playwright features. Here are five signs and the simpler pattern that replaces them.

Sign 1: Every page object extends `BasePage`

export class LoginPage extends BasePage {
  constructor(driver: Driver) { super(driver); }
}

Inheritance means one class receives behavior from a parent class. The 2015 logic made every page share one parent. That parent often becomes a junk drawer. It collects waits, logs, screenshots, and unused helpers.

Inheritance ties every page to the parent class. Modern page objects need less shared code. Shared helpers can live in plain functions. Test setup can live in fixtures, which prepare objects for each test.

Sign 2: Wait methods everywhere

await loginPage.waitForPageToLoad();
await loginPage.waitForSpinnerToDisappear();

Playwright checks elements before many user actions. For click, it checks visibility, stability, events, and enabled state. Many manual wait methods only repeat those checks. They can also hide timing bugs.

Wait explicitly only for conditions Playwright cannot infer. One example is a dashboard finishing a calculation. Use an assertion, which checks an expected result:

await expect(total).toHaveText('41.97');

Sign 3: Locators buried inside methods

async login(user: string, pass: string) {
  await this.page.locator('#username').fill(user);
  await this.page.locator('#password').fill(pass);
  await this.page.locator('button[type=submit]').click();
}

Hidden locators make page dependencies hard to see. Declare each locator once in the constructor:

export class LoginPage {
  readonly username: Locator;
  readonly password: Locator;
  readonly submit: Locator;

  constructor(readonly page: Page) {
    this.username = page.getByLabel('Username');
    this.password = page.getByLabel('Password');
    this.submit = page.getByRole('button', { name: 'Sign in' });
  }

  async login(user: string, pass: string) {
    await this.username.fill(user);
    await this.password.fill(pass);
    await this.submit.click();
  }
}

Now every locator is visible at a glance. The code also uses user-facing names through getByRole and getByLabel. Those names often survive redesigns. A CSS selector like #username may not.

Sign 4: Tests build their own page objects

test('login works', async ({ page }) => {
  const loginPage = new LoginPage(page);   // every test, every file
  ...
});

This setup repeats in every test. A Playwright fixture prepares the page object once:

// fixtures.ts
import { test as base } from '@playwright/test';
import { LoginPage } from './pages/login-page';

export const test = base.extend<{ loginPage: LoginPage }>({
  loginPage: async ({ page }, use) => {
    await use(new LoginPage(page));
  },
});

// login.spec.ts
import { test } from './fixtures';

test('login works', async ({ loginPage }) => {
  await loginPage.login('anton', 'secret');
});

The test asks for loginPage and receives a ready object. There is no repeated setup. One fixture can also depend on another fixture.

Sign 5: Page objects that assert

A loginPage.verifyDashboardIsCorrect() method lets the page object define "correct." The expected result now hides inside a shared class.

Modern split: page objects act, tests assert. The page object returns locators or values. The test states the expectation in plain sight:

await loginPage.login('anton', 'secret');
await expect(dashboard.greeting).toHaveText('Welcome, Anton');

When this fails, the expected value is visible in the test. You know what broke.

The migration path (no rewrite required)

You do not need a full rewrite:

New page objects follow the modern shape from day one.
When a test touches an old class, upgrade only that class.
Delete extends BasePage and move locators into the constructor.
Delete duplicate wait methods and move assertions into tests.
Add fixtures early. New tests get clean setup while old tests keep working.

Do AI agents change any of this?

They make this structure more important. Page objects give an AI agent a small list of approved actions. Raw selectors make the agent rediscover each page. That creates fragile tests. Calling loginPage.login() uses the same reviewed action as a human-written test.

Small, flat page objects give machines fewer ways to make mistakes. Large parent classes give them more choices.

The pattern in one line

Declare locators in the constructor, user-facing. Let fixtures do the wiring. Let auto-waiting do the waiting. Keep assertions in tests. Share nothing through inheritance.

Your page objects should be the most boring code you own. That is what makes them last another ten years.

Anton Gulin is the AI QA Architect &#8212 the first person to claim this title on LinkedIn. He builds AI-powered test automation systems where AI agents and human engineers collaborate on quality. Former Apple SDET (Apple.com / Apple Card pre-release testing). Find him at anton.qa or on LinkedIn.

Your AI Model Is a Dependency: Pin It, Keep a Fallback, Re-Verify

Anton Gulin — Sat, 11 Jul 2026 15:34:42 +0000

Key takeaways

Treat the AI model in your test pipeline like any other dependency. Pin the exact model ID in one config file. Keep a fallback model that has already passed your real suite. Re-run the same suite on both models on a schedule. When a model changes, disappears, or gets swapped, the switch becomes a one-line change instead of an emergency.

The 19-day proof

Nineteen days. That is how long one of the world's best AI models was simply gone this summer.

Claude Fable 5 went offline on June 12 by government order. It came back on July 1. Between those dates, every test suite that leaned on it had a problem. Some teams fixed it in one line. Others lost days, twice.

The difference was not luck. It was whether they treated the model like what it is: a dependency.

What "the model is a dependency" actually means

Your test suite already has dependencies. A database version. A browser version. A Node version. You pin them all. (Pinning means locking the exact version so nothing upgrades by itself.)

An AI model is the same kind of moving part, with three extra ways to hurt you:

It changes silently. Providers update models behind the same name. The model you tested in March is not always the model answering in July.
It disappears. Deprecations happen every quarter. And as of this summer, so do government-ordered shutdowns. Fable 5 was not deprecated. It was switched off overnight, worldwide.
It gets swapped without telling you. The fine print of the Fable 5 return says blocked requests are rerouted to a different model (Opus 4.8). Your pipeline asks one brain and sometimes gets another.

A test that stands on a part like this, unpinned and unwatched, is not a test. It is a hope.

Rule 1: Pin the version

Never let a test suite float on "latest" or on a bare model family name. Point it at the exact model ID, in one place.

// config/models.ts: ONE place the whole suite imports from
export const MODELS = {
  primary: "claude-fable-5",      // pinned: the exact ID we validated
  fallback: "claude-opus-4-8",    // pinned: the exact ID we validated
} as const;

Every agent, every AI-assisted test imports from this file. Nothing names a model directly. When the world changes, you edit one line, not forty files.

If you use an agent framework, the same rule applies to its config. In Stagehand, for example, the model is an explicit setting: set it, do not rely on an implicit choice:

const stagehand = new Stagehand({
  modelName: MODELS.primary,   // never omit this
});

Rule 2: Keep a fallback you have already validated

A fallback you pick during the outage is not a fallback. It is a gamble made under pressure.

Pick the second model now, on a calm day. The bar is simple: it must run your real suite acceptably. Not "it is a good model" , your suite, green, at a cost you accept.

Write it into the same config file (see MODELS.fallback above). One line to switch, pre-approved, pre-tested.

Rule 3: Re-run the same suite on both

This is the rule most teams skip, and it is the one that makes the other two real.

A fallback is only valid while it stays valid. Models drift. So, on a schedule, run your same test suite against both models and compare:

// parity.spec.ts: the same checks, both brains
for (const model of [MODELS.primary, MODELS.fallback]) {
  test(`checkout flow passes on ${model}`, async () => {
    const agent = makeAgent(model);
    await agent.run("complete checkout for the seeded cart");
    // The fixed check the agent cannot move: same for both models:
    expect(await getOrderTotal()).toBe(41.97);
  });
}

Two details carry this pattern:

The assert is model-independent. The known answer (41.97 for a seeded cart) comes from your test data, not from the model. Either brain must reach the same truth.
Run it weekly, not "someday." A parity suite that ran last night makes a model switch a non-event. A parity suite that never runs makes it an emergency.

What this cost the two kinds of teams

When Fable 5 went dark, the pinned teams with a validated fallback did this: change one line, run the suite, ship. When it came back July 1, they did it again in reverse. Two boring mornings.

The floating teams debugged broken builds twice in three weeks, once out, once back. Same event, same tools. The whole difference was written before the crisis: one config file, one spare model, one recurring suite.

The checklist

[ ] Every model reference goes through one config file
[ ] Model IDs are exact and pinned, no "latest", no bare family names
[ ] A fallback model is chosen, and it has passed your real suite
[ ] A parity suite runs both models on a schedule
[ ] A model switch is documented as a one-line change anyone can make

You would not float your database version in production. Your AI model earns the same respect. It is infrastructure now, and this summer proved it can vanish like infrastructure too.

How to Implement AI in QA (2026): A Practical Framework

Anton Gulin — Sat, 04 Jul 2026 15:40:25 +0000

Key takeaways

To implement AI in QA, let AI do the work and let a fixed check decide the result. Use AI to generate tests, repair broken selectors, and explore your app. Never let AI grade its own output. Add an independent check the AI cannot change, test for repeatable results, and test that the agent did only what you asked.

What "AI in QA" actually means

AI in QA means using an AI model to help test software. That is the whole idea. The model can write test cases, fix tests that broke, click through your app like a user, or read a failure and guess the cause.

It does not mean the AI replaces testing. It means the AI does some of the work a tester used to do by hand. The judgment stays with you.

I test software for a living. The teams that win with AI in QA all draw the same line. AI does the work. A human, and a fixed check, decide if the work is good.

The one rule that keeps it safe

Here is the rule the rest of this guide hangs on.

Let AI do the work. Never let AI judge its own work.

Picture an AI agent that tests your login. It clicks around. It reports green. Everyone relaxes. But the agent decided what "pass" means. If it is too kind, it passes a broken page. Now you shipped a bug with a green check on top.

An AI that grades its own work is not a test. It is an opinion.

So you give the AI room to explore, and you keep one thing it cannot touch. A fixed check. A known-good answer. A hard assert (a check that fails loudly) on the real outcome. The agent finds the path. The fixed check says pass or fail.

In testing this fixed answer has a name: an oracle. The oracle is the part the system being tested is not allowed to influence. Keep your oracle out of the AI's reach and most AI-in-QA risk goes away.

Where AI helps in QA (the 4 good jobs)

These four jobs are where AI pays off today.

Writing tests. Point the model at a page or a user story. It drafts test cases, including edge cases a tired human skips. You review and keep the good ones.
Fixing broken tests. A button moved and the test broke. AI can find the new selector (how a test finds a button) and propose the fix. This is the biggest time-saver for most teams.
Exploring the app. An AI agent can wander your app like a curious user and report what feels broken. Great for finding the bug nobody wrote a test for.
Reading failures. When a test fails, AI can read the log and the trace and suggest the likely cause. It turns a wall of red into a short list to check.

In all four, the AI proposes. You and your fixed checks dispose.

Where AI lies in QA (the 4 traps)

This is the part most guides skip. AI in QA fails in four ways. Plan for each.

It passes a broken thing. A too-kind agent calls a broken page "fine." Fix: an independent oracle the agent cannot move.
It is not repeatable. The same input passes now and fails in ten minutes. Fix: run the same input twice and compare the shape of the answer.
It does too much. You asked for one thing. The agent also changed a setting or sent a message. Fix: a scope check on what it touched.
It depends on a model that can change. The model under your tool updates, or even goes offline, and your tests shift with it. Fix: pin the model version and keep a fallback.

That last one is not theoretical. In June 2026 a widely used model was pulled offline overnight. Teams that pinned their model switched to a fallback in one line. Teams that did not found out when their build broke.

A working example: an AI agent with an oracle it cannot move

Here is the pattern in code. An AI agent books a meeting room. Then three fixed checks decide if it really worked. The agent never grades itself.

import { test, expect } from '@playwright/test';
import { Stagehand } from '@browserbasehq/stagehand';

test('AI books a room: and only that', async ({ page }) => {
  // Pin the model. Do not let it auto-upgrade under your tests.
  const stage = new Stagehand({ env: 'LOCAL', model: 'anthropic/claude-opus-4-8' });
  await stage.init();

  // 1) Let the AI do the work. It decides HOW to book the room.
  await stage.act('Book room B for 2pm tomorrow, for 30 minutes');

  // 2) The fixed check the AI cannot move (the oracle).
  //    These helpers read your real database, not the agent's report.
  const booking = await getBookingFromDb({ room: 'B', time: '14:00' });
  expect(booking).toBeTruthy();          // it did the task
  expect(booking.durationMin).toBe(30);  // exactly what we asked for

  // 3) Scope check. Did it touch anything it should not have?
  const otherChanges = await getChangesExcept(booking.id);
  expect(otherChanges).toHaveLength(0);  // no surprise side effects
});

Read the three checks again. The agent's own "I booked it" is never trusted. The database is the oracle. The duration check catches a sloppy booking. The scope check catches the agent doing extra. (getBookingFromDb and getChangesExcept are your own helpers. They read real state, not the agent's words.)

To catch the repeatable-result trap, run the same prompt twice and compare:

test('same request, same result', async () => {
  const a = await runBooking('Book room B for 2pm tomorrow, 30 minutes');
  const b = await runBooking('Book room B for 2pm tomorrow, 30 minutes');
  // The wording of the agent's reply may differ. The outcome may not.
  expect(a.room).toBe(b.room);
  expect(a.durationMin).toBe(b.durationMin);
});

The model is allowed to phrase its answer differently each time. It is not allowed to book a different room.

The 3 tests every AI feature needs

If you ship an AI feature to users, these three tests catch the failures that page you at 2am. Most teams only write the first easy one ("does it give a good answer?").

The wrong-input test. Feed it junk, empty fields, another language, a user trying to break it. A good feature fails safely. A bad one is confidently wrong.
The same-input-twice test. Run the exact input twice. Same kind of answer? Different wording is fine. Pass-then-fail is not.
The scope test. Did it do only what you asked? Or did it also change a setting, send a message, or touch a file? Extra is not helpful. Extra is a future incident.

Where to start on Monday

You do not need a platform or a budget. Start small.

Pick one flaky test. Let an AI tool propose the fix. You keep final say.
Add one oracle. Take your most important flow and add a hard check on the real outcome, not the agent's report.
Pin your model. Lock the version your AI tools use. Add a fallback.
Add the scope check to one agent run. See what it touches when you are not looking.

Do those four and you have AI in QA that you can trust. The AI does more work. You keep the judgment. The fixed checks keep everyone honest.

That is the whole job: the gap between "the AI says it passed" and "it passed, for the right reason."

How to Test Passkey (WebAuthn) Login in Playwright (2026)

Anton Gulin — Sat, 27 Jun 2026 15:43:03 +0000

Key takeaways

You can now test passkey login in Playwright with no hardware key. Playwright 1.61 added a virtual authenticator (a fake security key). Your test seeds a passkey, turns it on, and the page signs in as if a real key answered. It works in every browser and runs in CI. The API is browserContext.credentials, with three methods: create(), install(), and get().

What is a passkey, in plain words

A passkey is a login with no password. You sign in with your face, your fingerprint, or a device PIN. The hard part lives in your device. The website only sees a signed reply.

The browser standard behind this is called WebAuthn. It means "web authentication". When you log in, the browser runs a small back-and-forth with the site. The site asks. Your device answers and signs. This is the part that used to need real hardware.

Apple, Google, and most banks ship passkeys now. If your app has a "sign in with a passkey" button, you have this flow in production today.

Why nobody tested this flow

Here is the part nobody talks about. Almost nobody tests the passkey login.

For years it was hard. To test a passkey you needed a real security key plugged into the machine. You cannot plug a USB key into a CI server. CI is a remote build machine with no hands and no ports.

So the most important login flow shipped untested. The one thing a user does first. The one thing that locks them out if it breaks.

I test software for a living. An untested login is the scariest gap on the list. If sign-in breaks, nothing else matters. The cart, the dashboard, the settings page, all of it sits behind the door. On one project I watched a broken auth path block every other test for two days. The fix took ten minutes. Finding it took the two days.

Playwright 1.61 closed this gap.

What Playwright 1.61 added

Playwright 1.61 shipped on June 15, 2026. It added a virtual authenticator (a fake security key).

A virtual authenticator is software that pretends to be a hardware key. Your test creates one. It seeds a passkey into it. From then on, when the page calls the browser to sign in, Playwright answers for the key. No real device. No USB port. The page cannot tell the difference.

You reach it through a new class called Credentials, on the browser context: browserContext.credentials. It has three methods you will use most:

create() seeds a test passkey for a site.
install() turns the virtual key on for the page.
get() reads back any passkey the page registered, so you can save it and reuse it later.

This works in all three browser engines Playwright drives. So one test covers Chromium, Firefox, and WebKit.

How to test passkey login: a working example

Here is a complete test. It seeds a passkey, turns on the virtual key, then signs in. Read the comments for what each step does.

// passkey-login.spec.ts
// Tested against Playwright 1.61. Run with: npx playwright test
import { test, expect } from '@playwright/test';

test('user signs in with a passkey', async ({ browser }) => {
  // A fresh, clean browser session for this test.
  const context = await browser.newContext();

  // STEP 1: Seed a passkey for our site.
  // 'example.com' is the site domain (the "relying party id").
  // With only the domain, Playwright makes a fresh key for us.
  await context.credentials.create('example.com');

  // STEP 2: Turn the virtual key on.
  // From now on, the page's sign-in calls are answered by our key,
  // not by real hardware. Call this before the page loads.
  await context.credentials.install();

  // STEP 3: Let the page use it.
  const page = await context.newPage();
  await page.goto('https://example.com/login');

  // The page calls the browser to sign in. Our key answers.
  await page.getByRole('button', { name: 'Sign in with a passkey' }).click();

  // Check the user is in.
  await expect(page.getByText('Welcome back')).toBeVisible();
});

The three steps map to the three method calls. First you create() a passkey for your site. Then you install() the virtual key, which makes the page's sign-in calls run through it. Then the page does its normal login, and your key answers in place of hardware.

One note on order. Call install() before the page touches sign-in. The virtual key only answers calls that happen after you turn it on.

Re-using a passkey across tests

Often you want to register a passkey once, then reuse it in many tests. A passkey holds a private key (a secret only your device knows). You can read that secret back with get() and seed it into a later test.

// In a setup test: register once, then read the passkey back.
const created = await context.credentials.get({ rpId: 'example.com' });
// `created` holds the passkey fields, including its keys.
// Save them, then seed an identical passkey in a later test:
await otherContext.credentials.create('example.com', {
  id: created[0].id,
  userHandle: created[0].userHandle,
  privateKey: created[0].privateKey,
  publicKey: created[0].publicKey,
});

This is how you keep one stable test user across a whole suite. You do not re-register on every test. You seed the same passkey each run. See the Credentials docs for the full field list.

The honest part: what this does not test

A virtual key is not a real key. So this approach tests your login flow, not the physical hardware. It will not catch a bug in a specific phone's secure chip or a real fingerprint reader. It tests the part you own: the page, the back-and-forth, the server check.

For most teams that is the right line. The browser and the operating system test the hardware path for you. Your job is to test that your app asks the right question and trusts the right answer. That is exactly what the virtual key lets you do, in CI, on every push.

Why this matters for your CI pipeline

Before 1.61, your passkey login had two test options. Skip it, or test it by hand. Both are bad. A skipped test means a silent break. A by-hand test runs once a release, not once a push.

Now it runs like any other test. It sits in your suite. It runs on every pull request. If someone changes the login and breaks the passkey path, the build goes red before the change ships. That is the whole point of a test. Catch the break in seconds, not from an angry user.

If your app supports passkeys, this is the test you write this week. The excuse is gone. The login everyone ships and nobody verifies is now testable.

Related reads on anton.qa:

Official sources:

Playwright Best Practices: 10 Rules AI Agents Get Wrong (2026)

Anton Gulin — Sat, 20 Jun 2026 15:51:36 +0000

Playwright best practices are the rules that keep browser tests stable and easy to read. Use role-based locators (find by what users see), web-first assertions that auto-wait, and isolated tests. Seed data through the API (direct requests), not the UI. Avoid hard waits, conditional logic, and tests tied to your HTML. Turn on traces and run in parallel.

An AI agent can write 50 Playwright tests in a minute. That feels fast.

Then those tests fail at random, and nobody knows why. The agent copied old patterns from its training data. It does not know the run failed last night.

This guide lists the 10 best practices that keep tests stable. For each one, I show a small correct example. I also show what AI code agents get wrong. AI tools like Copilot, Cursor, and even Playwright codegen (the test recorder) lean on stale habits. Someone has to fix that.

1. Find elements the way a user sees them

A locator (a pointer to an element) should match what a person sees on screen. Use getByRole, getByLabel, or getByText. These read like the page. They also survive a redesign of your HTML.

import { test, expect } from '@playwright/test';

test('user can sign in', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('ada@example.com');
  await page.getByRole('button', { name: 'Sign in' }).click();
});

What AI agents get wrong: they reach for CSS or XPath (brittle path selectors) like page.locator('div.btn-primary > span'). Change one class name and the test breaks.

2. Use web-first assertions that wait for you

A web-first assertion (a check that auto-waits) retries until the page is ready. expect(locator).toBeVisible() waits on its own. You never add a fixed sleep.

import { test, expect } from '@playwright/test';

test('welcome message appears', async ({ page }) => {
  await page.goto('/dashboard');
  await expect(page.getByText('Welcome back')).toBeVisible();
});

What AI agents get wrong: they add await page.waitForTimeout(3000) (a hard pause). Hard waits are the top cause of flaky tests (tests that fail at random). Too short, the test fails. Too long, the suite crawls.

3. Keep every test isolated

Isolated means each test starts clean. No shared login. No leftover data from the test before. Playwright gives each test a fresh browser context (a clean session). Set up state in a hook, not across tests.

import { test, expect } from '@playwright/test';

test.beforeEach(async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('Email').fill('ada@example.com');
  await page.getByRole('button', { name: 'Sign in' }).click();
});

test('shows the account name', async ({ page }) => {
  await expect(page.getByRole('heading', { name: 'Ada Lovelace' })).toBeVisible();
});

What AI agents get wrong: they chain tests, where test 2 needs test 1 to run first. One failure then breaks the whole file.

4. Seed state through the API, not the UI

To test a page, you often need data first. A user, an order, a draft. Do not click through ten screens to make it. Send the data straight to your backend with the request fixture (a built-in HTTP client). It is faster and steadier.

import { test, expect } from '@playwright/test';

test('opens an existing project', async ({ page, request }) => {
  const res = await request.post('/api/projects', {
    data: { name: 'Apollo' },
  });
  expect(res.ok()).toBeTruthy();

  await page.goto('/projects');
  await expect(page.getByText('Apollo')).toBeVisible();
});

What AI agents get wrong: they build the data through the UI every time. The test gets long and slow, and a setup step fails for reasons that have nothing to do with the real check.

5. Do not lean on test IDs by default

A test ID (a tag added just for tests, like data-testid) works as a fallback. But reach for getByRole and getByLabel first. Those test what a real user can do. A test ID only proves an attribute exists.

import { test, expect } from '@playwright/test';

test('cart shows one item', async ({ page }) => {
  await page.goto('/cart');
  // Prefer a real role over a test id.
  await expect(page.getByRole('listitem')).toHaveCount(1);
});

What AI agents get wrong: they paste data-testid on everything. The tests pass even when the button has no label and a screen reader (assistive software) cannot find it. The test misses a real bug.

6. Turn on traces for the first retry

A trace (a full recording of the run) shows every step, the DOM, and the network. Set it to record only on the first retry of a failed test. You get the evidence for failures, and clean runs stay fast.

// playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  retries: 1,
  use: {
    trace: 'on-first-retry',
  },
});

What AI agents get wrong: they leave tracing off, or set trace: 'on' for every run. Off means no evidence when a test fails. Always-on slows the suite and fills your disk.

7. Run tests in parallel and shard them

Parallel means many tests run at once. Playwright does this by default. For one big file of independent tests, set parallel mode. To split a slow suite across machines, use sharding (run a slice per machine).

import { test, expect } from '@playwright/test';

test.describe.configure({ mode: 'parallel' });

test('loads home', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveTitle(/Home/);
});

Split across three machines on CI (your build server):

npx playwright test --shard=1/3

What AI agents get wrong: they write tests that share a database row or a single user. Run those in parallel and they fight each other, so you get flaky tests.

8. Keep `if` and `try` out of your tests

A test should walk one clear path. No branching. If a test asks "is the button there? if so click it," it hides a bug. The button should always be there. Assert it.

import { test, expect } from '@playwright/test';

test('checkout button works', async ({ page }) => {
  await page.goto('/cart');
  // Assert the state. Do not guess it with an if.
  const checkout = page.getByRole('button', { name: 'Checkout' });
  await expect(checkout).toBeEnabled();
  await checkout.click();
});

What AI agents get wrong: they wrap clicks in if (await locator.isVisible()) to stop errors. That hides the real failure. A test that skips its own check still goes green.

9. Test what users see, not how it is built

Test the behavior, not the internals. Check the visible result. Do not check a CSS class, a state variable, or a function name. Those change when you refactor (rewrite the code), even though the app still works.

import { test, expect } from '@playwright/test';

test('shows a success message after submit', async ({ page }) => {
  await page.goto('/contact');
  await page.getByLabel('Message').fill('Hello');
  await page.getByRole('button', { name: 'Send' }).click();
  // Check the user-facing result, not an internal class.
  await expect(page.getByText('Thanks, we got your message')).toBeVisible();
});

What AI agents get wrong: they assert on class="is-active" or an exact HTML shape. The test breaks on every redesign, even when nothing real changed.

10. Define projects in your config

A project (a named test setup) in playwright.config.ts runs the same tests under different settings. Use projects to cover Chromium, Firefox, and WebKit (the three main browser engines). One config, full coverage.

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: 1,
  use: { trace: 'on-first-retry' },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
  ],
});

What AI agents get wrong: they hard-code one browser, or copy a config with no projects array. The suite then tests Chrome only, and a Safari-only bug ships to users.

The human still owns the standard

AI writes the first draft fast. That part is real, and it is useful. But the first draft copies patterns from old code on the internet. It adds hard waits. It clicks through the UI to seed data. It wraps fragile steps in if blocks so the run stays green.

A green suite that proves nothing is worse than no suite. It buys false trust.

So the workflow is simple. Let the agent write the draft. Then a human reads it against these 10 rules and fixes what the agent got wrong. The agent moves fast. The human keeps the tests honest. That is the job of an AI QA Architect.

Build the tests with AI. Then make them stable yourself.

DEV Community: Anton Gulin

Page Object Model in Playwright with TypeScript: The Complete Guide

What is the Page Object Model?

Why Use Page Objects?

Project Structure

Creating a Base Page Class

Creating a Login Page Object

Creating a Dashboard Page Object

Using Page Objects in Tests

Advanced: Component Objects

Advanced: Using Playwright Fixtures

Best Practices

Folder Structure for Large Projects

Need Architecture Help?

You Were Handed Testing and No One Trained You: A Developer's Field Guide

1. "How do I wait for the page to be ready?"

2. "Why does my test pass, then fail with no change?"

3. "What am I even supposed to check?"

4. "My tests are so slow."

5. "It works on my machine."

The one habit under all five

Your Regression Suite Is a Museum: 5 Questions That Decide Delete vs Keep

Question 1: When did this test last fail for a real reason?

Question 2: What user risk does it guard?

Question 3: Would anyone notice if it vanished?

Question 4: Does it check results or steps?

Question 5: Can it fail at all?

What you get back

How to Review AI-Generated Tests: Seven Checks Before You Keep Them

1. Name the user risk

2. Break the product

3. Check the final result

4. Change the data

5. Read the failure

6. Run it twice

7. Make the release decision

A five-minute review example

Use the card during review

Test Retries Hide Real Bugs: When a Rerun Helps and When It Lies

What the rerun actually changed

The race that a rerun hides

Playwright already tells you the truth

The setup that keeps retries useful

The rule

Reuse One Page Object Method for Success and Failure Cases

The duplicate everyone has

Why the boolean flag makes it worse

Copy the shape Playwright already uses

Notice what the option does not say

When two methods really are right

The rule, in three lines

Should Page Objects Assert? Where Test Assertions Belong

The two kinds of checks

The rule

Why hidden business asserts hurt

Where it gets honestly debatable

The migration path

The takeaway

The Modern Page Object Model: Less Shared Code, Easier Changes

Sign 1: Every page object extends BasePage

Sign 2: Wait methods everywhere

Sign 3: Locators buried inside methods

Sign 4: Tests build their own page objects

Sign 5: Page objects that assert

The migration path (no rewrite required)

Do AI agents change any of this?

The pattern in one line

Your AI Model Is a Dependency: Pin It, Keep a Fallback, Re-Verify

Key takeaways

The 19-day proof

What "the model is a dependency" actually means

Rule 1: Pin the version

Rule 2: Keep a fallback you have already validated

Rule 3: Re-run the same suite on both

What this cost the two kinds of teams

The checklist

How to Implement AI in QA (2026): A Practical Framework

Key takeaways

What "AI in QA" actually means

The one rule that keeps it safe

Sign 1: Every page object extends `BasePage`

8. Keep `if` and `try` out of your tests