Skip to main content

class: LocatorAssertions

Added in: v1.17

The LocatorAssertions class provides assertion methods that can be used to make assertions about the Locator state in the tests.

import { test, expect } from '@copilotbrowser/copilotbrowser/test';

test('status becomes submitted', async ({ page }) => {
  // ...
  await page.getByRole('button').click();
  await expect(page.locator('.status')).toHaveText('Submitted');
});
// ...
import static com.microsoft.copilotbrowser.assertions.copilotbrowserAssertions.assertThat;

public class TestLocator {
  // ...
  @Test
  void statusBecomesSubmitted() {
    // ...
    page.getByRole(AriaRole.BUTTON).click();
    assertThat(page.locator(".status")).hasText("Submitted");
  }
}
from copilotbrowser.async_api import Page, expect

async def test_status_becomes_submitted(page: Page) -> None:
    # ..
    await page.get_by_role("button").click()
    await expect(page.locator(".status")).to_have_text("Submitted")
from copilotbrowser.sync_api import Page, expect

def test_status_becomes_submitted(page: Page) -> None:
    # ..
    page.get_by_role("button").click()
    expect(page.locator(".status")).to_have_text("Submitted")
using Microsoft.copilotbrowser;
using Microsoft.copilotbrowser.MSTest;

namespace copilotbrowserTests;

[TestClass]
public class ExampleTests : PageTest
{
    [TestMethod]
    public async Task StatusBecomesSubmitted()
    {
        // ...
        await Page.GetByRole(AriaRole.Button, new() { Name = "Sign In" }).ClickAsync();
        await Expect(Page.Locator(".status")).ToHaveTextAsync("Submitted");
    }
}

property: LocatorAssertions.not​

Added in: v1.20

Languages: Java, JavaScript, C# Returns: LocatorAssertions

Makes the assertion check for the opposite condition.

Usage

For example, this code tests that the Locator doesn't contain text "error":

await expect(locator).not.toContainText('error');
assertThat(locator).not().containsText("error");
await Expect(locator).Not.ToContainTextAsync("error");

async method: LocatorAssertions.NotToBeAttached​

Added in: v1.33

Languages: Python

The opposite of LocatorAssertions.toBeAttached().

option: LocatorAssertions.NotToBeAttached.attached​

Added in: v1.33

  • attached <boolean>

option: LocatorAssertions.NotToBeAttached.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.33

async method: LocatorAssertions.NotToBeChecked​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeChecked().

option: LocatorAssertions.NotToBeChecked.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToBeDisabled​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeDisabled().

option: LocatorAssertions.NotToBeDisabled.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToBeEditable​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeEditable().

option: LocatorAssertions.NotToBeEditable.editable​

Added in: v1.26

  • editable <boolean>

option: LocatorAssertions.NotToBeEditable.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToBeEmpty​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeEmpty().

option: LocatorAssertions.NotToBeEmpty.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToBeEnabled​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeEnabled().

option: LocatorAssertions.NotToBeEnabled.enabled​

Added in: v1.26

  • enabled <boolean>

option: LocatorAssertions.NotToBeEnabled.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToBeFocused​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeFocused().

option: LocatorAssertions.NotToBeFocused.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToBeHidden​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeHidden().

option: LocatorAssertions.NotToBeHidden.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToBeInViewport​

Added in: v1.31

Languages: Python

The opposite of LocatorAssertions.toBeInViewport().

option: LocatorAssertions.NotToBeInViewport.ratio​

Added in: v1.31

Languages: Python

  • ratio <float>

option: LocatorAssertions.NotToBeInViewport.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.31

Languages: Python

async method: LocatorAssertions.NotToBeVisible​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toBeVisible().

option: LocatorAssertions.NotToBeVisible.visible​

Added in: v1.26

  • visible <boolean>

option: LocatorAssertions.NotToBeVisible.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToContainClass​

Added in: v1.52

Languages: Python

The opposite of LocatorAssertions.toContainClass().

param: LocatorAssertions.NotToContainClass.expected​

Added in: v1.52

  • expected <string|Array<string>>

Expected class or RegExp or a list of those.

option: LocatorAssertions.NotToContainClass.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.52

async method: LocatorAssertions.NotToContainText​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toContainText().

param: LocatorAssertions.NotToContainText.expected​

Added in: v1.18

  • expected <string|RegExp|Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected substring or RegExp or a list of those.

option: LocatorAssertions.NotToContainText.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.23

option: LocatorAssertions.NotToContainText.useInnerText​

Added in: v1.18

  • useInnerText <boolean>

Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

option: LocatorAssertions.NotToContainText.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveAccessibleDescription​

Added in: v1.44

Languages: Python

The opposite of LocatorAssertions.toHaveAccessibleDescription().

param: LocatorAssertions.NotToHaveAccessibleDescription.name​

Added in: v1.44

  • description <string|RegExp>

Expected accessible description.

option: LocatorAssertions.NotToHaveAccessibleDescription.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.44

option: LocatorAssertions.NotToHaveAccessibleDescription.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.44

async method: LocatorAssertions.NotToHaveAccessibleErrorMessage​

Added in: v1.50

Languages: Python

The opposite of LocatorAssertions.toHaveAccessibleErrorMessage().

param: LocatorAssertions.NotToHaveAccessibleErrorMessage.errorMessage​

Added in: v1.50

  • errorMessage <string|RegExp>

Expected accessible error message.

option: LocatorAssertions.NotToHaveAccessibleErrorMessage.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.50

option: LocatorAssertions.NotToHaveAccessibleErrorMessage.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.50

async method: LocatorAssertions.NotToHaveAccessibleName​

Added in: v1.44

Languages: Python

The opposite of LocatorAssertions.toHaveAccessibleName().

param: LocatorAssertions.NotToHaveAccessibleName.name​

Added in: v1.44

  • name <string|RegExp>

Expected accessible name.

option: LocatorAssertions.NotToHaveAccessibleName.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.44

option: LocatorAssertions.NotToHaveAccessibleName.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.44

async method: LocatorAssertions.NotToHaveAttribute​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveAttribute().

param: LocatorAssertions.NotToHaveAttribute.name​

Added in: v1.18

  • name <string>

Attribute name.

param: LocatorAssertions.NotToHaveAttribute.value​

Added in: v1.18

  • value <string|RegExp>

Expected attribute value.

option: LocatorAssertions.NotToHaveAttribute.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.40

option: LocatorAssertions.NotToHaveAttribute.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveClass​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveClass().

param: LocatorAssertions.NotToHaveClass.expected​

Added in: v1.18

  • expected <string|RegExp|Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected class or RegExp or a list of those.

