Interface LocatorAssertions

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

import { expect } from '@libra/expect';
import { test } from '@libra/test';

test('status becomes submitted', async () => {
  // ...
  browser = await createLibraBrowser(launchType, {
    platformName: 'DESKTOP',
  });
  page = await createLibraPage(browser);

  await page.goto(`URL`, {
     timeout: 60000,
  });
  await page.getByRole('button').click();
  await expect(page.locator('.status')).toHaveText('Submitted');
});

interface LocatorAssertions {
    not: LocatorAssertions;
    toBeAttached(options?: {
        timeout?: number;
    }): Promise<void>;
    toBeChecked(options?: {
        checked?: boolean;
        timeout?: number;
    }): Promise<void>;
    toBeDisabled(options?: {
        timeout?: number;
    }): Promise<void>;
    toBeEditable(options?: {
        timeout?: number;
    }): Promise<void>;
    toBeEnabled(options?: {
        timeout?: number;
    }): Promise<void>;
    toBeFocused(options?: {
        timeout?: number;
    }): Promise<void>;
    toBeHidden(options?: {
        timeout?: number;
    }): Promise<void>;
    toBeInViewport(options?: {
        timeout?: number;
    }): Promise<void>;
    toBeLeftOf(locator: Locator): Promise<void>;
    toBeTopOf(locator: Locator): Promise<void>;
    toBeVisible(options?: {
        timeout?: number;
        visible?: boolean;
    }): Promise<void>;
    toContainText(expected: string | RegExp | (string | RegExp)[], options?: {
        ignoreCase?: boolean;
        timeout?: number;
    }): Promise<void>;
    toHaveAttribute(name: string, value: string | RegExp, options?: {
        ignoreCase?: boolean;
        timeout?: number;
    }): Promise<void>;
    toHaveAttribute(name: string, options?: {
        timeout?: number;
    }): Promise<void>;
    toHaveCSS(name: string, value: string | RegExp, options?: {
        timeout?: number;
    }): Promise<void>;
    toHaveClass(expected: string | RegExp | (string | RegExp)[], options?: {
        timeout?: number;
    }): Promise<void>;
    toHaveCount(count: number, options?: {
        timeout?: number;
    }): Promise<void>;
    toHaveText(expected: string | RegExp | (string | RegExp)[], options?: {
        ignoreCase?: boolean;
        timeout?: number;
    }): Promise<void>;
    toHaveValue(value: string | RegExp, options?: {
        timeout?: number;
    }): Promise<void>;
}

Index

Properties

not

Methods

toBeAttached toBeChecked toBeDisabled toBeEditable toBeEnabled toBeFocused toBeHidden toBeInViewport toBeLeftOf toBeTopOf toBeVisible toContainText toHaveAttribute toHaveCSS toHaveClass toHaveCount toHaveText toHaveValue

Properties

not

not: LocatorAssertions

Makes the assertion check for the opposite condition. For example, this code tests that the Locator doesn't contain text "error":

await expect(locator).not.toContainText('error');

Methods

toBeAttached

toBeAttached(options?): Promise<void>
Ensures that Locator points to an attached DOM node.

Usage
```
await expect(page.getByText('Hidden text')).toBeAttached();
```
Parameters
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toBeChecked

toBeChecked(options?): Promise<void>
Ensures the Locator points to a checked input.

Usage
```
const locator = page.getByLabel('Subscribe to newsletter');
await expect(locator).toBeChecked();
```
Parameters
- Optionaloptions: {
  checked?: boolean;
  timeout?: number;
  }
  - Optionalchecked?: boolean
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toBeDisabled

toBeDisabled(options?): Promise<void>
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();
```
Parameters
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toBeEditable

toBeEditable(options?): Promise<void>
Ensures the Locator points to an editable element.

Usage
```
const locator = page.getByRole('textbox');
await expect(locator).toBeEditable();
```
Parameters
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toBeEnabled

toBeEnabled(options?): Promise<void>
Ensures the Locator points to an enabled element.

Usage
```
const locator = page.locator('button.submit');
await expect(locator).toBeEnabled();
```
Parameters
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toBeFocused

toBeFocused(options?): Promise<void>
Ensures the Locator points to a focused DOM node.

Usage
```
const locator = page.getByRole('textbox');
await expect(locator).toBeFocused();
```
Parameters
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toBeHidden

toBeHidden(options?): Promise<void>
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();
```
Parameters
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toBeInViewport

toBeInViewport(options?): Promise<void>

Ensures the Locator points to an element that intersects viewport, according to the intersection observer API. ratio in options was not supported 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();

Parameters

Optionaloptions: {
timeout?: number;
}
- Optionaltimeout?: number
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.

Returns Promise<void>

toBeLeftOf

toBeLeftOf(locator): Promise<void>
Parameters
- locator: Locator
  Libra.Locator
Returns Promise<void>

toBeTopOf

toBeTopOf(locator): Promise<void>
Parameters
- locator: Locator
  Libra.Locator
Returns Promise<void>

toBeVisible

toBeVisible(options?): Promise<void>

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();

Parameters

Optionaloptions: {
timeout?: number;
visible?: boolean;
}
- Optionaltimeout?: number
  Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
