Skip to main content
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": "[email protected]"
  }
}

// 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": "[email protected]" } }
{ "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": "[email protected]" } }

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

Always use browser_snapshot before assertions to identify the correct roles, accessible names, and refs for elements.
Use browser_verify_element_visible instead of browser_verify_text_visible when possible for more robust tests.
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" } }
Assertion tools will fail if the expected state doesn’t match. Use this for test validation and error reporting.
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" } }

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