option: LocatorAssertions.NotToHaveClass.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveCount​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveCount().

param: LocatorAssertions.NotToHaveCount.count​

Added in: v1.18

  • count <int>

Expected count.

option: LocatorAssertions.NotToHaveCount.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveCSS​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveCSS().

param: LocatorAssertions.NotToHaveCSS.name​

Added in: v1.18

  • name <string>

CSS property name.

param: LocatorAssertions.NotToHaveCSS.value​

Added in: v1.18

  • value <string|RegExp>

CSS property value.

option: LocatorAssertions.NotToHaveCSS.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveId​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveId().

param: LocatorAssertions.NotToHaveId.id​

Added in: v1.18

  • id <string|RegExp>

Element id.

option: LocatorAssertions.NotToHaveId.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveJSProperty​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveJSProperty().

param: LocatorAssertions.NotToHaveJSProperty.name​

Added in: v1.18

  • name <string>

Property name.

param: LocatorAssertions.NotToHaveJSProperty.value​

Added in: v1.18

  • value <any>

Property value.

option: LocatorAssertions.NotToHaveJSProperty.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveRole​

Added in: v1.44

Languages: Python

The opposite of LocatorAssertions.toHaveRole().

param: LocatorAssertions.NotToHaveRole.role = %%-get-by-role-to-have-role-role-%%​

Added in: v1.44

option: LocatorAssertions.NotToHaveRole.timeout = %%-js-assertions-timeout-%%​

Added in: v1.44

option: LocatorAssertions.NotToHaveRole.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.44

async method: LocatorAssertions.NotToHaveText​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveText().

param: LocatorAssertions.NotToHaveText.expected​

Added in: v1.18

  • expected <string|RegExp|Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected string or RegExp or a list of those.

option: LocatorAssertions.NotToHaveText.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.23

option: LocatorAssertions.NotToHaveText.useInnerText​

Added in: v1.18

  • useInnerText <boolean>

Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

option: LocatorAssertions.NotToHaveText.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveValue​

Added in: v1.20

Languages: Python

The opposite of LocatorAssertions.toHaveValue().

param: LocatorAssertions.NotToHaveValue.value​

Added in: v1.18

  • value <string|RegExp>

Expected value.

option: LocatorAssertions.NotToHaveValue.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.NotToHaveValues​

Added in: v1.23

Languages: Python

The opposite of LocatorAssertions.toHaveValues().

param: LocatorAssertions.NotToHaveValues.values​

Added in: v1.23

  • values <Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected options currently selected.

option: LocatorAssertions.NotToHaveValues.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.23

async method: LocatorAssertions.NotToMatchAriaSnapshot​

Added in: v1.49

Languages: Python

The opposite of LocatorAssertions.toMatchAriaSnapshot().

param: LocatorAssertions.NotToMatchAriaSnapshot.expected​

Added in: v1.49

  • expected

option: LocatorAssertions.NotToMatchAriaSnapshot.timeout = %%-js-assertions-timeout-%%​

Added in: v1.49

option: LocatorAssertions.NotToMatchAriaSnapshot.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.49

async method: LocatorAssertions.toBeAttached​

Added in: v1.33

Languages: (all)

Ensures that Locator points to an element that is connected to a Document or a ShadowRoot.

Usage

await expect(page.getByText('Hidden text')).toBeAttached();
assertThat(page.getByText("Hidden text")).isAttached();
await expect(page.get_by_text("Hidden text")).to_be_attached()
expect(page.get_by_text("Hidden text")).to_be_attached()
await Expect(Page.GetByText("Hidden text")).ToBeAttachedAsync();

option: LocatorAssertions.toBeAttached.attached​

Added in: v1.33

  • attached <boolean>

option: LocatorAssertions.toBeAttached.timeout = %%-js-assertions-timeout-%%​

Added in: v1.33

option: LocatorAssertions.toBeAttached.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.33

async method: LocatorAssertions.toBeChecked​

Added in: v1.20

Languages: (all)

Ensures the Locator points to a checked input.

Usage

const locator = page.getByLabel('Subscribe to newsletter');
await expect(locator).toBeChecked();
assertThat(page.getByLabel("Subscribe to newsletter")).isChecked();
from copilotbrowser.async_api import expect

locator = page.get_by_label("Subscribe to newsletter")
await expect(locator).to_be_checked()
from copilotbrowser.sync_api import expect

locator = page.get_by_label("Subscribe to newsletter")
expect(locator).to_be_checked()
var locator = Page.GetByLabel("Subscribe to newsletter");
await Expect(locator).ToBeCheckedAsync();

option: LocatorAssertions.toBeChecked.checked​

Added in: v1.18

  • checked <boolean>

Provides state to assert for. Asserts for input to be checked by default. This option can't be used when LocatorAssertions.toBeChecked.indeterminate is set to true.

option: LocatorAssertions.toBeChecked.indeterminate​

Added in: v1.50

  • indeterminate <boolean>

Asserts that the element is in the indeterminate (mixed) state. Only supported for checkboxes and radio buttons. This option can't be true when LocatorAssertions.toBeChecked.checked is provided.

option: LocatorAssertions.toBeChecked.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeChecked.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toBeDisabled​

Added in: v1.20

Languages: (all)

Ensures the Locator points to a disabled element. Element is disabled if it has "disabled" attribute or is disabled via 'aria-disabled'. Note that only native control elements such as HTML button, input, select, textarea, option, optgroup can be disabled by setting "disabled" attribute. "disabled" attribute on other elements is ignored by the browser.

Usage

const locator = page.locator('button.submit');
await expect(locator).toBeDisabled();
assertThat(page.locator("button.submit")).isDisabled();
from copilotbrowser.async_api import expect

locator = page.locator("button.submit")
await expect(locator).to_be_disabled()
from copilotbrowser.sync_api import expect

locator = page.locator("button.submit")
expect(locator).to_be_disabled()
var locator = Page.Locator("button.submit");
await Expect(locator).ToBeDisabledAsync();

option: LocatorAssertions.toBeDisabled.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeDisabled.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toBeEditable​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an editable element.

Usage

const locator = page.getByRole('textbox');
await expect(locator).toBeEditable();
assertThat(page.getByRole(AriaRole.TEXTBOX)).isEditable();
from copilotbrowser.async_api import expect

locator = page.get_by_role("textbox")
await expect(locator).to_be_editable()
from copilotbrowser.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_be_editable()
var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToBeEditableAsync();

option: LocatorAssertions.toBeEditable.editable​

Added in: v1.26

  • editable <boolean>

