Playwright assertion magic

Playwright’s assertions drive the precise test accuracy, provide early bug detection and empower testers to create robust and reliable automation scripts by increasing time and resource efficiency in the testing process. In this article, we discover how assertions are used in testing, reveal their categories and learn how to handle them in Playwright. Don’t hesitate to uncover how to benefit from assertions in different testing scenarios to deliver high-performing software products.

Passionate Dev and test automation enthusiast. Michael believes testing should be easy and fun. Thus, he has created Codeception (PHP) and CodeceptJS (NodeJS) frameworks for easy BDD-style tests. Full-time open-source contributor since 2013, tech consultant, corporate trainer, and conference speaker. Currently serving as the CTO role and chief development of our test management tool. Also, enjoys kayaking, hiking, and playing Heroes 3. Come on, connect with Michael on Twitter and other social media ↩️

In the testing process, assertions help testing and development teams to deliver reliable and robust software products. Serving as checkpoints within automated tests, they effectively verify whether the app functions correctly as expected and help development teams address issues promptly.

Furthermore, assertions lead to script stability and maintenance – you are always in the know that any changes or modifications do not go unnoticed. Beyond these core functionalities, assertions contribute to comprehensive test coverage and make the testing process more effective and reliable.

What are assertions in testing?

In the context of testing, assertions refer to statements or conditions that the QA engineers expect from Playwright test to be true during the test execution. Embedded within the test script, these statements help detect issues of the product under Playwright test and verify whether it behaves as expected. Among other pluses, we may point the following ones:

  • The possibility to indicate a deviation from the expected behavior.
  • The possibility to act as a test scenario and maintain it as a form of artifact in the documentation.
  • The possibility to facilitate efficient debugging and provide specific information about what went wrong to streamline the process of identifying and fixing errors or error.
  • The possibility to provide continuous monitoring of application behavior to make sure that changes in the codebase are promptly identified in time.

What are the categories of assertions?

The categories of assertions in software testing encompass a diverse set of validations tailored to different aspects of an application. These categories include:

  • APIResponseAssertions. This category is specifically designed to validate API responses. You can not only verify the HTTP status code, but also check response body content with the presence of expected headers and validate the structure of the API response.
  • GenericAssertions. This category is versatile enough to be applied across different scenarios and include general-purpose assertions to help in validating data types, equality, etc.
  • LocatorAssertions. This category of assertions allows you to validate the presence, visibility, or attributes of UI elements on a webpage. For example, you can check if a button is visible or confirm the value of an input field.
  • PageAssertions. This category of assertions provides high-level validations related to the overall state or behavior of a web page and cover interactions with the entire page (page title, URL, or the presence of specific components) rather than individual elements.
  • SnapshotAssertions. This category of assertions validates the visual consistency of the web application across different states or versions where the user interface’s appearance is critical and focuses on capturing and comparing the entire visual representation of a page.

To sum up, each category serves a distinct purpose in order to make sure that Playwright test assertions are reliable and correct. Whether they involve API interactions, web element validations, or visual consistency checks, this helps you confirm that every aspect of your app aligns with the expected behavior and design standards.

“Hard” and “Soft” Playwright assertions: what are they?

The terms “hard assertions” and “soft assertions” refer to different approaches in handling them, particularly in test automation. Here are the key differences between them:

Hard Assertions Soft Assertions
Failure Impact
If a hard assert fails, the test immediately stops, and the Playwright test case is marked as failed. Subsequent steps in the test script are not executed. If a soft assert fails, the test continues to execute, and all assertions are evaluated. Finally, a summary of assertion failures is provided.
Number of Assertions
Typically involves individual assert statements placed at different points in the test script. Multiple assertions can be grouped together to provide evaluation of several conditions within a single test.
Execution Flow
Execution stops at the first failed assertion and limits the information about multiple issues in a single run. The test script continues to execute even after encountering a failed assertion and provide a more comprehensive overview of all assertion failures.
Use Cases
Suitable for scenarios where subsequent steps are dependent on the success of previous steps, and further execution wouldn’t make sense if a critical condition fails. Useful when you want to collect information about multiple issues in a single test run without stopping the entire test case on the first failure.
Reporting may be less detailed as the test stops at the first failure and provides information only about the initial failure. Offers a more comprehensive report with details about all assertion failures got during the test run.

When it comes to choosing between hard and soft assertions, using hard assertions allows teams to detect a critical deviation that requires immediate attention. They are also suitable when precise pinpointing of failures is crucial for the debugging process. On the contrary, you can opt for soft assertions if there is a need to identify all issues within a test run and collect wider information about the state of the app.

The power of expectations in Playwright

In the context of Playwright, the power of expectations refers to the use of assertions to validate expected outcomes during automated testing. Here’s an overview of how expectations are asserted in Playwright:

  • Element Existence and Visibility. You can use expectations to verify the existence and visibility of UI elements on the page.
await expect(page.locator('button#submitBtn')).toBeVisible();
  • Text Content Verification. You can express expectations about the text content of elements on the page.
