Assertion API

Vitest предоставляет широкий спектр DOM-утверждений, унаследованных от библиотеки @testing-library/jest-dom, с поддержкой локаторов и встроенным механизмом повторных попыток.

Поддержка TypeScript

Если вы используете TypeScript или хотите получать корректные подсказки типов в expect, убедитесь, что в вашем проекте присутствует ссылка на @vitest/browser/context. Если вы никогда не импортировали оттуда, вы можете добавить комментарий reference в любой файл, входящий в область действия вашего tsconfig.json:

/// <reference types="@vitest/browser/context" />

Тесты в браузере могут непредсказуемо завершаться с ошибкой из-за их асинхронной природы. Из-за этого важно обеспечить успешность утверждений, даже если выполнение условия задерживается (например, из-за таймаута, сетевого запроса или анимации). Для этой цели Vitest предоставляет встроенные утверждения с возможностью повторных попыток через API expect.poll и expect.element:

import { expect, test } from 'vitest';
import { page } from '@vitest/browser/context';

test('error banner is rendered', async () => {
  triggerError();

  // Это создает локатор для поиска элемента при вызове любого из его методов.
  // Этот вызов сам по себе не проверяет существование элемента.
  const banner = page.getByRole('alert', {
    name: /error/i,
  });

  // Vitest предоставляет `expect.element` со встроенной возможностью повторных попыток.
  // Он будет многократно проверять, что элемент существует в DOM и что содержимое `element.textContent` равно "Error!" до тех пор, пока все условия не будут выполнены
  await expect.element(banner).toHaveTextContent('Error!');
});

Мы рекомендуем всегда использовать expect.element при работе с локаторами page.getBy*, чтобы уменьшить количество нестабильных тестов. Обратите внимание, что expect.element принимает вторую опцию:

interface ExpectPollOptions {
  // Интервал для повторных попыток утверждения в миллисекундах
  // По умолчанию используется опция конфигурации "expect.poll.interval"
  interval?: number;
  // Время для повторных попыток утверждения в миллисекундах
  // По умолчанию используется опция конфигурации "expect.poll.timeout"
  timeout?: number;
  // Сообщение, отображаемое при сбое утверждения
  message?: string;
}

TIP

expect.element — это сокращение для expect.poll(() => element) и работает точно так же.

toHaveTextContent и все остальные утверждения по-прежнему доступны в обычном expect без встроенного механизма повторных попыток:

// сразу же выдаст ошибку, если .textContent не равен `'Error!'`
expect(banner).toHaveTextContent('Error!');

toBeDisabled

function toBeDisabled(): Promise<void>;

Позволяет проверить, отключен ли элемент с точки зрения пользовательского интерфейса.

Совпадает, если элемент является элементом управления формы и атрибут disabled указан для него, или элемент является потомком элемента формы с атрибутом disabled.

Обратите внимание, что только нативные элементы управления, такие как HTML button, input, select, textarea, option, optgroup, могут быть отключены установкой атрибута "disabled". Атрибут "disabled" на других элементах игнорируется, за исключением пользовательских элементов.

html

<button data-testid="button" type="submit" disabled>submit</button>

await expect.element(getByTestId('button')).toBeDisabled(); // ✅
await expect.element(getByTestId('button')).not.toBeDisabled(); // ❌

toBeEnabled

function toBeEnabled(): Promise<void>;

Позволяет проверить, не отключен ли элемент с точки зрения пользователя.

Работает как not.toBeDisabled(). Используйте этот сопоставитель, чтобы избежать двойного отрицания в ваших тестах.

html

<button data-testid="button" type="submit" disabled>submit</button>

await expect.element(getByTestId('button')).toBeEnabled(); // ✅
await expect.element(getByTestId('button')).not.toBeEnabled(); // ❌

toBeEmptyDOMElement

function toBeEmptyDOMElement(): Promise<void>;

Это позволяет вам утверждать, что элемент не имеет видимого содержимого для пользователя. Он игнорирует комментарии, но выдаст ошибку, если элемент содержит пробельные символы.

html

<span data-testid="not-empty"><span data-testid="empty"></span></span>
<span data-testid="with-whitespace"> </span>
<span data-testid="with-comment"><!-- comment --></span>

await expect.element(getByTestId('empty')).toBeEmptyDOMElement();
await expect.element(getByTestId('not-empty')).not.toBeEmptyDOMElement();
await expect.element(getByTestId('with-whitespace')).not.toBeEmptyDOMElement();

toBeInTheDocument

function toBeInTheDocument(): Promise<void>;

Позволяет утвердить, присутствует ли элемент в документе.

html

<svg data-testid="svg-element"></svg>

await expect.element(getByTestId('svg-element')).toBeInTheDocument();
await expect.element(getByTestId('does-not-exist')).not.toBeInTheDocument();