option: LocatorAssertions.toBeEditable.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeEditable.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toBeEmpty​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an empty editable element or to a DOM node that has no text.

Usage

const locator = page.locator('div.warning');
await expect(locator).toBeEmpty();
assertThat(page.locator("div.warning")).isEmpty();
from copilotbrowser.async_api import expect

locator = page.locator("div.warning")
await expect(locator).to_be_empty()
from copilotbrowser.sync_api import expect

locator = page.locator("div.warning")
expect(locator).to_be_empty()
var locator = Page.Locator("div.warning");
await Expect(locator).ToBeEmptyAsync();

option: LocatorAssertions.toBeEmpty.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeEmpty.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toBeEnabled​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an enabled element.

Usage

const locator = page.locator('button.submit');
await expect(locator).toBeEnabled();
assertThat(page.locator("button.submit")).isEnabled();
from copilotbrowser.async_api import expect

locator = page.locator("button.submit")
await expect(locator).to_be_enabled()
from copilotbrowser.sync_api import expect

locator = page.locator("button.submit")
expect(locator).to_be_enabled()
var locator = Page.Locator("button.submit");
await Expect(locator).ToBeEnabledAsync();

option: LocatorAssertions.toBeEnabled.enabled​

Added in: v1.26

  • enabled <boolean>

option: LocatorAssertions.toBeEnabled.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeEnabled.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toBeFocused​

Added in: v1.20

Languages: (all)

Ensures the Locator points to a focused DOM node.

Usage

const locator = page.getByRole('textbox');
await expect(locator).toBeFocused();
assertThat(page.getByRole(AriaRole.TEXTBOX)).isFocused();
from copilotbrowser.async_api import expect

locator = page.get_by_role("textbox")
await expect(locator).to_be_focused()
from copilotbrowser.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_be_focused()
var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToBeFocusedAsync();

option: LocatorAssertions.toBeFocused.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeFocused.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toBeHidden​

Added in: v1.20

Languages: (all)

Ensures that Locator either does not resolve to any DOM node, or resolves to a non-visible one.

Usage

const locator = page.locator('.my-element');
await expect(locator).toBeHidden();
assertThat(page.locator(".my-element")).isHidden();
from copilotbrowser.async_api import expect

locator = page.locator('.my-element')
await expect(locator).to_be_hidden()
from copilotbrowser.sync_api import expect

locator = page.locator('.my-element')
expect(locator).to_be_hidden()
var locator = Page.Locator(".my-element");
await Expect(locator).ToBeHiddenAsync();

option: LocatorAssertions.toBeHidden.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeHidden.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toBeInViewport​

Added in: v1.31

Languages: (all)

Ensures the Locator points to an element that intersects viewport, according to the intersection observer API.

Usage

const locator = page.getByRole('button');
// Make sure at least some part of element intersects viewport.
await expect(locator).toBeInViewport();
// Make sure element is fully outside of viewport.
await expect(locator).not.toBeInViewport();
// Make sure that at least half of the element intersects viewport.
await expect(locator).toBeInViewport({ ratio: 0.5 });
Locator locator = page.getByRole(AriaRole.BUTTON);
// Make sure at least some part of element intersects viewport.
assertThat(locator).isInViewport();
// Make sure element is fully outside of viewport.
assertThat(locator).not().isInViewport();
// Make sure that at least half of the element intersects viewport.
assertThat(locator).isInViewport(new LocatorAssertions.IsInViewportOptions().setRatio(0.5));
var locator = Page.GetByRole(AriaRole.Button);
// Make sure at least some part of element intersects viewport.
await Expect(locator).ToBeInViewportAsync();
// Make sure element is fully outside of viewport.
await Expect(locator).Not.ToBeInViewportAsync();
// Make sure that at least half of the element intersects viewport.
await Expect(locator).ToBeInViewportAsync(new() { Ratio = 0.5 });
from copilotbrowser.async_api import expect

locator = page.get_by_role("button")
# Make sure at least some part of element intersects viewport.
await expect(locator).to_be_in_viewport()
# Make sure element is fully outside of viewport.
await expect(locator).not_to_be_in_viewport()
# Make sure that at least half of the element intersects viewport.
await expect(locator).to_be_in_viewport(ratio=0.5)
from copilotbrowser.sync_api import expect

locator = page.get_by_role("button")
# Make sure at least some part of element intersects viewport.
expect(locator).to_be_in_viewport()
# Make sure element is fully outside of viewport.
expect(locator).not_to_be_in_viewport()
# Make sure that at least half of the element intersects viewport.
expect(locator).to_be_in_viewport(ratio=0.5)

option: LocatorAssertions.toBeInViewport.ratio​

Added in: v1.31

  • ratio <float>

The minimal ratio of the element to intersect viewport. If equals to 0, then element should intersect viewport at any positive ratio. Defaults to 0.

option: LocatorAssertions.toBeInViewport.timeout = %%-js-assertions-timeout-%%​

Added in: v1.31

option: LocatorAssertions.toBeInViewport.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.31

async method: LocatorAssertions.toBeVisible​

Added in: v1.20

Languages: (all)

Ensures that Locator points to an attached and visible DOM node.

To check that at least one element from the list is visible, use Locator.first().

Usage

// A specific element is visible.
await expect(page.getByText('Welcome')).toBeVisible();

// At least one item in the list is visible.
await expect(page.getByTestId('todo-item').first()).toBeVisible();

// At least one of the two elements is visible, possibly both.
await expect(
    page.getByRole('button', { name: 'Sign in' })
        .or(page.getByRole('button', { name: 'Sign up' }))
        .first()
).toBeVisible();
// A specific element is visible.
assertThat(page.getByText("Welcome")).isVisible();

// At least one item in the list is visible.
assertThat(page.getByTestId("todo-item").first()).isVisible();