await expect(page.locator('h1#pageTitle')).toHaveText('Welcome to Playwright');
  • Attribute Values. You can assert the values of attributes associated with elements.
await expect(page.locator('div#product').getAttribute('data-price')).toBe('29.99');
  • Navigation Expectations. You can validate expectations related to page navigation.
await page.goto('');
await expect(page.url()).toBe('');
  • Network Requests and Responses. You can express expectations about network requests and responses.
const [request] = await Promise.all([
  • Asynchronous Operations. You can use expectations to handle asynchronous operations and make sure that elements or conditions appear within a specified time frame.
await expect(page.locator('div#loadingSpinner')).toBeVisible({ timeout: 5000 });
  • State Assertions. You can assert the state of UI elements – whether a checkbox is checked or a button is disabled.
await expect(page.locator('input#agreeCheckbox')).toBeChecked();

By leveraging these expectation features in Playwright, testers can verify their assumptions about the application’s behavior. This not only improves the reliability of automated tests but also contributes to a more robust testing process and assures that the app meets expected criteria and behaves as intended.

How to handle assertions in Playwright

In Playwright, assertions are utilized to validate expected outcomes during test automation. Playwright provides a robust set of features that help testing and development teams handle assertions, including built-in matchers, custom matchers, negative matchers, asynchronous assertion handling, expect retrying, and detailed reporting. Let’s delve into each of these aspects:

Built-in Matchers. Playwright offers several built-in matchers that simplify the process of expressing and verifying expected condition in your test scripts. They are the following:

  • toBeVisible: Asserts strict equality.
await expect(page.locator('button')).toBeVisible();
  • toContainText: Asserts that an element contains specific text.
await expect(page.locator('div#message')).toContainText('Hello, Playwright!');
  • toHaveAttribute: Asserts the presence and value of an attribute.
await expect(page.locator('input#username')).toHaveAttribute('placeholder', 'Enter your username');

Custom Matchers. You can create custom matchers tailored to your application’s specific needs. These allow for more expressive and domain-specific assertions.

    toBeValidUsername(element) {
        const isValid = /* custom validation logic */ ;
        return isValid ?
                pass: true,
                message: () => 'Expected username to be valid.'
            } :
                pass: false,
                message: () => 'Expected username to be valid, but it was not.'
// Usage
await expect(page.locator('input#username')).toBeValidUsername();

Negative Matchers. Negative assertions help validate that certain conditions are not met. Use the .not modifier before the matcher.

await expect(page.locator('button')).not.toBeDisabled();

Handling Async Assertions. Playwright handles asynchronous assertions seamlessly. You can use await when necessary, and Playwright will wait for the assertion to complete before moving on to the next step.

await expect(page.locator('div#status')).toHaveText('Ready');

Expect Retrying. When handling flaky tests or situations where elements may take time to appear, you can use the expect.retry feature.

await expect.retry(()=> page.locator('div#dynamicElement')).toBeVisible();

Reporting. With Playwright, you can get detailed reporting of assertions. When a test fails, Playwright outputs information about the failure, streamlining the debugging process.

await expect(page.locator('input#password')).toHaveAttribute('type', 'password');

How do teams benefit from assertions in Playwright?

  • Let’s delve into the notable advantages that assertions bring into the testing process and discover what benefits teams reap from:
  • Teams make sure that web pages and elements behave as expected.
  • Teams provide quick issue identification and debugging and validate specific conditions during execution.
  • Teams continuously monitor app behavior and quickly detect issues.
  • Teams speed up issue resolution by pinpointing the root cause of test failures.
  • Teams validate various aspects of the app that lead to comprehensive test coverage.
  • Teams adapt automated tests to changes with ease and make modifications in test scripts.

Best Practices for Crafting Robust Assertions in Playwright

  • Well-written assertions help teams carry out effective and maintainable testing. Here are best practices that emphasize both clarity and reusability, ensuring your assertion scripts stand the test of time.
  • Create concise statements. Try to use descriptive method names and eliminate unnecessary details. This helps you make sure that your assertion statements are easily readable.
  • Use Descriptive Messages. Focus on providing clear and informative failure messages so that the developer or tester can understand the cause of the failure without delving into the code.
  • Parameterize Assertions. You can reuse the same assertion logic with different input values to increase flexibility and improve the versatility of your testing suite.
  • Leverage Libraries. You can utilize assertion libraries provided by testing frameworks to speed up and improve the process.
  • Make reviews. You should regularly review and refactor your assertions to make sure that assertions are aligned with changes and reflect the evolving requirements.

Also, you might be interested in the following thoughts:

Bottom Line: Want to Master Assertions in Playwright?

Only by leveraging assertions in Playwright can you truly carry out effective Playwright testing, enable continuous monitoring, and achieve comprehensive test coverage. Drop us a line if you are ready to dive in and witness the transformation of your testing process with assertions in Playwright.

Playwright extent report 📊
Simultaneously output manual and automated tests with the single test management tool
Follow us