Test Assertions

Verify page elements and content for automated testing

Test assertion tools require the testing capability. Start the server with --caps=testing to enable these tools.

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:

npx @playwright/mcp-server --caps=testing

You can combine it with other capabilities:

npx @playwright/mcp-server --caps=vision,pdf,testing

Element Visibility Assertions

browser_verify_element_visible

Verify that an element is visible on the page.

role · 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.

accessibleName · string · required

ACCESSIBLE_NAME of the element. Can be found in the snapshot like this: - role "{ACCESSIBLE_NAME}"

Read-only: No

// Example: Verify submit button is visible
{
  "tool": "browser_verify_element_visible",
  "arguments": {
    "role": "button",
    "accessibleName": "Submit"
  }
}

Use browser_snapshot first to identify the correct role and accessible name of elements.

browser_verify_text_visible

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

text · string · required

TEXT to verify. Can be found in the snapshot like this: - role "Accessible Name": {TEXT} or like this: - text: {TEXT}

Read-only: No

// Example: Verify success message
{
  "tool": "browser_verify_text_visible",
  "arguments": {
    "text": "Form submitted successfully"
  }
}

browser_verify_text_visible searches for the text anywhere on the page. Use browser_verify_element_visible for more precise assertions.

List Verification

browser_verify_list_visible

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

element · string · required

Human-readable list description

ref · string · required

Exact target element reference that points to the list

items · array · required

Items to verify in the list. Each item should be a string.

Read-only: No

// 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.

type · string · required

Type of the element. Examples: textbox, checkbox, radio, select

element · string · required

Human-readable element description

ref · string · required

Exact target element reference that points to the element

value · string · required

Value to verify. For checkbox, use “true” or “false”.

Read-only: No

// Example: Verify input field value
{
  "tool": "browser_verify_value",
  "arguments": {
    "type": "textbox",
    "element": "Email input",
    "ref": "ref_150",
    "value": "[e-mail]"
  }
}

// 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.

element · string

Human-readable element description used to obtain permission to interact with the element

ref · string · required

Exact target element reference from the page snapshot

Read-only: Yes

// Example: Generate locator for submit button
{
  "tool": "browser_generate_locator",
  "arguments": {
    "element": "Submit button",
    "ref": "ref_123"
  }
}

Response example:

page.getByRole('button', { name: 'Submit' })

Use generated locators in your Playwright test scripts for consistent element selection.

Testing Workflows

Form Validation Testing

Verify form behavior and validation:

// 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": "[e-mail]" } }
{ "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": "[e-mail]" } }

// 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:

// 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:

// 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

Use Snapshots for Element Discovery

Always use browser_snapshot before assertions to identify the correct roles, accessible names, and refs for elements.

Prefer Semantic Assertions

Use browser_verify_element_visible instead of browser_verify_text_visible when possible for more robust tests.

Wait for Dynamic Content

Use browser_wait_for before assertions if content loads dynamically:

{ "tool": "browser_wait_for", "arguments": { "text": "Loading complete" } }
{ "tool": "browser_verify_element_visible", "arguments": { "role": "button", "accessibleName": "Submit" } }

Handle Assertion Failures

Assertion tools will fail if the expected state doesn’t match. Use this for test validation and error reporting.

Generate Locators for Test Code

Use browser_generate_locator to get Playwright locators that you can use in your test scripts for consistency.

Assertion vs. Wait

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.

// 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

// 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

// 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

Page Snapshot

Capture page structure to identify elements for assertions

Wait For

Wait for conditions before asserting

Core Automation

Interact with pages before verifying results