// At least one of the two elements is visible, possibly both.
assertThat(
  page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign in"))
    .or(page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign up")))
    .first()
).isVisible();
# A specific element is visible.
await expect(page.get_by_text("Welcome")).to_be_visible()

# At least one item in the list is visible.
await expect(page.get_by_test_id("todo-item").first).to_be_visible()

# At least one of the two elements is visible, possibly both.
await expect(
    page.get_by_role("button", name="Sign in")
    .or_(page.get_by_role("button", name="Sign up"))
    .first
).to_be_visible()
# A specific element is visible.
expect(page.get_by_text("Welcome")).to_be_visible()

# At least one item in the list is visible.
expect(page.get_by_test_id("todo-item").first).to_be_visible()

# At least one of the two elements is visible, possibly both.
expect(
    page.get_by_role("button", name="Sign in")
    .or_(page.get_by_role("button", name="Sign up"))
    .first
).to_be_visible()
// A specific element is visible.
await Expect(Page.GetByText("Welcome")).ToBeVisibleAsync();

// At least one item in the list is visible.
await Expect(Page.GetByTestId("todo-item").First).ToBeVisibleAsync();

// At least one of the two elements is visible, possibly both.
await Expect(
  Page.GetByRole(AriaRole.Button, new() { Name = "Sign in" })
    .Or(Page.GetByRole(AriaRole.Button, new() { Name = "Sign up" }))
    .First
).ToBeVisibleAsync();

option: LocatorAssertions.toBeVisible.visible​

Added in: v1.26

  • visible <boolean>

option: LocatorAssertions.toBeVisible.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toBeVisible.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toContainClass​

Added in: v1.52

Languages: (all)

Ensures the Locator points to an element with given CSS classes. All classes from the asserted value, separated by spaces, must be present in the Element.classList in any order.

Usage

<div class='middle selected row' id='component'></div>
const locator = page.locator('#component');
await expect(locator).toContainClass('middle selected row');
await expect(locator).toContainClass('selected');
await expect(locator).toContainClass('row middle');
assertThat(page.locator("#component")).containsClass("middle selected row");
assertThat(page.locator("#component")).containsClass("selected");
assertThat(page.locator("#component")).containsClass("row middle");
from copilotbrowser.async_api import expect

locator = page.locator("#component")
await expect(locator).to_contain_class("middle selected row")
await expect(locator).to_contain_class("selected")
await expect(locator).to_contain_class("row middle")
from copilotbrowser.sync_api import expect

locator = page.locator("#component")
expect(locator).to_contain_class("middle selected row")
expect(locator).to_contain_class("selected")
expect(locator).to_contain_class("row middle")
var locator = Page.Locator("#component");
await Expect(locator).ToContainClassAsync("middle selected row");
await Expect(locator).ToContainClassAsync("selected");
await Expect(locator).ToContainClassAsync("row middle");

When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class lists. Each element's class attribute is matched against the corresponding class in the array:

<div class='list'>
  <div class='component inactive'></div>
  <div class='component active'></div>
  <div class='component inactive'></div>
</div>
const locator = page.locator('.list > .component');
await expect(locator).toContainClass(['inactive', 'active', 'inactive']);
assertThat(page.locator(".list > .component")).containsClass(new String[] {"inactive", "active", "inactive"});
from copilotbrowser.async_api import expect

locator = page.locator(".list > .component")
await expect(locator).to_contain_class(["inactive", "active", "inactive"])
from copilotbrowser.sync_api import expect

locator = page.locator(".list > .component")
await expect(locator).to_contain_class(["inactive", "active", "inactive"])
var locator = Page.Locator(".list > .component");
await Expect(locator).ToContainClassAsync(new string[]{"inactive", "active", "inactive"});

param: LocatorAssertions.toContainClass.expected​

Added in: v1.52

  • expected <string|Array<string>>

A string containing expected class names, separated by spaces, or a list of such strings to assert multiple elements.

option: LocatorAssertions.toContainClass.timeout = %%-js-assertions-timeout-%%​

Added in: v1.52

option: LocatorAssertions.toContainClass.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.52

async method: LocatorAssertions.toContainText​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an element that contains the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.

Details

When expected parameter is a string, copilotbrowser will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.

Usage

const locator = page.locator('.title');
await expect(locator).toContainText('substring');
await expect(locator).toContainText(/\d messages/);
assertThat(page.locator(".title")).containsText("substring");
import re
from copilotbrowser.async_api import expect

locator = page.locator('.title')
await expect(locator).to_contain_text("substring")
await expect(locator).to_contain_text(re.compile(r"\d messages"))
import re
from copilotbrowser.sync_api import expect

locator = page.locator('.title')
expect(locator).to_contain_text("substring")
expect(locator).to_contain_text(re.compile(r"\d messages"))
var locator = Page.Locator(".title");
await Expect(locator).ToContainTextAsync("substring");
await Expect(locator).ToContainTextAsync(new Regex("\\d messages"));

If you pass an array as an expected value, the expectations are:

  1. Locator resolves to a list of elements.
  2. Elements from a subset of this list contain text from the expected array, respectively.
  3. The matching subset of elements has the same order as the expected array.
  4. Each text value from the expected array is matched by some element from the list.

For example, consider the following list:

<ul>
  <li>Item Text 1</li>
  <li>Item Text 2</li>
  <li>Item Text 3</li>
</ul>

Let's see how we can use the assertion:

// ✓ Contains the right items in the right order
await expect(page.locator('ul > li')).toContainText(['Text 1', 'Text 3']);

// ✖ Wrong order
await expect(page.locator('ul > li')).toContainText(['Text 3', 'Text 2']);

// ✖ No item contains this text
await expect(page.locator('ul > li')).toContainText(['Some 33']);

// ✖ Locator points to the outer list element, not to the list items
await expect(page.locator('ul')).toContainText(['Text 3']);
// ✓ Contains the right items in the right order
assertThat(page.locator("ul > li")).containsText(new String[] {"Text 1", "Text 3"});

// ✖ Wrong order
assertThat(page.locator("ul > li")).containsText(new String[] {"Text 3", "Text 2"});

// ✖ No item contains this text
assertThat(page.locator("ul > li")).containsText(new String[] {"Some 33"});

// ✖ Locator points to the outer list element, not to the list items
assertThat(page.locator("ul")).containsText(new String[] {"Text 3"});
from copilotbrowser.async_api import expect

# ✓ Contains the right items in the right order
await expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3"])

# ✖ Wrong order
await expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])

# ✖ No item contains this text
await expect(page.locator("ul > li")).to_contain_text(["Some 33"])

# ✖ Locator points to the outer list element, not to the list items
await expect(page.locator("ul")).to_contain_text(["Text 3"])
from copilotbrowser.sync_api import expect

# ✓ Contains the right items in the right order
expect(page.locator("ul > li")).to_contain_text(["Text 1", "Text 3"])

# ✖ Wrong order
expect(page.locator("ul > li")).to_contain_text(["Text 3", "Text 2"])

# ✖ No item contains this text
expect(page.locator("ul > li")).to_contain_text(["Some 33"])

# ✖ Locator points to the outer list element, not to the list items
expect(page.locator("ul")).to_contain_text(["Text 3"])
// ✓ Contains the right items in the right order
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"Text 1", "Text 3"});

// ✖ Wrong order
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"Text 3", "Text 2"});

// ✖ No item contains this text
await Expect(Page.Locator("ul > li")).ToContainTextAsync(new string[] {"Some 33"});

