> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/microsoft/playwright-mcp/llms.txt
> Use this file to discover all available pages before exploring further.

# Test Assertions

> Verify page elements and content for automated testing

<Warning>
  Test assertion tools require the `testing` capability. Start the server with `--caps=testing` to enable these tools.
</Warning>

Test assertion tools allow you to verify that page elements and content match expected states. These tools are essential for automated testing and validation workflows.

## Enabling Testing Capability

To use test assertion tools, start the MCP server with the testing capability:

```bash theme={null}
npx @playwright/mcp-server --caps=testing
```

You can combine it with other capabilities:

```bash theme={null}
npx @playwright/mcp-server --caps=vision,pdf,testing
```

## Element Visibility Assertions

### browser\_verify\_element\_visible

Verify that an element is visible on the page.

<ParamField path="role" type="string" required>
  ROLE of the element. Can be found in the snapshot like this: `- {ROLE} "Accessible Name":`

  Common roles: `button`, `link`, `textbox`, `heading`, `img`, `list`, etc.
</ParamField>

<ParamField path="accessibleName" type="string" required>
  ACCESSIBLE\_NAME of the element. Can be found in the snapshot like this: `- role "{ACCESSIBLE_NAME}"`
</ParamField>

**Read-only**: No

```javascript theme={null}
// Example: Verify submit button is visible
{
  "tool": "browser_verify_element_visible",
  "arguments": {
    "role": "button",
    "accessibleName": "Submit"
  }
}
```

<Tip>
  Use `browser_snapshot` first to identify the correct role and accessible name of elements.
</Tip>

### browser\_verify\_text\_visible

Verify that specific text is visible on the page. Prefer `browser_verify_element_visible` when possible.

<ParamField path="text" type="string" required>
  TEXT to verify. Can be found in the snapshot like this: `- role "Accessible Name": {TEXT}` or like this: `- text: {TEXT}`
</ParamField>

**Read-only**: No

```javascript theme={null}
// Example: Verify success message
{
  "tool": "browser_verify_text_visible",
  "arguments": {
    "text": "Form submitted successfully"
  }
}
```

<Note>
  `browser_verify_text_visible` searches for the text anywhere on the page. Use `browser_verify_element_visible` for more precise assertions.
</Note>

## List Verification

### browser\_verify\_list\_visible

Verify that a list with specific items is visible on the page.

<ParamField path="element" type="string" required>
  Human-readable list description
</ParamField>

<ParamField path="ref" type="string" required>
  Exact target element reference that points to the list
</ParamField>

<ParamField path="items" type="array" required>
  Items to verify in the list. Each item should be a string.
</ParamField>

**Read-only**: No

```javascript theme={null}
// Example: Verify navigation menu items
{
  "tool": "browser_verify_list_visible",
  "arguments": {
    "element": "Main navigation menu",
    "ref": "ref_200",
    "items": ["Home", "About", "Products", "Contact"]
  }
}
```

## Value Verification

### browser\_verify\_value

Verify the value of a form element.

<ParamField path="type" type="string" required>
  Type of the element. Examples: `textbox`, `checkbox`, `radio`, `select`
</ParamField>

<ParamField path="element" type="string" required>
  Human-readable element description
</ParamField>

<ParamField path="ref" type="string" required>
  Exact target element reference that points to the element
</ParamField>

<ParamField path="value" type="string" required>
  Value to verify. For checkbox, use "true" or "false".
</ParamField>

**Read-only**: No

```javascript theme={null}
// Example: Verify input field value
{
  "tool": "browser_verify_value",
  "arguments": {
    "type": "textbox",
    "element": "Email input",
    "ref": "ref_150",
    "value": "user@example.com"
  }
}
```

```javascript theme={null}
// Example: Verify checkbox is checked
{
  "tool": "browser_verify_value",
  "arguments": {
    "type": "checkbox",
    "element": "Terms and conditions checkbox",
    "ref": "ref_151",
    "value": "true"
  }
}
```

## Locator Generation

### browser\_generate\_locator

Generate a Playwright locator for an element to use in tests.

<ParamField path="element" type="string">
  Human-readable element description used to obtain permission to interact with the element
</ParamField>

<ParamField path="ref" type="string" required>
  Exact target element reference from the page snapshot
</ParamField>

**Read-only**: Yes

```javascript theme={null}
// Example: Generate locator for submit button
{
  "tool": "browser_generate_locator",
  "arguments": {
    "element": "Submit button",
    "ref": "ref_123"
  }
}
```

**Response example:**

```javascript theme={null}
page.getByRole('button', { name: 'Submit' })
```

<Tip>
  Use generated locators in your Playwright test scripts for consistent element selection.
</Tip>

## Testing Workflows

### Form Validation Testing

Verify form behavior and validation:

```javascript theme={null}
// 1. Navigate to form
{ "tool": "browser_navigate", "arguments": { "url": "https://example.com/signup" } }

// 2. Fill in form
{ "tool": "browser_type", "arguments": { "element": "Email", "ref": "ref_100", "text": "test@example.com" } }
{ "tool": "browser_type", "arguments": { "element": "Password", "ref": "ref_101", "text": "SecurePass123" } }

// 3. Verify form values
{ "tool": "browser_verify_value", "arguments": { "type": "textbox", "element": "Email", "ref": "ref_100", "value": "test@example.com" } }

// 4. Submit form
{ "tool": "browser_click", "arguments": { "element": "Submit", "ref": "ref_102" } }

// 5. Verify success message
{ "tool": "browser_verify_text_visible", "arguments": { "text": "Account created successfully" } }
```