- Optionalvisible?: boolean

Returns Promise<void>

toContainText

toContainText(expected, options?): Promise<void>
Ensures the Locator points to an element that contains the given text. You can use regular expressions for the value as well.

Details

When expected parameter is a string, Playwright 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/);
```
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']);
```
Parameters
- expected: string | RegExp | (string | RegExp)[]
  Expected substring or RegExp or a list of those.
- Optionaloptions: {
  ignoreCase?: boolean;
  timeout?: number;
  }
  - OptionalignoreCase?: boolean
    Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toHaveAttribute

toHaveAttribute(name, value, options?): Promise<void>
Ensures the Locator points to an element with given attribute.

Usage
```
const locator = page.locator('input');
await expect(locator).toHaveAttribute('type', 'text');
```
Parameters
- name: string
  Attribute name.
- value: string | RegExp
  Expected attribute value.
- Optionaloptions: {
  ignoreCase?: boolean;
  timeout?: number;
  }
  - OptionalignoreCase?: boolean
    Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>
toHaveAttribute(name, options?): Promise<void>
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');
```
Parameters
- name: string
  Attribute name.
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toHaveCSS

toHaveCSS(name, value, options?): Promise<void>
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');
```
Parameters
- name: string
  CSS property name.
- value: string | RegExp
  CSS property value.
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toHaveClass

toHaveClass(expected, options?): Promise<void>
Ensures the Locator points to an element with given CSS classes. This needs to be a full match or using a relaxed regular expression.

Usage
```
<div class='selected row' id='component'></div>
```
```
const locator = page.locator('#component');
await expect(locator).toHaveClass(/selected/);
await expect(locator).toHaveClass('selected row');
```
Note that if array is passed as an expected value, entire lists of elements can be asserted:
```
const locator = page.locator('list > .component');
await expect(locator).toHaveClass(['component', 'component selected', 'component']);
```
Parameters
- expected: string | RegExp | (string | RegExp)[]
  Expected class or RegExp or a list of those.
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toHaveCount

toHaveCount(count, options?): Promise<void>
Ensures the Locator resolves to an exact number of DOM nodes.

Usage
```
const list = page.locator('list > .component');
await expect(list).toHaveCount(3);
```
Parameters
- count: number
  Expected count.
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toHaveText

toHaveText(expected, options?): Promise<void>
Ensures the Locator points to an element with the given text. You can use regular expressions for the value as well.

Details

When expected parameter is a string, Playwright 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, .*/);
```
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']);
```
Parameters
- expected: string | RegExp | (string | RegExp)[]
  Expected string or RegExp or a list of those.
- Optionaloptions: {
  ignoreCase?: boolean;
  timeout?: number;
  }
  - OptionalignoreCase?: boolean
    Whether to perform case-insensitive match. ignoreCase option takes precedence over the corresponding regular expression flag if specified.
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

toHaveValue

toHaveValue(value, options?): Promise<void>
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]/);
```
Parameters
- value: string | RegExp
  Expected value.
- Optionaloptions: {
  timeout?: number;
  }
  - Optionaltimeout?: number
    Time to retry the assertion for in milliseconds. Defaults to timeout in TestConfig.expect.
Returns Promise<void>

Interface LocatorAssertions

Index

Properties

Methods

Properties

not

Methods

toBeAttached

Parameters

Optionaltimeout?: number

Returns Promise<void>

toBeChecked

Parameters

Optionalchecked?: boolean

Optionaltimeout?: number

Returns Promise<void>

toBeDisabled

Parameters

Optionaltimeout?: number

Returns Promise<void>

toBeEditable

Parameters

Optionaltimeout?: number

Returns Promise<void>

toBeEnabled

Parameters

Optionaltimeout?: number

Returns Promise<void>

toBeFocused

Parameters

Optionaltimeout?: number

Returns Promise<void>

toBeHidden

Parameters

Optionaltimeout?: number

Returns Promise<void>

toBeInViewport

Parameters

Optionaltimeout?: number

Returns Promise<void>

toBeLeftOf

Parameters

Returns Promise<void>

toBeTopOf

Parameters

Returns Promise<void>

toBeVisible

Parameters

Optionaltimeout?: number

Optionalvisible?: boolean

Returns Promise<void>

toContainText

Parameters

OptionalignoreCase?: boolean

Optionaltimeout?: number

Returns Promise<void>

toHaveAttribute

Parameters

OptionalignoreCase?: boolean

Optionaltimeout?: number

Returns Promise<void>

Parameters

Optionaltimeout?: number

Returns Promise<void>

toHaveCSS

Parameters

Optionaltimeout?: number

Returns Promise<void>

toHaveClass

Parameters

Optionaltimeout?: number

Returns Promise<void>

toHaveCount

Parameters

Optionaltimeout?: number

Returns Promise<void>

toHaveText

Parameters

OptionalignoreCase?: boolean

Optionaltimeout?: number

`Optional`timeout?: number

`Optional`checked?: boolean

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`visible?: boolean

`Optional`ignoreCase?: boolean

`Optional`timeout?: number

`Optional`ignoreCase?: boolean

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`timeout?: number

`Optional`ignoreCase?: boolean

`Optional`timeout?: number

`Optional`timeout?: number