WARNING

Этот сопоставитель не находит отсоединенные элементы. Элемент должен быть добавлен в документ, чтобы быть найденным toBeInTheDocument. Если требуется поиск в отсоединенном элементе, используйте: toContainElement.

toBeInvalid

function toBeInvalid(): Promise<void>;

Это позволяет проверить, является ли элемент в данный момент недействительным.

Элемент является недействительным, если он имеет атрибут aria-invalid без указанного значения или со значением "true", или если результат checkValidity() равен false.

html

<input data-testid="no-aria-invalid" />
<input data-testid="aria-invalid" aria-invalid />
<input data-testid="aria-invalid-value" aria-invalid="true" />
<input data-testid="aria-invalid-false" aria-invalid="false" />

<form data-testid="valid-form">
  <input />
</form>

<form data-testid="invalid-form">
  <input required />
</form>

await expect.element(getByTestId('no-aria-invalid')).not.toBeInvalid();
await expect.element(getByTestId('aria-invalid')).toBeInvalid();
await expect.element(getByTestId('aria-invalid-value')).toBeInvalid();
await expect.element(getByTestId('aria-invalid-false')).not.toBeInvalid();

await expect.element(getByTestId('valid-form')).not.toBeInvalid();
await expect.element(getByTestId('invalid-form')).toBeInvalid();

toBeRequired

function toBeRequired(): Promise<void>;

Это позволяет проверить, является ли элемент формы в данный момент обязательным.

Элемент считается обязательным, если он имеет атрибут required или aria-required="true".

html

<input data-testid="required-input" required />
<input data-testid="aria-required-input" aria-required="true" />
<input data-testid="conflicted-input" required aria-required="false" />
<input data-testid="aria-not-required-input" aria-required="false" />
<input data-testid="optional-input" />
<input data-testid="unsupported-type" type="image" required />
<select data-testid="select" required></select>
<textarea data-testid="textarea" required></textarea>
<div data-testid="supported-role" role="tree" required></div>
<div data-testid="supported-role-aria" role="tree" aria-required="true"></div>

await expect.element(getByTestId('required-input')).toBeRequired();
await expect.element(getByTestId('aria-required-input')).toBeRequired();
await expect.element(getByTestId('conflicted-input')).toBeRequired();
await expect.element(getByTestId('aria-not-required-input')).not.toBeRequired();
await expect.element(getByTestId('optional-input')).not.toBeRequired();
await expect.element(getByTestId('unsupported-type')).not.toBeRequired();
await expect.element(getByTestId('select')).toBeRequired();
await expect.element(getByTestId('textarea')).toBeRequired();
await expect.element(getByTestId('supported-role')).not.toBeRequired();
await expect.element(getByTestId('supported-role-aria')).toBeRequired();

toBeValid

function toBeValid(): Promise<void>;

Это позволяет проверить, является ли значение элемента в данный момент действительным.

Элемент является действительным, если он не имеет атрибута aria-invalid или имеет значение атрибута "false". Результат checkValidity() также должен быть true, если это элемент формы.

html

<input data-testid="no-aria-invalid" />
<input data-testid="aria-invalid" aria-invalid />
<input data-testid="aria-invalid-value" aria-invalid="true" />
<input data-testid="aria-invalid-false" aria-invalid="false" />

<form data-testid="valid-form">
  <input />
</form>

<form data-testid="invalid-form">
  <input required />
</form>

await expect.element(getByTestId('no-aria-invalid')).toBeValid();
await expect.element(getByTestId('aria-invalid')).not.toBeValid();
await expect.element(getByTestId('aria-invalid-value')).not.toBeValid();
await expect.element(getByTestId('aria-invalid-false')).toBeValid();

await expect.element(getByTestId('valid-form')).toBeValid();
await expect.element(getByTestId('invalid-form')).not.toBeValid();

toBeVisible

function toBeVisible(): Promise<void>;

Это позволяет проверить, виден ли элемент в данный момент пользователю.

Элемент считается видимым, если он имеет ненулевые размеры (непустой ограничивающий прямоугольник) и не имеет вычисленного стиля visibility:hidden.

Обратите внимание, что согласно этому определению:

Элементы нулевых размеров не считаются видимыми.
Элементы с display:none не считаются видимыми.
Элементы с opacity:0 считаются видимыми.

Чтобы проверить, виден ли хотя бы один элемент из списка, используйте locator.first().

// Конкретный элемент виден.
await expect.element(page.getByText('Welcome')).toBeVisible();

// Хотя бы один элемент в списке является видимым.
await expect.element(page.getByTestId('todo-item').first()).toBeVisible();

