How to Use Playwright Expect Assertions

Artem Bondar
Struggling with Playwright assertions? You're not alone. Let's dive into this crucial part of test automation and make it crystal clear.

When you're new to Playwright, you quickly figure out the basics of assertions.

But here's the kicker: Playwright has two types of assertions - Locator Assertions and Generic Assertions. Both start with expect() method, but they're different beasts entirely.

Types of Playwright Assertions

    1. Generic Assertions
    2. Locator Assertions

Let's break it down:

Generic Assertions: The Quick and Dirty

  • Execute immediately
  • Give you instant results
  • Don't know squat about your app
  • Take two arguments and run with them
  • Do exactly what you tell them, no questions asked

Locator Assertions: The Smart Cookie

  • Only work with web element locators
  • Perform checks against that locator
  • Retry if things don't work out at first
  • Have a 5-second timeout limit (but you can change that)

The Assertion Selection: Which is which?

How do you know which assertion to use? It's all in the syntax.

Generic assertions:
  • Don't use 'await'
  • Argument must be a value

Locator assertions:
  • Must use 'await'
  • Provide a locator as the argument
Pro tip: Hover over the assertion method in VS Code. It'll tell you what you're dealing with.
Locator Assertion VS Code pop up

Best Practices: Don't Shoot Yourself in the Foot

  • Locator assertions are your go-to. Use them for anything web-related.
  • Save generic assertions for simple data comparisons.
Why? Locator assertions have a built-in wait mechanism. They make your tests more stable and less flaky.
Comparison at a Glance:
Generic Assertions
Locator Assertions
Immediate execution
Retry mechanism
Any data type
Web elements only
No built-in wait
5-second default timeout

Common Pitfalls: Don't Fall Into These Traps

Let's say you want to check the text in an input field. You might be tempted to do this:
But here's a slicker, more reliable way:

Here's the crucial difference:

With Generic Assertion, the inputValue() method waits until any value is available in the input field (up to the test timout which is 30 seconds by default), grabs that value, assigns it to a constant, and Playwright immediately checks if it's "Expected Text" or not.

With Locator Assertion, Playwright waits up to 5 seconds for the "Expected Text" to appear in the input field. If there's any other value currently, it keeps checking until the expected value shows up or the timeout is reached.

See how that could make your tests more reliable.
Let's look at a few more examples, checking the number of items in a list:

The old way:
The Playwright way:
Or checking for an empty input:
Instead of:
Do this:

Timing is Everything: Configuring Timeouts

You've got two ways to set timeouts for locator assertions:
1. Globally in playwright.config.ts:
2. For individual assertions:
Remember, these timeouts aren't hard waits. They're more like "up to" times. If the element shows up sooner, you're golden.

Troubleshooting: When Things Go Sideways

If you're not seeing the assertion methods you expect:
  • For locator assertions, make sure you've got 'await' and you're using a locator.
  • For generic assertions, skip the 'await' and use a plain value.

Pro tip
: When using generic assertions, know the difference between toBe() and toEqual(), check the article in our blog. They're not always interchangeable.

Wrap Up

Playwright assertions are powerful tools when used right. Prioritize locator assertions for web elements, keep your tests clean and readable, and don't be afraid to dig into the docs for more advanced uses.

You can find the full list of Generic and Locator assertions in the Playwright documentation with a detailed description of each method and usage example. Always skim through this list to find the most suitable assertion method for your validation.

Now go forth and assert with confidence. Your tests will thank you.

Want to take your Playwright skills to the next level? Check out the SDET with Playwright course. It's got everything you need to become a Playwright pro, including a deep dive into assertions and much more.