// ✖ Locator points to the outer list element, not to the list items
await Expect(Page.Locator("ul")).ToContainTextAsync(new string[] {"Text 3"});

param: LocatorAssertions.toContainText.expected​

Added in: v1.18

Languages: JavaScript

  • expected <string|RegExp|Array<string|RegExp>>

Expected substring or RegExp or a list of those.

param: LocatorAssertions.toContainText.expected​

Added in: v1.18

Languages: Python

  • expected <string|RegExp|Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected substring or RegExp or a list of those.

param: LocatorAssertions.toContainText.expected​

Added in: v1.18

Languages: Java, C#

  • expected <string|RegExp|Array<string>|Array<RegExp>>

Expected substring or RegExp or a list of those.

option: LocatorAssertions.toContainText.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.23

option: LocatorAssertions.toContainText.useInnerText​

Added in: v1.18

  • useInnerText <boolean>

Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

option: LocatorAssertions.toContainText.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toContainText.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveAccessibleDescription​

Added in: v1.44

Languages: (all)

Ensures the Locator points to an element with a given accessible description.

Usage

const locator = page.getByTestId('save-button');
await expect(locator).toHaveAccessibleDescription('Save results to disk');
Locator locator = page.getByTestId("save-button");
assertThat(locator).hasAccessibleDescription("Save results to disk");
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_description("Save results to disk")
locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_description("Save results to disk")
var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveAccessibleDescriptionAsync("Save results to disk");

param: LocatorAssertions.toHaveAccessibleDescription.description​

Added in: v1.44

  • description <string|RegExp>

Expected accessible description.

option: LocatorAssertions.toHaveAccessibleDescription.timeout = %%-js-assertions-timeout-%%​

Added in: v1.44

option: LocatorAssertions.toHaveAccessibleDescription.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.44

option: LocatorAssertions.toHaveAccessibleDescription.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.44

async method: LocatorAssertions.toHaveAccessibleErrorMessage​

Added in: v1.50

Languages: (all)

Ensures the Locator points to an element with a given aria errormessage.

Usage

const locator = page.getByTestId('username-input');
await expect(locator).toHaveAccessibleErrorMessage('Username is required.');
Locator locator = page.getByTestId("username-input");
assertThat(locator).hasAccessibleErrorMessage("Username is required.");
locator = page.get_by_test_id("username-input")
await expect(locator).to_have_accessible_error_message("Username is required.")
locator = page.get_by_test_id("username-input")
expect(locator).to_have_accessible_error_message("Username is required.")
var locator = Page.GetByTestId("username-input");
await Expect(locator).ToHaveAccessibleErrorMessageAsync("Username is required.");

param: LocatorAssertions.toHaveAccessibleErrorMessage.errorMessage​

Added in: v1.50

  • errorMessage <string|RegExp>

Expected accessible error message.

option: LocatorAssertions.toHaveAccessibleErrorMessage.timeout = %%-js-assertions-timeout-%%​

Added in: v1.50

option: LocatorAssertions.toHaveAccessibleErrorMessage.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.50

option: LocatorAssertions.toHaveAccessibleErrorMessage.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.50

async method: LocatorAssertions.toHaveAccessibleName​

Added in: v1.44

Languages: (all)

Ensures the Locator points to an element with a given accessible name.

Usage

const locator = page.getByTestId('save-button');
await expect(locator).toHaveAccessibleName('Save to disk');
Locator locator = page.getByTestId("save-button");
assertThat(locator).hasAccessibleName("Save to disk");
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_accessible_name("Save to disk")
locator = page.get_by_test_id("save-button")
expect(locator).to_have_accessible_name("Save to disk")
var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveAccessibleNameAsync("Save to disk");

param: LocatorAssertions.toHaveAccessibleName.name​

Added in: v1.44

  • name <string|RegExp>

Expected accessible name.

option: LocatorAssertions.toHaveAccessibleName.timeout = %%-js-assertions-timeout-%%​

Added in: v1.44

option: LocatorAssertions.toHaveAccessibleName.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.44

option: LocatorAssertions.toHaveAccessibleName.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.44

async method: LocatorAssertions.toHaveAttribute​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an element with given attribute.

Usage

const locator = page.locator('input');
await expect(locator).toHaveAttribute('type', 'text');
assertThat(page.locator("input")).hasAttribute("type", "text");
from copilotbrowser.async_api import expect

locator = page.locator("input")
await expect(locator).to_have_attribute("type", "text")
from copilotbrowser.sync_api import expect

locator = page.locator("input")
expect(locator).to_have_attribute("type", "text")
var locator = Page.Locator("input");
await Expect(locator).ToHaveAttributeAsync("type", "text");

param: LocatorAssertions.toHaveAttribute.name​

Added in: v1.18

  • name <string>

Attribute name.

param: LocatorAssertions.toHaveAttribute.value​

Added in: v1.18

  • value <string|RegExp>

Expected attribute value.

option: LocatorAssertions.toHaveAttribute.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveAttribute.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveAttribute.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.40

async method: LocatorAssertions.toHaveAttribute#2​

Added in: v1.39

Languages: JavaScript

Ensures the Locator points to an element with given attribute. The method will assert attribute presence.

const locator = page.locator('input');
// Assert attribute existence.
await expect(locator).toHaveAttribute('disabled');
await expect(locator).not.toHaveAttribute('open');

param: LocatorAssertions.toHaveAttribute#2.name​

Added in: v1.39

  • name <string>

Attribute name.

option: LocatorAssertions.toHaveAttribute#2.timeout = %%-js-assertions-timeout-%%​

Added in: v1.39

async method: LocatorAssertions.toHaveClass​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an element with given CSS classes. When a string is provided, it must fully match the element's class attribute. To match individual classes use LocatorAssertions.toContainClass().

Usage

<div class='middle selected row' id='component'></div>
const locator = page.locator('#component');
await expect(locator).toHaveClass('middle selected row');
await expect(locator).toHaveClass(/(^|\s)selected(\s|$)/);
assertThat(page.locator("#component")).hasClass("middle selected row");
assertThat(page.locator("#component")).hasClass(Pattern.compile("(^|\\s)selected(\\s|$)"));
from copilotbrowser.async_api import expect

locator = page.locator("#component")
await expect(locator).to_have_class("middle selected row")
await expect(locator).to_have_class(re.compile(r"(^|\\s)selected(\\s|$)"))
from copilotbrowser.sync_api import expect