// Хотя бы один из двух элементов является видимым, возможно, оба.
await expect
  .element(
    page
      .getByRole('button', { name: 'Sign in' })
      .or(page.getByRole('button', { name: 'Sign up' }))
      .first()
  )
  .toBeVisible();

toContainElement

function toContainElement(
  element: HTMLElement | SVGElement | null
): Promise<void>;

Это позволяет вам утверждать, содержит ли один элемент другой элемент в качестве потомка.

html

<span data-testid="ancestor"><span data-testid="descendant"></span></span>

const ancestor = getByTestId('ancestor');
const descendant = getByTestId('descendant');
const nonExistantElement = getByTestId('does-not-exist');

await expect.element(ancestor).toContainElement(descendant);
await expect.element(descendant).not.toContainElement(ancestor);
await expect.element(ancestor).not.toContainElement(nonExistantElement);

toContainHTML

function toContainHTML(htmlText: string): Promise<void>;

Позволяет утвердить, содержится ли строка, представляющая HTML-элемент, в другом элементе. Строка должна содержать валидный HTML, а не неполный HTML.

html

<span data-testid="parent"><span data-testid="child"></span></span>

// Это валидные использования
await expect
  .element(getByTestId('parent'))
  .toContainHTML('<span data-testid="child"></span>');
await expect
  .element(getByTestId('parent'))
  .toContainHTML('<span data-testid="child" />');
await expect.element(getByTestId('parent')).not.toContainHTML('<br />');

// Это не сработает
await expect
  .element(getByTestId('parent'))
  .toContainHTML('data-testid="child"');
await expect.element(getByTestId('parent')).toContainHTML('data-testid');
await expect.element(getByTestId('parent')).toContainHTML('</span>');

WARNING

Вероятно, вам не понадобится использовать этот сопоставитель. Мы рекомендуем тестировать с точки зрения того, как пользователь воспринимает приложение в браузере. Поэтому тестирование, основанное на конкретной структуре DOM, не рекомендуется.

Это может быть полезно в ситуациях, когда тестируемый код отображает HTML, полученный из внешнего источника, и вы хотите проверить, что этот HTML-код был использован корректно.

Его не следует использовать для проверки структуры DOM, которую вы контролируете. Вместо этого используйте toContainElement.

toHaveAccessibleDescription

function toHaveAccessibleDescription(
  description?: string | RegExp
): Promise<void>;

Это позволяет вам утверждать, что элемент имеет ожидаемое доступное описание (описание для вспомогательных технологий).

Вы можете передать точную строку ожидаемого доступного описания, или вы можете выполнить частичное совпадение, используя регулярное выражение, либо expect.stringContaining или expect.stringMatching.

html

<a
  data-testid="link"
  href="/"
  aria-label="Home page"
  title="A link to start over"
  >Start</a
>
<a data-testid="extra-link" href="/about" aria-label="About page">About</a>
<img src="avatar.jpg" data-testid="avatar" alt="User profile pic" />
<img
  src="logo.jpg"
  data-testid="logo"
  alt="Company logo"
  aria-describedby="t1"
/>
<span id="t1" role="presentation">The logo of Our Company</span>
<img
  src="logo.jpg"
  data-testid="logo2"
  alt="Company logo"
  aria-description="The logo of Our Company"
/>

await expect.element(getByTestId('link')).toHaveAccessibleDescription();
await expect
  .element(getByTestId('link'))
  .toHaveAccessibleDescription('A link to start over');
await expect
  .element(getByTestId('link'))
  .not.toHaveAccessibleDescription('Home page');
await expect
  .element(getByTestId('extra-link'))
  .not.toHaveAccessibleDescription();
await expect.element(getByTestId('avatar')).not.toHaveAccessibleDescription();
await expect
  .element(getByTestId('logo'))
  .not.toHaveAccessibleDescription('Company logo');
await expect
  .element(getByTestId('logo'))
  .toHaveAccessibleDescription('The logo of Our Company');
await expect
  .element(getByTestId('logo2'))
  .toHaveAccessibleDescription('The logo of Our Company');

toHaveAccessibleErrorMessage

function toHaveAccessibleErrorMessage(message?: string | RegExp): Promise<void>;

Это позволяет вам утверждать, что элемент имеет ожидаемое доступное сообщение об ошибке.

Вы можете передать точную строку ожидаемого доступного сообщения об ошибке. В качестве альтернативы вы можете выполнить частичное совпадение, передав регулярное выражение или используя expect.stringContaining или expect.stringMatching.

html

<input
  aria-label="Has Error"
  aria-invalid="true"
  aria-errormessage="error-message"
/>
<div id="error-message" role="alert">This field is invalid</div>

<input aria-label="No Error Attributes" />
<input
  aria-label="Not Invalid"
  aria-invalid="false"
  aria-errormessage="error-message"
/>

