expect — assertions

  • Release version: Australia
  • Updated June 25, 2026
  • 1 minute to read

    • The expect API makes assertions about elements or values in a Run UI Test Script step. Pass a DOM element for element-specific matchers, or pass any other value for value matchers.

    Element matchers

    const [btn] = screen.getAllByRole('button', { name: 'Submit' });
expect(btn).toBeVisible();
expect(btn).toBeEnabled();
expect(btn).not.toBeDisabled();
expect(btn).toHaveTextContent('Submit');
    Table 1. Element matchers
    Matcher Asserts
    .toBeVisible() Element is in the DOM and visible, not hidden by CSS.
    .toBeHidden() Element isn't visible.
    .toBeEnabled() Form control isn't disabled.
    .toBeDisabled() Form control is disabled or has aria-disabled="true".
    .toBeChecked() Check box or radio is checked.
    .toBePartiallyChecked() Check box is indeterminate.
    .toBeInTheDocument() Element exists in the document.
    .toBeEmptyDOMElement() Element has no child nodes.
    .toHaveFocus() Element has keyboard focus.
    .toHaveTextContent(text) Element's text content matches a string or RegExp.
    .toHaveValue(value) Form control's current value matches.
    .toHaveDisplayValue(value) Visible label of a <select> matches.
    .toHaveAttribute(name, value?) Element has the attribute, optionally with a specific value.
    .toHaveClass(...classes) Element has all listed CSS classes.
    .toHaveStyle(styles) Element has the given inline or computed styles.
    .toHaveAccessibleName(name) ARIA accessible name matches.
    .toHaveAccessibleDescription(desc) ARIA accessible description matches.
    .toContainElement(child) Element contains child.
    .toHaveRole(role) Element has the given ARIA role.
    .toHaveFormValues(values) Form element's fields match the given value map.
    .toBeRequired() Form control is required.
    .toBeValid() Form control passes validation.
    .toBeInvalid() Form control fails validation.
    .toHaveErrorMessage(text?) Element has an associated error message.

    Value matchers

    When expect receives a non-element value, it delegates to value matchers.

    expect(2 + 2).toBe(4);
expect({ a: 1 }).toEqual({ a: 1 });
expect([1, 2, 3]).toContain(2);
expect('hello').toMatch(/ell/);
expect(null).toBeNull();
expect(undefined).toBeUndefined();

    Polling with expect

    expect throws synchronously on failure. Combine it with waitFor to retry.

    await waitFor(() => {
  expect(screen.getByRole('status')).toHaveTextContent('Saved');
});