locator = page.locator("#component")
expect(locator).to_have_class("middle selected row")
expect(locator).to_have_class(re.compile(r"(^|\\s)selected(\\s|$)"))
var locator = Page.Locator("#component");
await Expect(locator).ToHaveClassAsync("middle selected row");
await Expect(locator).ToHaveClassAsync(new Regex("(^|\\s)selected(\\s|$)"));

When an array is passed, the method asserts that the list of elements located matches the corresponding list of expected class values. Each element's class attribute is matched against the corresponding string or regular expression in the array:

const locator = page.locator('.list > .component');
await expect(locator).toHaveClass(['component', 'component selected', 'component']);
assertThat(page.locator(".list > .component")).hasClass(new String[] {"component", "component selected", "component"});
from copilotbrowser.async_api import expect

locator = page.locator(".list > .component")
await expect(locator).to_have_class(["component", "component selected", "component"])
from copilotbrowser.sync_api import expect

locator = page.locator(".list > .component")
expect(locator).to_have_class(["component", "component selected", "component"])
var locator = Page.Locator(".list > .component");
await Expect(locator).ToHaveClassAsync(new string[]{"component", "component selected", "component"});

param: LocatorAssertions.toHaveClass.expected​

Added in: v1.18

Languages: JavaScript

  • expected <string|RegExp|Array<string|RegExp>>

Expected class or RegExp or a list of those.

param: LocatorAssertions.toHaveClass.expected​

Added in: v1.18

Languages: Python

  • expected <string|RegExp|Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected class or RegExp or a list of those.

param: LocatorAssertions.toHaveClass.expected​

Added in: v1.18

Languages: Java, C#

  • expected <string|RegExp|Array<string>|Array<RegExp>>

Expected class or RegExp or a list of those.

option: LocatorAssertions.toHaveClass.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveClass.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveCount​

Added in: v1.20

Languages: (all)

Ensures the Locator resolves to an exact number of DOM nodes.

Usage

const list = page.locator('list > .component');
await expect(list).toHaveCount(3);
assertThat(page.locator("list > .component")).hasCount(3);
from copilotbrowser.async_api import expect

locator = page.locator("list > .component")
await expect(locator).to_have_count(3)
from copilotbrowser.sync_api import expect

locator = page.locator("list > .component")
expect(locator).to_have_count(3)
var locator = Page.Locator("list > .component");
await Expect(locator).ToHaveCountAsync(3);

param: LocatorAssertions.toHaveCount.count​

Added in: v1.18

  • count <int>

Expected count.

option: LocatorAssertions.toHaveCount.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveCount.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveCSS#1​

Added in: v1.20

Languages: (all)

Ensures the Locator resolves to an element with the given computed CSS style.

Usage

const locator = page.getByRole('button');
await expect(locator).toHaveCSS('display', 'flex');
assertThat(page.getByRole(AriaRole.BUTTON)).hasCSS("display", "flex");
from copilotbrowser.async_api import expect

locator = page.get_by_role("button")
await expect(locator).to_have_css("display", "flex")
from copilotbrowser.sync_api import expect

locator = page.get_by_role("button")
expect(locator).to_have_css("display", "flex")
var locator = Page.GetByRole(AriaRole.Button);
await Expect(locator).ToHaveCSSAsync("display", "flex");

param: LocatorAssertions.toHaveCSS#1.name​

Added in: v1.18

  • name <string>

CSS property name.

param: LocatorAssertions.toHaveCSS#1.value​

Added in: v1.18

  • value <string|RegExp>

CSS property value.

option: LocatorAssertions.toHaveCSS#1.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveCSS#1.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveCSS#2​

Added in: v1.58

Languages: JavaScript

Ensures the Locator resolves to an element with the given computed CSS properties. Only the listed properties are checked.

Usage

const locator = page.getByRole('button');
await expect(locator).toHaveCSS({
  display: 'flex',
  backgroundColor: 'rgb(255, 0, 0)'
});

param: LocatorAssertions.toHaveCSS#2.styles​

Added in: v1.58

  • styles <Object>

CSS properties object. See CSSStyleProperties for available properties.

option: LocatorAssertions.toHaveCSS#2.timeout = %%-js-assertions-timeout-%%​

Added in: v1.58

async method: LocatorAssertions.toHaveId​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an element with the given DOM Node ID.

Usage

const locator = page.getByRole('textbox');
await expect(locator).toHaveId('lastname');
assertThat(page.getByRole(AriaRole.TEXTBOX)).hasId("lastname");
from copilotbrowser.async_api import expect

locator = page.get_by_role("textbox")
await expect(locator).to_have_id("lastname")
from copilotbrowser.sync_api import expect

locator = page.get_by_role("textbox")
expect(locator).to_have_id("lastname")
var locator = Page.GetByRole(AriaRole.Textbox);
await Expect(locator).ToHaveIdAsync("lastname");

param: LocatorAssertions.toHaveId.id​

Added in: v1.18

  • id <string|RegExp>

Element id.

option: LocatorAssertions.toHaveId.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveId.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveJSProperty​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an element with given JavaScript property. Note that this property can be of a primitive type as well as a plain serializable JavaScript object.

Usage

const locator = page.locator('.component');
await expect(locator).toHaveJSProperty('loaded', true);
assertThat(page.locator("input")).hasJSProperty("loaded", true);
from copilotbrowser.async_api import expect

locator = page.locator(".component")
await expect(locator).to_have_js_property("loaded", True)
from copilotbrowser.sync_api import expect

locator = page.locator(".component")
expect(locator).to_have_js_property("loaded", True)
var locator = Page.Locator(".component");
await Expect(locator).ToHaveJSPropertyAsync("loaded", true);

param: LocatorAssertions.toHaveJSProperty.name​

Added in: v1.18

  • name <string>

Property name.

param: LocatorAssertions.toHaveJSProperty.value​

Added in: v1.18

  • value <any>

Property value.

option: LocatorAssertions.toHaveJSProperty.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveJSProperty.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveRole​

Added in: v1.44

Languages: (all)

Ensures the Locator points to an element with a given ARIA role.

Note that role is matched as a string, disregarding the ARIA role hierarchy. For example, asserting a superclass role "checkbox" on an element with a subclass role "switch" will fail.

Usage

const locator = page.getByTestId('save-button');
await expect(locator).toHaveRole('button');
Locator locator = page.getByTestId("save-button");
assertThat(locator).hasRole(AriaRole.BUTTON);
locator = page.get_by_test_id("save-button")
await expect(locator).to_have_role("button")
locator = page.get_by_test_id("save-button")
expect(locator).to_have_role("button")
var locator = Page.GetByTestId("save-button");
await Expect(locator).ToHaveRoleAsync(AriaRole.Button);