// Поля ввода с валидными сообщениями об ошибках
await expect
  .element(getByRole('textbox', { name: 'Has Error' }))
  .toHaveAccessibleErrorMessage();
await expect
  .element(getByRole('textbox', { name: 'Has Error' }))
  .toHaveAccessibleErrorMessage('This field is invalid');
await expect
  .element(getByRole('textbox', { name: 'Has Error' }))
  .toHaveAccessibleErrorMessage(/invalid/i);
await expect
  .element(getByRole('textbox', { name: 'Has Error' }))
  .not.toHaveAccessibleErrorMessage('This field is absolutely correct!');

// Поля ввода без валидных сообщений об ошибках
await expect
  .element(getByRole('textbox', { name: 'No Error Attributes' }))
  .not.toHaveAccessibleErrorMessage();

await expect
  .element(getByRole('textbox', { name: 'Not Invalid' }))
  .not.toHaveAccessibleErrorMessage();

toHaveAccessibleName

function toHaveAccessibleName(name?: string | RegExp): Promise<void>;

Это позволяет вам утверждать, что элемент имеет ожидаемое доступное имя. Это полезно, например, для утверждения, что элементы формы и кнопки имеют правильные метки.

Вы можете передать точную строку ожидаемого доступного имени, или вы можете выполнить частичное совпадение, используя регулярное выражение, либо expect.stringContaining или expect.stringMatching.

html

<img data-testid="img-alt" src="" alt="Test alt" />
<img data-testid="img-empty-alt" src="" alt="" />
<svg data-testid="svg-title"><title>Test title</title></svg>
<button data-testid="button-img-alt"><img src="" alt="Test" /></button>
<p><img data-testid="img-paragraph" src="" alt="" /> Test content</p>
<button data-testid="svg-button"><svg><title>Test</title></svg></p>
<div><svg data-testid="svg-without-title"></svg></div>
<input data-testid="input-title" title="test" />

javascript

await expect.element(getByTestId('img-alt')).toHaveAccessibleName('Test alt');
await expect.element(getByTestId('img-empty-alt')).not.toHaveAccessibleName();
await expect
  .element(getByTestId('svg-title'))
  .toHaveAccessibleName('Test title');
await expect.element(getByTestId('button-img-alt')).toHaveAccessibleName();
await expect.element(getByTestId('img-paragraph')).not.toHaveAccessibleName();
await expect.element(getByTestId('svg-button')).toHaveAccessibleName();
await expect
  .element(getByTestId('svg-without-title'))
  .not.toHaveAccessibleName();
await expect.element(getByTestId('input-title')).toHaveAccessibleName();

toHaveAttribute

function toHaveAttribute(attribute: string, value?: unknown): Promise<void>;

Это позволяет вам проверить, имеет ли данный элемент атрибут. Вы также можете опционально проверить, что атрибут имеет определенное ожидаемое значение или частично совпадает, используя expect.stringContaining или expect.stringMatching.

html

<button data-testid="ok-button" type="submit" disabled>ok</button>

const button = getByTestId('ok-button');

await expect.element(button).toHaveAttribute('disabled');
await expect.element(button).toHaveAttribute('type', 'submit');
await expect.element(button).not.toHaveAttribute('type', 'button');

await expect
  .element(button)
  .toHaveAttribute('type', expect.stringContaining('sub'));
await expect
  .element(button)
  .toHaveAttribute('type', expect.not.stringContaining('but'));

toHaveClass

function toHaveClass(
  ...classNames: string[],
  options?: { exact: boolean }
): Promise<void>;
function toHaveClass(...classNames: (string | RegExp)[]): Promise<void>;

Это позволяет вам проверить, содержит ли данный элемент определенные классы в своем атрибуте class. Вы должны предоставить хотя бы один класс, за исключением случаев, когда вы утверждаете, что элемент не имеет никаких классов.

Список имен классов может включать строки и регулярные выражения. Регулярные выражения сопоставляются с каждым отдельным классом в целевом элементе и не сопоставляются со всем значением атрибута class целиком.

WARNING

Обратите внимание, что вы не можете использовать опцию exact: true, если предоставлены только регулярные выражения.

html

<button data-testid="delete-button" class="btn extra btn-danger">
  Delete item
</button>
<button data-testid="no-classes">No Classes</button>

const deleteButton = getByTestId('delete-button');
const noClasses = getByTestId('no-classes');

await expect.element(deleteButton).toHaveClass('extra');
await expect.element(deleteButton).toHaveClass('btn-danger btn');
await expect.element(deleteButton).toHaveClass(/danger/, 'btn');
await expect.element(deleteButton).toHaveClass('btn-danger', 'btn');
await expect.element(deleteButton).not.toHaveClass('btn-link');
await expect.element(deleteButton).not.toHaveClass(/link/);