### UI Component Testing

Verify UI components display correctly:

```javascript theme={null}
// 1. Navigate to page
{ "tool": "browser_navigate", "arguments": { "url": "https://example.com/dashboard" } }

// 2. Verify header elements
{ "tool": "browser_verify_element_visible", "arguments": { "role": "heading", "accessibleName": "Dashboard" } }
{ "tool": "browser_verify_element_visible", "arguments": { "role": "button", "accessibleName": "Logout" } }

// 3. Verify navigation menu
{ "tool": "browser_verify_list_visible", "arguments": {
  "element": "Navigation menu",
  "ref": "ref_200",
  "items": ["Home", "Profile", "Settings"]
}}
```

### E2E Testing Workflow

Complete end-to-end testing scenario:

```javascript theme={null}
// 1. Login
{ "tool": "browser_navigate", "arguments": { "url": "https://example.com/login" } }
{ "tool": "browser_type", "arguments": { "element": "Username", "ref": "ref_10", "text": "testuser" } }
{ "tool": "browser_type", "arguments": { "element": "Password", "ref": "ref_11", "text": "password123", "submit": true } }

// 2. Verify login successful
{ "tool": "browser_verify_element_visible", "arguments": { "role": "heading", "accessibleName": "Welcome, testuser" } }

// 3. Navigate to feature
{ "tool": "browser_click", "arguments": { "element": "Products", "ref": "ref_20" } }

// 4. Verify page loaded
{ "tool": "browser_verify_text_visible", "arguments": { "text": "Product List" } }

// 5. Interact with feature
{ "tool": "browser_click", "arguments": { "element": "Add to cart", "ref": "ref_30" } }

// 6. Verify action completed
{ "tool": "browser_verify_text_visible", "arguments": { "text": "Item added to cart" } }
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use Snapshots for Element Discovery">
    Always use `browser_snapshot` before assertions to identify the correct roles, accessible names, and refs for elements.
  </Accordion>

  <Accordion title="Prefer Semantic Assertions">
    Use `browser_verify_element_visible` instead of `browser_verify_text_visible` when possible for more robust tests.
  </Accordion>

  <Accordion title="Wait for Dynamic Content">
    Use `browser_wait_for` before assertions if content loads dynamically:

    ```javascript theme={null}
    { "tool": "browser_wait_for", "arguments": { "text": "Loading complete" } }
    { "tool": "browser_verify_element_visible", "arguments": { "role": "button", "accessibleName": "Submit" } }
    ```
  </Accordion>

  <Accordion title="Handle Assertion Failures">
    Assertion tools will fail if the expected state doesn't match. Use this for test validation and error reporting.
  </Accordion>

  <Accordion title="Generate Locators for Test Code">
    Use `browser_generate_locator` to get Playwright locators that you can use in your test scripts for consistency.
  </Accordion>
</AccordionGroup>

## Assertion vs. Wait

<Note>
  Assertions (`browser_verify_*`) fail immediately if the condition isn't met. If you need to wait for an element to appear, use `browser_wait_for` first, then verify with assertions.
</Note>

```javascript theme={null}
// Good: Wait then verify
{ "tool": "browser_wait_for", "arguments": { "text": "Processing complete" } }
{ "tool": "browser_verify_text_visible", "arguments": { "text": "Processing complete" } }

// Bad: Verify immediately (may fail if content is loading)
{ "tool": "browser_verify_text_visible", "arguments": { "text": "Processing complete" } }
```

## Common Testing Patterns

### Verify Form Submission Flow

```javascript theme={null}
// Fill and verify each field
{ "tool": "browser_type", "arguments": { "element": "Name", "ref": "ref_1", "text": "John Doe" } }
{ "tool": "browser_verify_value", "arguments": { "type": "textbox", "element": "Name", "ref": "ref_1", "value": "John Doe" } }

// Check terms checkbox
{ "tool": "browser_click", "arguments": { "element": "Terms", "ref": "ref_2" } }
{ "tool": "browser_verify_value", "arguments": { "type": "checkbox", "element": "Terms", "ref": "ref_2", "value": "true" } }

// Submit and verify
{ "tool": "browser_click", "arguments": { "element": "Submit", "ref": "ref_3" } }
{ "tool": "browser_wait_for", "arguments": { "text": "Success" } }
{ "tool": "browser_verify_text_visible", "arguments": { "text": "Form submitted successfully" } }
```

### Verify Navigation Flow

```javascript theme={null}
// Verify current page
{ "tool": "browser_verify_element_visible", "arguments": { "role": "heading", "accessibleName": "Home Page" } }

// Navigate to next page
{ "tool": "browser_click", "arguments": { "element": "Next", "ref": "ref_50" } }

// Verify new page loaded
{ "tool": "browser_verify_element_visible", "arguments": { "role": "heading", "accessibleName": "Step 2" } }
```

## Related Tools

<CardGroup cols={2}>
  <Card title="Page Snapshot" icon="camera" href="/tools/core-automation#browser_snapshot">
    Capture page structure to identify elements for assertions
  </Card>

  <Card title="Wait For" icon="clock" href="/tools/core-automation#browser_wait_for">
    Wait for conditions before asserting
  </Card>

  <Card title="Core Automation" icon="browser" href="/tools/core-automation">
    Interact with pages before verifying results
  </Card>
</CardGroup>