param: LocatorAssertions.toHaveRole.role = %%-get-by-role-to-have-role-role-%%​

Added in: v1.44

option: LocatorAssertions.toHaveRole.timeout = %%-js-assertions-timeout-%%​

Added in: v1.44

option: LocatorAssertions.toHaveRole.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.44

async method: LocatorAssertions.toHaveScreenshot#1​

Added in: v1.23

Languages: JavaScript

This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.

Usage

const locator = page.getByRole('button');
await expect(locator).toHaveScreenshot('image.png');

Note that screenshot assertions only work with copilotbrowser test runner.

param: LocatorAssertions.toHaveScreenshot#1.name​

Added in: v1.23

  • name <string|Array<string>>

Snapshot name.

option: LocatorAssertions.toHaveScreenshot#1.timeout = %%-js-assertions-timeout-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.animations = %%-screenshot-option-animations-default-disabled-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.caret = %%-screenshot-option-caret-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.mask = %%-screenshot-option-mask-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.maskColor = %%-screenshot-option-mask-color-%%​

Added in: v1.35

option: LocatorAssertions.toHaveScreenshot#1.stylePath = %%-screenshot-option-style-path-%%​

Added in: v1.41

option: LocatorAssertions.toHaveScreenshot#1.omitBackground = %%-screenshot-option-omit-background-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.scale = %%-screenshot-option-scale-default-css-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.maxDiffPixels = %%-assertions-max-diff-pixels-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#1.threshold = %%-assertions-threshold-%%​

Added in: v1.23

async method: LocatorAssertions.toHaveScreenshot#2​

Added in: v1.23

Languages: JavaScript

This function will wait until two consecutive locator screenshots yield the same result, and then compare the last screenshot with the expectation.

Usage

const locator = page.getByRole('button');
await expect(locator).toHaveScreenshot();

Note that screenshot assertions only work with copilotbrowser test runner.

option: LocatorAssertions.toHaveScreenshot#2.timeout = %%-js-assertions-timeout-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.animations = %%-screenshot-option-animations-default-disabled-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.caret = %%-screenshot-option-caret-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.mask = %%-screenshot-option-mask-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.maskColor = %%-screenshot-option-mask-color-%%​

Added in: v1.35

option: LocatorAssertions.toHaveScreenshot#2.stylePath = %%-screenshot-option-style-path-%%​

Added in: v1.41

option: LocatorAssertions.toHaveScreenshot#2.omitBackground = %%-screenshot-option-omit-background-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.scale = %%-screenshot-option-scale-default-css-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.maxDiffPixels = %%-assertions-max-diff-pixels-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.maxDiffPixelRatio = %%-assertions-max-diff-pixel-ratio-%%​

Added in: v1.23

option: LocatorAssertions.toHaveScreenshot#2.threshold = %%-assertions-threshold-%%​

Added in: v1.23

async method: LocatorAssertions.toHaveText​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an element with the given text. All nested elements will be considered when computing the text content of the element. You can use regular expressions for the value as well.

Details

When expected parameter is a string, copilotbrowser will normalize whitespaces and line breaks both in the actual text and in the expected string before matching. When regular expression is used, the actual text is matched as is.

Usage

const locator = page.locator('.title');
await expect(locator).toHaveText(/Welcome, Test User/);
await expect(locator).toHaveText(/Welcome, .*/);
assertThat(page.locator(".title")).hasText("Welcome, Test User");
assertThat(page.locator(".title")).hasText(Pattern.compile("Welcome, .*"));
import re
from copilotbrowser.async_api import expect

locator = page.locator(".title")
await expect(locator).to_have_text(re.compile(r"Welcome, Test User"))
await expect(locator).to_have_text(re.compile(r"Welcome, .*"))
import re
from copilotbrowser.sync_api import expect

locator = page.locator(".title")
expect(locator).to_have_text(re.compile(r"Welcome, Test User"))
expect(locator).to_have_text(re.compile(r"Welcome, .*"))
var locator = Page.Locator(".title");
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, Test User"));
await Expect(locator).ToHaveTextAsync(new Regex("Welcome, .*"));

If you pass an array as an expected value, the expectations are:

  1. Locator resolves to a list of elements.
  2. The number of elements equals the number of expected values in the array.
  3. Elements from the list have text matching expected array values, one by one, in order.

For example, consider the following list:

<ul>
  <li>Text 1</li>
  <li>Text 2</li>
  <li>Text 3</li>
</ul>

Let's see how we can use the assertion:

// ✓ Has the right items in the right order
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text 3']);

// ✖ Wrong order
await expect(page.locator('ul > li')).toHaveText(['Text 3', 'Text 2', 'Text 1']);

// ✖ Last item does not match
await expect(page.locator('ul > li')).toHaveText(['Text 1', 'Text 2', 'Text']);

// ✖ Locator points to the outer list element, not to the list items
await expect(page.locator('ul')).toHaveText(['Text 1', 'Text 2', 'Text 3']);
// ✓ Has the right items in the right order
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});

// ✖ Wrong order
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 3", "Text 2", "Text 1"});

// ✖ Last item does not match
assertThat(page.locator("ul > li")).hasText(new String[] {"Text 1", "Text 2", "Text"});

// ✖ Locator points to the outer list element, not to the list items
assertThat(page.locator("ul")).hasText(new String[] {"Text 1", "Text 2", "Text 3"});
from copilotbrowser.async_api import expect

# ✓ Has the right items in the right order
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])

# ✖ Wrong order
await expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])

# ✖ Last item does not match
await expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])

# ✖ Locator points to the outer list element, not to the list items
await expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])
from copilotbrowser.sync_api import expect

# ✓ Has the right items in the right order
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text 3"])

# ✖ Wrong order
expect(page.locator("ul > li")).to_have_text(["Text 3", "Text 2", "Text 1"])

# ✖ Last item does not match
expect(page.locator("ul > li")).to_have_text(["Text 1", "Text 2", "Text"])

# ✖ Locator points to the outer list element, not to the list items
expect(page.locator("ul")).to_have_text(["Text 1", "Text 2", "Text 3"])
// ✓ Has the right items in the right order
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text 3"});

// ✖ Wrong order
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 3", "Text 2", "Text 1"});