// ⚠️ регулярное выражение сопоставляется с отдельными классами, а не со всем classList
await expect.element(deleteButton).not.toHaveClass(/btn extra/);

// элемент содержит ТОЧНО набор классов (в любом порядке)
await expect.element(deleteButton).toHaveClass('btn-danger extra btn', {
  exact: true,
});
// если у него больше, чем ожидалось, он выдаст ошибку
await expect.element(deleteButton).not.toHaveClass('btn-danger extra', {
  exact: true,
});

await expect.element(noClasses).not.toHaveClass();

toHaveFocus

function toHaveFocus(): Promise<void>;

Это позволяет вам утверждать, находится ли элемент в фокусе.

html

<div><input type="text" data-testid="element-to-focus" /></div>

const input = page.getByTestId('element-to-focus');
input.element().focus();
await expect.element(input).toHaveFocus();
input.element().blur();
await expect.element(input).not.toHaveFocus();

toHaveFormValues

function toHaveFormValues(
  expectedValues: Record<string, unknown>
): Promise<void>;

Это позволяет вам проверить, содержит ли форма или набор полей поля формы для каждого заданного имени, имеющие указанное значение.

TIP

Важно подчеркнуть, что этот сопоставитель может быть вызван только на элементе form или fieldset.

Это позволяет ему использовать свойство .elements в form и fieldset для надежного получения всех элементов управления формы внутри них.

Это также позволяет избежать ситуаций, когда пользователи предоставляют контейнер, содержащий более одной form, тем самым приводя к смешиванию элементов управления формы, которые не связаны и могут даже конфликтовать друг с другом.

Этот сопоставитель абстрагируется от особенностей получения значения элемента управления формы в зависимости от его типа. Например, элементы <input> имеют атрибут value, но элементы <select> не имеют. Вот список всех охватываемых случаев:

Элементы <input type="number"> возвращают значение как число, а не строку.
Элементы <input type="checkbox">:
- если есть только один с заданным атрибутом name, он рассматривается как логическое значение, возвращающее true, если флажок установлен, false, если не установлен.
- если есть более одного флажка с одним и тем же атрибутом name, они все рассматриваются коллективно как один элемент управления формы, возвращающий значение как массив, содержащий все значения выбранных флажков в коллекции.
Элементы <input type="radio"> группируются по атрибуту name, и такая группа рассматривается как один элемент управления формы. Этот элемент управления формы возвращает значение как строку, соответствующую атрибуту value выбранной радиокнопки в группе.
Элементы <input type="text"> возвращают значение как строку. Это также относится к элементам <input>, имеющим любой другой возможный атрибут type, который явно не охвачен в предыдущих правилах (например, search, email, date, password, hidden и т. д.)
Элементы <select> без атрибута multiple возвращают значение как строку, соответствующую атрибуту value выбранного option, или undefined, если нет выбранного варианта.
Элементы <select multiple> возвращают значение как массив, содержащий все значения выбранных вариантов.
Элементы <textarea> возвращают свое значение как строку. Значение соответствует их содержимому узла.

Вышеуказанные правила облегчают, например, возможность перехода от использования одного элемента управления выбора к использованию группы радиокнопок. Или переход от элемента управления множественным выбором к использованию группы флажков. Результирующий набор значений формы, используемый этим сопоставителем для сравнения, будет одинаковым.

html

<form data-testid="login-form">
  <input type="text" name="username" value="jane.doe" />
  <input type="password" name="password" value="12345678" />
  <input type="checkbox" name="rememberMe" checked />
  <button type="submit">Sign in</button>
</form>

await expect.element(getByTestId('login-form')).toHaveFormValues({
  username: 'jane.doe',
  rememberMe: true,
});

toHaveStyle

function toHaveStyle(css: string | Partial<CSSStyleDeclaration>): Promise<void>;

Это позволяет вам проверить, применены ли к определенному элементу некоторые специфические CSS-свойства с определенными значениями. Он совпадает только в том случае, если ко всем ожидаемым свойствам элемента применены значения, а не только к некоторым из них.

html

<button
  data-testid="delete-button"
  style="display: none; background-color: red"
>
  Delete item
</button>

const button = getByTestId('delete-button');

await expect.element(button).toHaveStyle('display: none');
await expect.element(button).toHaveStyle({ display: 'none' });
await expect.element(button).toHaveStyle(`
  background-color: red;
  display: none;
`);
await expect.element(button).toHaveStyle({
  backgroundColor: 'red',
  display: 'none',
});
await expect.element(button).not.toHaveStyle(`
  background-color: blue;
  display: none;
`);
await expect.element(button).not.toHaveStyle({
  backgroundColor: 'blue',
  display: 'none',
});

Это также работает с правилами, которые применяются к элементу через имя класса, правила для которого определены в таблице стилей, активной в документе. Применяются обычные правила приоритета CSS.

