Playwright Assertions: The Complete Guide with Real-World Examples

What are Assertions?

Assertions verify that your application behaves exactly as expected.

Without assertions, a test simply performs actions without validating the outcome.

Assertions are one of the most important parts of any automation framework because they determine whether a test passes or fails.

Why Playwright Assertions are Better

Playwright assertions automatically wait until the expected condition becomes true.

This eliminates many flaky tests caused by timing issues.

Benefits include:

• Auto Waiting
• Better Stability
• Cleaner Code
• Better Error Messages
• Faster Debugging

expect()

Basic Assertion

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

test('Verify title', async ({ page }) => {
    await page.goto('https://example.com');

    await expect(page).toHaveTitle(/Example/);
});

toBeVisible()

Verify an element is visible.

await expect(
    page.getByRole('button', {
        name: 'Login'
    })
).toBeVisible();

toHaveText()

await expect(
    page.locator('.message')
).toHaveText('Welcome');

Use when the complete text must match exactly.

toContainText()

await expect(
    page.locator('.message')
).toContainText('Welcome');

Use when only part of the text matters.

toHaveValue()

await expect(
    page.locator('#email')
).toHaveValue('admin@test.com');

Perfect for validating input fields.

toBeChecked()

await expect(
    page.getByRole('checkbox')
).toBeChecked();

Useful for:

• Checkboxes
• Radio Buttons

toBeEnabled() and toBeDisabled()

await expect(
    page.getByRole('button', {
        name: 'Submit'
    })
).toBeEnabled();

await expect(
    page.getByRole('button', {
        name: 'Submit'
    })
).toBeDisabled();

toHaveURL()

await expect(page)
.toHaveURL('https://example.com/dashboard');

Great for verifying navigation.

toHaveTitle()

await expect(page)
.toHaveTitle(/Dashboard/);

toHaveCount()

await expect(
    page.locator('.product')
).toHaveCount(12);

Useful for:

• Search Results
• Tables
• Product Lists

Soft Assertions

Continue execution even if an assertion fails.

expect.soft(
    await page.locator('.message')
).toContainText('Success');

Useful when validating multiple UI elements in one test.

Best Practices

Enterprise Best Practices

• Validate business behavior instead of implementation details.
• Prefer Playwright assertions over manual if statements.
• Keep assertions close to the action being validated.
• Avoid unnecessary assertions.
• Make assertion messages meaningful.

Common Mistakes

Avoid manual if statements:

if(text=="Success") {
    // manual check
}

Instead use:

await expect(locator)
.toHaveText("Success");

Avoid hardcoded waits:

await page.waitForTimeout(5000);

Instead:

await expect(locator)
.toBeVisible();

Interview Questions

Why are Playwright assertions more reliable than manual validation?

Because they automatically retry until the expected condition becomes true or the timeout expires.

Difference between toHaveText() and toContainText()?

toHaveText() requires an exact match. toContainText() checks for partial text.

When should soft assertions be used?

When validating multiple independent UI elements without stopping the test after the first failure.

Summary

Playwright assertions provide a modern, reliable way to validate web applications.

By leveraging automatic waiting, descriptive error messages, and expressive APIs, they significantly reduce flaky tests and improve test maintainability.

Mastering assertions is essential for writing production-ready Playwright automation frameworks.