// ✖ Last item does not match
await Expect(Page.Locator("ul > li")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text"});

// ✖ Locator points to the outer list element, not to the list items
await Expect(Page.Locator("ul")).ToHaveTextAsync(new string[] {"Text 1", "Text 2", "Text 3"});

param: LocatorAssertions.toHaveText.expected​

Added in: v1.18

Languages: JavaScript

  • expected <string|RegExp|Array<string|RegExp>>

Expected string or RegExp or a list of those.

param: LocatorAssertions.toHaveText.expected​

Added in: v1.18

Languages: Python

  • expected <string|RegExp|Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected string or RegExp or a list of those.

param: LocatorAssertions.toHaveText.expected​

Added in: v1.18

Languages: Java, C#

  • expected <string|RegExp|Array<string>|Array<RegExp>>

Expected string or RegExp or a list of those.

option: LocatorAssertions.toHaveText.ignoreCase = %%-assertions-ignore-case-%%​

Added in: v1.23

option: LocatorAssertions.toHaveText.useInnerText​

Added in: v1.18

  • useInnerText <boolean>

Whether to use element.innerText instead of element.textContent when retrieving DOM node text.

option: LocatorAssertions.toHaveText.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveText.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveValue​

Added in: v1.20

Languages: (all)

Ensures the Locator points to an element with the given input value. You can use regular expressions for the value as well.

Usage

const locator = page.locator('input[type=number]');
await expect(locator).toHaveValue(/[0-9]/);
assertThat(page.locator("input[type=number]")).hasValue(Pattern.compile("[0-9]"));
import re
from copilotbrowser.async_api import expect

locator = page.locator("input[type=number]")
await expect(locator).to_have_value(re.compile(r"[0-9]"))
import re
from copilotbrowser.sync_api import expect

locator = page.locator("input[type=number]")
expect(locator).to_have_value(re.compile(r"[0-9]"))
var locator = Page.Locator("input[type=number]");
await Expect(locator).ToHaveValueAsync(new Regex("[0-9]"));

param: LocatorAssertions.toHaveValue.value​

Added in: v1.18

  • value <string|RegExp>

Expected value.

option: LocatorAssertions.toHaveValue.timeout = %%-js-assertions-timeout-%%​

Added in: v1.18

option: LocatorAssertions.toHaveValue.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.18

async method: LocatorAssertions.toHaveValues​

Added in: v1.23

Languages: (all)

Ensures the Locator points to multi-select/combobox (i.e. a select with the multiple attribute) and the specified values are selected.

Usage

For example, given the following element:

<select id="favorite-colors" multiple>
  <option value="R">Red</option>
  <option value="G">Green</option>
  <option value="B">Blue</option>
</select>
const locator = page.locator('id=favorite-colors');
await locator.selectOption(['R', 'G']);
await expect(locator).toHaveValues([/R/, /G/]);
page.locator("id=favorite-colors").selectOption(new String[]{"R", "G"});
assertThat(page.locator("id=favorite-colors")).hasValues(new Pattern[] { Pattern.compile("R"), Pattern.compile("G") });
import re
from copilotbrowser.async_api import expect

locator = page.locator("id=favorite-colors")
await locator.select_option(["R", "G"])
await expect(locator).to_have_values([re.compile(r"R"), re.compile(r"G")])
import re
from copilotbrowser.sync_api import expect

locator = page.locator("id=favorite-colors")
locator.select_option(["R", "G"])
expect(locator).to_have_values([re.compile(r"R"), re.compile(r"G")])
var locator = Page.Locator("id=favorite-colors");
await locator.SelectOptionAsync(new string[] { "R", "G" });
await Expect(locator).ToHaveValuesAsync(new Regex[] { new Regex("R"), new Regex("G") });

param: LocatorAssertions.toHaveValues.values​

Added in: v1.23

Languages: JavaScript

  • values <Array<string|RegExp>>

Expected options currently selected.

param: LocatorAssertions.toHaveValues.values​

Added in: v1.23

Languages: Python

  • values <Array<string>|Array<RegExp>|Array<string|RegExp>>

Expected options currently selected.

param: LocatorAssertions.toHaveValues.values​

Added in: v1.23

Languages: Java, C#

  • values <Array<string>|Array<RegExp>>

Expected options currently selected.

option: LocatorAssertions.toHaveValues.timeout = %%-js-assertions-timeout-%%​

Added in: v1.23

option: LocatorAssertions.toHaveValues.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.23

async method: LocatorAssertions.toMatchAriaSnapshot​

Added in: v1.49

Languages: (all)

Asserts that the target element matches the given accessibility snapshot.

Usage

await page.goto('https://demo.copilotbrowser.dev/todomvc/');
await expect(page.locator('body')).toMatchAriaSnapshot(`
  - heading "todos"
  - textbox "What needs to be done?"
`);
await page.goto("https://demo.copilotbrowser.dev/todomvc/")
await expect(page.locator('body')).to_match_aria_snapshot('''
  - heading "todos"
  - textbox "What needs to be done?"
''')
page.goto("https://demo.copilotbrowser.dev/todomvc/")
expect(page.locator('body')).to_match_aria_snapshot('''
  - heading "todos"
  - textbox "What needs to be done?"
''')
await page.GotoAsync("https://demo.copilotbrowser.dev/todomvc/");
await Expect(page.Locator("body")).ToMatchAriaSnapshotAsync(@"
  - heading ""todos""
  - textbox ""What needs to be done?""
");
page.navigate("https://demo.copilotbrowser.dev/todomvc/");
assertThat(page.locator("body")).matchesAriaSnapshot("""
  - heading "todos"
  - textbox "What needs to be done?"
""");

param: LocatorAssertions.toMatchAriaSnapshot.expected​

Added in: v1.49

  • expected

option: LocatorAssertions.toMatchAriaSnapshot.timeout = %%-js-assertions-timeout-%%​

Added in: v1.49

option: LocatorAssertions.toMatchAriaSnapshot.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.49

async method: LocatorAssertions.toMatchAriaSnapshot#2​

Added in: v1.50

Languages: JavaScript

Asserts that the target element matches the given accessibility snapshot.

Snapshot is stored in a separate .aria.yml file in a location configured by expect.toMatchAriaSnapshot.pathTemplate and/or snapshotPathTemplate properties in the configuration file.

Usage

await expect(page.locator('body')).toMatchAriaSnapshot();
await expect(page.locator('body')).toMatchAriaSnapshot({ name: 'body.aria.yml' });

option: LocatorAssertions.toMatchAriaSnapshot#2.name​

Added in: v1.50

Languages: JavaScript

  • name <string>

Name of the snapshot to store in the snapshot folder corresponding to this test. Generates sequential names if not specified.

option: LocatorAssertions.toMatchAriaSnapshot#2.timeout = %%-js-assertions-timeout-%%​

Added in: v1.50

option: LocatorAssertions.toMatchAriaSnapshot#2.timeout = %%-csharp-java-python-assertions-timeout-%%​

Added in: v1.50