toHaveTextContent

function toHaveTextContent(
  text: string | RegExp,
  options?: { normalizeWhitespace: boolean }
): Promise<void>;

Это позволяет вам проверить, содержит ли данный узел текстовое содержимое. Это применимо к элементам, а также к текстовым узлам и фрагментам документа.

Когда передается строковый аргумент, выполняется частичное совпадение с учетом регистра с содержимым узла.

Для выполнения совпадения без учета регистра, вы можете использовать RegExp с модификатором /i.

Если вы хотите сопоставить все содержимое, вы можете использовать RegExp с этой целью.

html

<span data-testid="text-content">Text Content</span>

const element = getByTestId('text-content');

await expect.element(element).toHaveTextContent('Content');
// для сопоставления всего содержимого
await expect.element(element).toHaveTextContent(/^Text Content$/);
// для использования сопоставления без учета регистра
await expect.element(element).toHaveTextContent(/content$/i);
await expect.element(element).not.toHaveTextContent('content');

toHaveValue

function toHaveValue(value: string | string[] | number | null): Promise<void>;

Это позволяет вам проверить, содержит ли данный элемент формы указанное значение. Он принимает элементы <input>, <select> и <textarea>, за исключением <input type="checkbox"> и <input type="radio">, которые могут быть корректно сопоставлены только с помощью toBeChecked или toHaveFormValues.

Он также принимает элементы с ролями meter, progressbar, slider или spinbutton и проверяет значение их атрибута aria-valuenow (как число).

Для всех остальных элементов формы значение сопоставляется с использованием того же алгоритма, что и toHaveFormValues.

html

<input type="text" value="text" data-testid="input-text" />
<input type="number" value="5" data-testid="input-number" />
<input type="text" data-testid="input-empty" />
<select multiple data-testid="select-number">
  <option value="first">First Value</option>
  <option value="second" selected>Second Value</option>
  <option value="third" selected>Third Value</option>
</select>

const textInput = getByTestId('input-text');
const numberInput = getByTestId('input-number');
const emptyInput = getByTestId('input-empty');
const selectInput = getByTestId('select-number');

await expect.element(textInput).toHaveValue('text');
await expect.element(numberInput).toHaveValue(5);
await expect.element(emptyInput).not.toHaveValue();
await expect.element(selectInput).toHaveValue(['second', 'third']);

toHaveDisplayValue

typescript

function toHaveDisplayValue(
  value: string | RegExp | (string | RegExp)[]
): Promise<void>;

Это позволяет вам проверить, содержит ли данный элемент формы указанное отображаемое значение (которое отображается конечному пользователю). Он принимает элементы <input>, <select> и <textarea>, за исключением <input type="checkbox"> и <input type="radio">, которые могут быть корректно сопоставлены только с помощью toBeChecked или toHaveFormValues.

html

<label for="input-example">First name</label>
<input type="text" id="input-example" value="Luca" />

<label for="textarea-example">Description</label>
<textarea id="textarea-example">An example description here.</textarea>

<label for="single-select-example">Fruit</label>
<select id="single-select-example">
  <option value="">Select a fruit...</option>
  <option value="banana">Banana</option>
  <option value="ananas">Ananas</option>
  <option value="avocado">Avocado</option>
</select>

<label for="multiple-select-example">Fruits</label>
<select id="multiple-select-example" multiple>
  <option value="">Select a fruit...</option>
  <option value="banana" selected>Banana</option>
  <option value="ananas">Ananas</option>
  <option value="avocado" selected>Avocado</option>
</select>

const input = page.getByLabelText('First name');
const textarea = page.getByLabelText('Description');
const selectSingle = page.getByLabelText('Fruit');
const selectMultiple = page.getByLabelText('Fruits');

await expect.element(input).toHaveDisplayValue('Luca');
await expect.element(input).toHaveDisplayValue(/Luc/);
await expect
  .element(textarea)
  .toHaveDisplayValue('An example description here.');
await expect.element(textarea).toHaveDisplayValue(/example/);
await expect.element(selectSingle).toHaveDisplayValue('Select a fruit...');
await expect.element(selectSingle).toHaveDisplayValue(/Select/);
await expect.element(selectMultiple).toHaveDisplayValue([/Avocado/, 'Banana']);

toBeChecked

function toBeChecked(): Promise<void>;

Это позволяет вам проверить, отмечен ли данный элемент. Он принимает input типа checkbox или radio, а также элементы с role checkbox, radio или switch, имеющие действительный атрибут aria-checked со значением "true" или "false".

html

<input type="checkbox" checked data-testid="input-checkbox-checked" />
<input type="checkbox" data-testid="input-checkbox-unchecked" />
<div role="checkbox" aria-checked="true" data-testid="aria-checkbox-checked" />
<div
  role="checkbox"
  aria-checked="false"
  data-testid="aria-checkbox-unchecked"
