YouTip

This chapter provides a comprehensive introduction to the Playwright assertion system, including the usage of auto-retrying assertions, general assertions, and soft assertions.\\n\\n* * *\\n\\n## What is an Assertion\\n\\nAssertions are used to verify whether the expected result of a test matches the actual result.\\n\\nPlaywright provides two sets of assertions: general assertions (from Jest) and auto-retrying assertions (unique to Playwright).\\n\\n* * *\\n\\n## Auto-retrying Assertions vs General Assertions\\n\\n### Auto-retrying Assertions (Async Matchers)\\n\\nPlaywright's web-specific assertions automatically retry until the condition is met or a timeout occurs, and must be used with `await`.\\n\\n## Example\\n\\n// Auto-retrying assertion —— waits for the condition to be met\\n\\n await expect(page.getByText('TUTORIAL')).toBeVisible();\\n\\n### General Assertions\\n\\nUsed for non-web-specific value comparisons, they do not retry automatically.\\n\\n## Example\\n\\n// General assertion —— executes immediately, no waiting\\n\\n expect(1+1).toBe(2);\\n\\n expect('hello').toContain('ell');\\n\\n expect(true).toBeTruthy();\\n\\n| Type | Auto-retry | Requires await | Use Case |\\n| --- | --- | --- | --- |\\n| Auto-retrying assertion | Yes | Must use `await` | Web-specific content like page elements, URLs, titles, etc. |\\n| General assertion | No | Not required | JavaScript values like ordinary variables, arrays, objects, etc. |\\n\\n* * *\\n\\n## Page-level Assertions\\n\\n## Example\\n\\n// Page title assertion\\n\\n await expect(page).toHaveTitle('TUTORIAL - ');\\n\\n await expect(page).toHaveTitle(/TUTORIAL/);\\n\\n// Page URL assertion\\n\\n await expect(page).toHaveURL('');\\n\\n await expect(page).toHaveURL(//);\\n\\n* * *\\n\\n## Visibility Assertions\\n\\n## Example\\n\\nconst btn = page.getByRole('button',{ name:'submit'});\\n\\n// Element is visible\\n\\n await expect(btn).toBeVisible();\\n\\n// Element is hidden\\n\\n await expect(btn).toBeHidden();\\n\\n// Element exists in the DOM (but not necessarily visible)\\n\\n await expect(btn).toBeAttached();\\n\\n// Element is visible within the viewport\\n\\n await expect(btn).toBeInViewport();\\n\\n* * *\\n\\n## Text and Value Assertions\\n\\n## Example\\n\\nconst heading = page.getByRole('heading',{ name:'TUTORIAL'});\\n\\n// Exact match of element's text content\\n\\n await expect(heading).toHaveText('');\\n\\n// Element's text content contains substring\\n\\n await expect(heading).toContainText('technology');\\n\\n// Current value of input\\n\\n await expect(page.getByLabel('Username')).toHaveValue('tutorial_user');\\n\\n// Element content is empty\\n\\n await expect(page.getByTestId('error-msg')).toBeEmpty();\\n\\n* * *\\n\\n## State Assertions\\n\\n## Example\\n\\nconst checkbox = page.getByLabel('Agree to Terms');\\n\\nconst input = page.getByLabel('Email');\\n\\n// Element is enabled\\n\\n await expect(input).toBeEnabled();\\n\\n// Element is disabled\\n\\n await expect(input).toBeDisabled();\\n\\n// Element is editable\\n\\n await expect(input).toBeEditable();\\n\\n// Checkbox is checked\\n\\n await expect(checkbox).toBeChecked();\\n\\n// Element is focused\\n\\n await expect(input).toBeFocused();\\n\\n* * *\\n\\n## Attribute Assertions\\n\\n## Example\\n\\nconst element = page.locator('.tutorial-logo');\\n\\n// DOM attribute assertion\\n\\n await expect(element).toHaveAttribute('src','/static/images/logo.png');\\n\\n// Only check if attribute exists\\n\\n await expect(element).toHaveAttribute('alt');\\n\\n// CSS class name assertion\\n\\n await expect(element).toHaveClass('logo-primary');\\n\\n// CSS property value assertion\\n\\n await expect(element).toHaveCSS('display','block');\\n\\n// Element ID assertion\\n\\n await expect(element).toHaveId('main-logo');\\n\\n// Accessible name\\n\\n await expect(page.getByRole('button')).toHaveAccessibleName('submit');\\n\\n* * *\\n\\n## Count Assertions\\n\\n## Example\\n\\n// Match element count\\n\\nconst items = page.getByRole('listitem');\\n\\n await expect(items).toHaveCount(5);\\n\\n// Used with filter\\n\\nconst activeItems = page.getByRole('listitem').filter({ hasText:'Activated'});\\n\\n await expect(activeItems).toHaveCount(3);\\n\\n* * *\\n\\n## General Assertions Quick Reference\\n\\n| Method | Description | Example |\\n| --- | --- | --- |\\n| `toBe(value)` | Strict equality (===) | `expect(x).toBe(42)` |\\n| `toEqual(value)` | Deep equality | `expect(obj).toEqual({ a: 1 })` |\\n| `toContain(item)` | Array/string contains | `expect(arr).toContain('a')` |\\n| `toBeTruthy()` | Value is truthy | `expect(x).toBeTruthy()` |\\n| `toBeFalsy()` | Value is falsy | `expect(x).toBeFalsy()` |\\n| `toBeNull()` | Value is null | `expect(x).toBeNull()` |\\n| `toBeGreaterThan(n)` | Greater than n | `expect(x).toBeGreaterThan(10)` |\\n| `toBeLessThan(n)` | Less than n | `expect(x).toBeLessThan(100)` |\\n| `toHaveLength(n)` | Array length | `expect(arr).toHaveLength(3)` |\\n\\n* * *\\n\\n## expect.soft() Soft Assertions\\n\\nA normal assertion immediately terminates the test upon failure.\\n\\nA soft assertion does not terminate upon failure; it continues to execute subsequent code and reports all failures together at the end of the test.\\n\\n## Example\\n\\ntest('Multiple Form Validation Checks', async ({ page })=>{\\n\\n await page.goto('https://example.com/form');\\n\\n// Soft assertion —— failure does not stop the test\\n\\n await expect.soft(page.getByLabel('Username')).toBeVisible();\\n\\n await expect.soft(page.getByLabel('Password')).toBeVisible();\\n\\n await expect.soft(page.getByLabel('Email')).toBeVisible();\\n\\n await expect.soft(page.getByRole('button',{ name:'Register'})).toBeEnabled();\\n\\n// If any of the above assertions fail, it will continue checking and report all failures together at the end\\n\\n});\\n\\n> Using `expect.soft()` when testing form pages allows you to discover all missing fields at once, rather than having to fix them one by one before seeing the next issue. This significantly improves debugging efficiency.\\n\\n* * *\\n\\n## Assertion Timeout\\n\\nAuto-retrying assertions have a default timeout of 5 seconds, which can be customized in the configuration file or for a single assertion:\\n\\n## Example\\n\\n// Set timeout for a single assertion (milliseconds)\\n\\n await expect(page.getByText('Loading...')).toBeHidden({ timeout:10000});\\n\\n// Set globally in the configuration file\\n\\n// playwright.config.ts:\\n\\n// export default defineConfig({\\n\\n// expect: { timeout: 10000 },\\n\\n// });