/>

<input type="radio" checked value="foo" data-testid="input-radio-checked" />
<input type="radio" value="foo" data-testid="input-radio-unchecked" />
<div role="radio" aria-checked="true" data-testid="aria-radio-checked" />
<div role="radio" aria-checked="false" data-testid="aria-radio-unchecked" />
<div role="switch" aria-checked="true" data-testid="aria-switch-checked" />
<div role="switch" aria-checked="false" data-testid="aria-switch-unchecked" />

const inputCheckboxChecked = getByTestId('input-checkbox-checked');
const inputCheckboxUnchecked = getByTestId('input-checkbox-unchecked');
const ariaCheckboxChecked = getByTestId('aria-checkbox-checked');
const ariaCheckboxUnchecked = getByTestId('aria-checkbox-unchecked');
await expect.element(inputCheckboxChecked).toBeChecked();
await expect.element(inputCheckboxUnchecked).not.toBeChecked();
await expect.element(ariaCheckboxChecked).toBeChecked();
await expect.element(ariaCheckboxUnchecked).not.toBeChecked();

const inputRadioChecked = getByTestId('input-radio-checked');
const inputRadioUnchecked = getByTestId('input-radio-unchecked');
const ariaRadioChecked = getByTestId('aria-radio-checked');
const ariaRadioUnchecked = getByTestId('aria-radio-unchecked');
await expect.element(inputRadioChecked).toBeChecked();
await expect.element(inputRadioUnchecked).not.toBeChecked();
await expect.element(ariaRadioChecked).toBeChecked();
await expect.element(ariaRadioUnchecked).not.toBeChecked();

const ariaSwitchChecked = getByTestId('aria-switch-checked');
const ariaSwitchUnchecked = getByTestId('aria-switch-unchecked');
await expect.element(ariaSwitchChecked).toBeChecked();
await expect.element(ariaSwitchUnchecked).not.toBeChecked();

toBePartiallyChecked

typescript

function toBePartiallyChecked(): Promise<void>;

Это позволяет вам проверить, частично ли отмечен данный элемент. Он принимает input типа checkbox и элементы с role checkbox, имеющие aria-checked="mixed", или input типа checkbox с indeterminate, установленным в true.

html

<input type="checkbox" aria-checked="mixed" data-testid="aria-checkbox-mixed" />
<input type="checkbox" checked data-testid="input-checkbox-checked" />
<input type="checkbox" data-testid="input-checkbox-unchecked" />
<div role="checkbox" aria-checked="true" data-testid="aria-checkbox-checked" />
<div
  role="checkbox"
  aria-checked="false"
  data-testid="aria-checkbox-unchecked"
/>
<input type="checkbox" data-testid="input-checkbox-indeterminate" />

const ariaCheckboxMixed = getByTestId('aria-checkbox-mixed');
const inputCheckboxChecked = getByTestId('input-checkbox-checked');
const inputCheckboxUnchecked = getByTestId('input-checkbox-unchecked');
const ariaCheckboxChecked = getByTestId('aria-checkbox-checked');
const ariaCheckboxUnchecked = getByTestId('aria-checkbox-unchecked');
const inputCheckboxIndeterminate = getByTestId('input-checkbox-indeterminate');

await expect.element(ariaCheckboxMixed).toBePartiallyChecked();
await expect.element(inputCheckboxChecked).not.toBePartiallyChecked();
await expect.element(inputCheckboxUnchecked).not.toBePartiallyChecked();
await expect.element(ariaCheckboxChecked).not.toBePartiallyChecked();
await expect.element(ariaCheckboxUnchecked).not.toBePartiallyChecked();

inputCheckboxIndeterminate.element().indeterminate = true;
await expect.element(inputCheckboxIndeterminate).toBePartiallyChecked();

toHaveRole

function toHaveRole(role: ARIARole): Promise<void>;

Это позволяет вам утверждать, что элемент имеет ожидаемую роль.

Это полезно в случаях, когда у вас уже есть доступ к элементу с помощью запроса, отличного от самой роли, и вы хотите выполнить дополнительные утверждения относительно его доступности.

Роль может соответствовать либо явной роли (через атрибут role), либо неявной через неявную семантику ARIA.

html

<button data-testid="button">Continue</button>
<div role="button" data-testid="button-explicit">Continue</button>
<button role="switch button" data-testid="button-explicit-multiple">Continue</button>
<a href="/about" data-testid="link">About</a>
<a data-testid="link-invalid">Invalid link<a/>

await expect.element(getByTestId('button')).toHaveRole('button');
await expect.element(getByTestId('button-explicit')).toHaveRole('button');
await expect
  .element(getByTestId('button-explicit-multiple'))
  .toHaveRole('button');
await expect
  .element(getByTestId('button-explicit-multiple'))
  .toHaveRole('switch');
await expect.element(getByTestId('link')).toHaveRole('link');
await expect.element(getByTestId('link-invalid')).not.toHaveRole('link');
await expect.element(getByTestId('link-invalid')).toHaveRole('generic');

WARNING

Роли сопоставляются буквально путем сравнения строк, без наследования от иерархии ролей ARIA. В результате запрос по роли суперкласса, такой как checkbox, не будет включать элементы с ролью подкласса, такой как switch.

Также обратите внимание, что в отличие от testing-library, Vitest игнорирует все пользовательские роли, за исключением первой допустимой, в соответствии с поведением Playwright:

jsx

<div data-testid="switch" role="switch alert"></div>;

await expect.element(getByTestId('switch')).toHaveRole('switch'); // ✅
await expect.element(getByTestId('switch')).toHaveRole('alert'); // ❌

toHaveSelection

function toHaveSelection(selection?: string): Promise<void>;

Это позволяет проверить, что элемент имеет текстовое выделение.

Это полезно для проверки того, выделен ли текст или его часть в элементе. Элемент может быть либо текстовым полем ввода, либо текстовой областью, либо любым другим элементом, содержащим текст, таким как абзац, span, div и т. д.

WARNING

Ожидаемое выделение — это строка, и оно не позволяет проверять индексы диапазона выделения.

html

<div>
  <input type="text" value="text selected text" data-testid="text" />
  <textarea data-testid="textarea">text selected text</textarea>
  <p data-testid="prev">prev</p>
  <p data-testid="parent">
    text <span data-testid="child">selected</span> text
  </p>
  <p data-testid="next">next</p>
</div>

getByTestId('text').element().setSelectionRange(5, 13);
await expect.element(getByTestId('text')).toHaveSelection('selected');

getByTestId('textarea').element().setSelectionRange(0, 5);
await expect.element('textarea').toHaveSelection('text ');

const selection = document.getSelection();
const range = document.createRange();
selection.removeAllRanges();
selection.empty();
selection.addRange(range);

// выделение дочернего элемента распространяется также и на родительский
range.selectNodeContents(getByTestId('child').element());
await expect.element(getByTestId('child')).toHaveSelection('selected');
await expect.element(getByTestId('parent')).toHaveSelection('selected');

// выделение, которое охватывает весь элемент prev, часть родительского текста перед дочерним элементом и часть дочернего элемента.
range.setStart(getByTestId('prev').element(), 0);
range.setEnd(getByTestId('child').element().childNodes[0], 3);
await expect.element(queryByTestId('prev')).toHaveSelection('prev');
await expect.element(queryByTestId('child')).toHaveSelection('sel');
await expect.element(queryByTestId('parent')).toHaveSelection('text sel');
await expect.element(queryByTestId('next')).not.toHaveSelection();

// выделение, которое охватывает часть дочернего элемента, родительский текст после дочернего элемента и часть следующего элемента.
range.setStart(getByTestId('child').element().childNodes[0], 3);
range.setEnd(getByTestId('next').element().childNodes[0], 2);
await expect.element(queryByTestId('child')).toHaveSelection('ected');
await expect.element(queryByTestId('parent')).toHaveSelection('ected text');
await expect.element(queryByTestId('prev')).not.toHaveSelection();
await expect.element(queryByTestId('next')).toHaveSelection('ne');

Assertion API ​

toBeDisabled ​

toBeEnabled ​

toBeEmptyDOMElement ​

toBeInTheDocument ​

toBeInvalid ​

toBeRequired ​

toBeValid ​

toBeVisible ​

toContainElement ​

toContainHTML ​

toHaveAccessibleDescription ​

toHaveAccessibleErrorMessage ​

toHaveAccessibleName ​

toHaveAttribute ​

toHaveClass ​

toHaveFocus ​

toHaveFormValues ​

toHaveStyle ​

toHaveTextContent ​

toHaveValue ​

toHaveDisplayValue ​

toBeChecked ​

toBePartiallyChecked ​

toHaveRole ​

toHaveSelection ​

Assertion API

toBeDisabled

toBeEnabled

toBeEmptyDOMElement

toBeInTheDocument

toBeInvalid

toBeRequired

toBeValid

toBeVisible

toContainElement

toContainHTML

toHaveAccessibleDescription

toHaveAccessibleErrorMessage

toHaveAccessibleName

toHaveAttribute

toHaveClass

toHaveFocus

toHaveFormValues

toHaveStyle

toHaveTextContent

toHaveValue

toHaveDisplayValue

toBeChecked

toBePartiallyChecked

toHaveRole

toHaveSelection