diff --git a/docs/guide/browser/assertion-api.md b/docs/guide/browser/assertion-api.md
index 2126fe110e22..090d8b31f3d2 100644
--- a/docs/guide/browser/assertion-api.md
+++ b/docs/guide/browser/assertion-api.md
@@ -4,45 +4,13 @@ title: Assertion API | Browser Mode
# Assertion API
-Vitest bundles the [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) library to provide a wide range of DOM assertions out of the box. For detailed documentation, you can read the `jest-dom` readme:
-
-- [`toBeDisabled`](https://github.com/testing-library/jest-dom#toBeDisabled)
-- [`toBeEnabled`](https://github.com/testing-library/jest-dom#toBeEnabled)
-- [`toBeEmptyDOMElement`](https://github.com/testing-library/jest-dom#toBeEmptyDOMElement)
-- [`toBeInTheDocument`](https://github.com/testing-library/jest-dom#toBeInTheDocument)
-- [`toBeInvalid`](https://github.com/testing-library/jest-dom#toBeInvalid)
-- [`toBeRequired`](https://github.com/testing-library/jest-dom#toBeRequired)
-- [`toBeValid`](https://github.com/testing-library/jest-dom#toBeValid)
-- [`toBeVisible`](https://github.com/testing-library/jest-dom#toBeVisible)
-- [`toContainElement`](https://github.com/testing-library/jest-dom#toContainElement)
-- [`toContainHTML`](https://github.com/testing-library/jest-dom#toContainHTML)
-- [`toHaveAccessibleDescription`](https://github.com/testing-library/jest-dom#toHaveAccessibleDescription)
-- [`toHaveAccessibleErrorMessage`](https://github.com/testing-library/jest-dom#toHaveAccessibleErrorMessage)
-- [`toHaveAccessibleName`](https://github.com/testing-library/jest-dom#toHaveAccessibleName)
-- [`toHaveAttribute`](https://github.com/testing-library/jest-dom#toHaveAttribute)
-- [`toHaveClass`](https://github.com/testing-library/jest-dom#toHaveClass)
-- [`toHaveFocus`](https://github.com/testing-library/jest-dom#toHaveFocus)
-- [`toHaveFormValues`](https://github.com/testing-library/jest-dom#toHaveFormValues)
-- [`toHaveStyle`](https://github.com/testing-library/jest-dom#toHaveStyle)
-- [`toHaveTextContent`](https://github.com/testing-library/jest-dom#toHaveTextContent)
-- [`toHaveValue`](https://github.com/testing-library/jest-dom#toHaveValue)
-- [`toHaveDisplayValue`](https://github.com/testing-library/jest-dom#toHaveDisplayValue)
-- [`toBeChecked`](https://github.com/testing-library/jest-dom#toBeChecked)
-- [`toBePartiallyChecked`](https://github.com/testing-library/jest-dom#toBePartiallyChecked)
-- [`toHaveRole`](https://github.com/testing-library/jest-dom#toHaveRole)
-- [`toHaveErrorMessage`](https://github.com/testing-library/jest-dom#toHaveErrorMessage)
-
-If you are using [TypeScript](/guide/browser/#typescript) or want to have correct type hints in `expect`, make sure you have either `@vitest/browser/providers/playwright` or `@vitest/browser/providers/webdriverio` referenced in your [setup file](/config/#setupfile) or a [config file](/config/) depending on the provider you use. If you use the default `preview` provider, you can specify `@vitest/browser/matchers` instead.
-
-::: code-group
-```ts [preview]
-///
-```
-```ts [playwright]
-///
-```
-```ts [webdriverio]
-///
+Vitest provides a wide range of DOM assertions out of the box forked from [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) library with the added support for locators and built-in retry-ability.
+
+::: tip TypeScript Support
+If you are using [TypeScript](/guide/browser/#typescript) or want to have correct type hints in `expect`, make sure you have `@vitest/browser/context` referenced somewhere. If you never imported from there, you can add a `reference` comment in any file that's covered by your `tsconfig.json`:
+
+```ts
+///
```
:::
@@ -55,25 +23,1026 @@ import { page } from '@vitest/browser/context'
test('error banner is rendered', async () => {
triggerError()
- // @testing-library provides queries with built-in retry-ability
- // It will try to find the banner until it's rendered
+ // This creates a locator that will try to find the element
+ // when any of its methods are called.
+ // This call by itself doesn't check the existence of the element.
const banner = page.getByRole('alert', {
name: /error/i,
})
// Vitest provides `expect.element` with built-in retry-ability
- // It will check `element.textContent` until it's equal to "Error!"
+ // It will repeatedly check that the element exists in the DOM and that
+ // the content of `element.textContent` is equal to "Error!"
+ // until all the conditions are met
await expect.element(banner).toHaveTextContent('Error!')
})
```
+We recommend to always use `expect.element` when working with `page.getBy*` locators to reduce test flakiness. Note that `expect.element` accepts a second option:
+
+```ts
+interface ExpectPollOptions {
+ // The interval to retry the assertion for in milliseconds
+ // Defaults to "expect.poll.interval" config option
+ interval?: number
+ // Time to retry the assertion for in milliseconds
+ // Defaults to "expect.poll.timeout" config option
+ timeout?: number
+ // The message printed when the assertion fails
+ message?: string
+}
+```
+
::: tip
`expect.element` is a shorthand for `expect.poll(() => element)` and works in exactly the same way.
-`toHaveTextContent` and all other [`@testing-library/jest-dom`](https://github.com/testing-library/jest-dom) assertions are still available on a regular `expect` without a built-in retry-ability mechanism:
+`toHaveTextContent` and all other assertions are still available on a regular `expect` without a built-in retry-ability mechanism:
```ts
// will fail immediately if .textContent is not `'Error!'`
expect(banner).toHaveTextContent('Error!')
```
:::
+
+## toBeDisabled
+
+```ts
+function toBeDisabled(): Promise
+```
+
+Allows you to check whether an element is disabled from the user's perspective.
+
+Matches if the element is a form control and the `disabled` attribute is specified on this element or the
+element is a descendant of a form element with a `disabled` attribute.
+
+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, unless it's a custom element.
+
+```html
+
+```
+
+```ts
+await expect.element(getByTestId('button')).toBeDisabled() // ✅
+await expect.element(getByTestId('button')).not.toBeDisabled() // ❌
+```
+
+## toBeEnabled
+
+```ts
+function toBeEnabled(): Promise
+```
+
+Allows you to check whether an element is not disabled from the user's perspective.
+
+Works like [`not.toBeDisabled()`](#tobedisabled). Use this matcher to avoid double negation in your tests.
+
+```html
+
+```
+
+```ts
+await expect.element(getByTestId('button')).toBeEnabled() // ✅
+await expect.element(getByTestId('button')).not.toBeEnabled() // ❌
+```
+
+## toBeEmptyDOMElement
+
+```ts
+function toBeEmptyDOMElement(): Promise
+```
+
+This allows you to assert whether an element has no visible content for the user. It ignores comments but will fail if the element contains white-space.
+
+```html
+
+
+
+```
+
+```ts
+await expect.element(getByTestId('empty')).toBeEmptyDOMElement()
+await expect.element(getByTestId('not-empty')).not.toBeEmptyDOMElement()
+await expect.element(
+ getByTestId('with-whitespace')
+).not.toBeEmptyDOMElement()
+```
+
+## toBeInTheDocument
+
+```ts
+function toBeInTheDocument(): Promise
+```
+
+Assert whether an element is present in the document or not.
+
+```html
+
+```
+
+```ts
+await expect.element(getByTestId('svg-element')).toBeInTheDocument()
+await expect.element(getByTestId('does-not-exist')).not.toBeInTheDocument()
+```
+
+::: warning
+This matcher does not find detached elements. The element must be added to the document to be found by `toBeInTheDocument`. If you desire to search in a detached element, please use: [`toContainElement`](#tocontainelement).
+:::
+
+## toBeInvalid
+
+```ts
+function toBeInvalid(): Promise
+```
+
+This allows you to check if an element, is currently invalid.
+
+An element is invalid if it has an [`aria-invalid` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) with no value or a value of `"true"`, or if the result of [`checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation) is `false`.
+
+```html
+
+
+
+
+
+
+
+
+```
+
+```ts
+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
+
+```ts
+function toBeRequired(): Promise
+```
+
+This allows you to check if a form element is currently required.
+
+An element is required if it is having a `required` or `aria-required="true"` attribute.
+
+```html
+
+
+
+
+
+
+
+
+
+
+```
+
+```ts
+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
+
+```ts
+function toBeValid(): Promise
+```
+
+This allows you to check if the value of an element, is currently valid.
+
+An element is valid if it has no [`aria-invalid` attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) or an attribute value of "false". The result of [`checkValidity()`](https://developer.mozilla.org/en-US/docs/Web/HTML/Constraint_validation) must also be `true` if it's a form element.
+
+```html
+
+
+
+
+
+
+
+
+```
+
+```ts
+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
+
+```ts
+function toBeVisible(): Promise
+```
+
+This allows you to check if an element is currently visible to the user.
+
+Element is considered visible when it has non-empty bounding box and does not have `visibility:hidden` computed style.
+
+Note that according to this definition:
+
+- Elements of zero size **are not** considered visible.
+- Elements with `display:none` **are not** considered visible.
+- Elements with `opacity:0` **are** considered visible.
+
+To check that at least one element from the list is visible, use `locator.first()`.
+
+```ts
+// A specific element is visible.
+await expect.element(page.getByText('Welcome')).toBeVisible()
+
+// At least one item in the list is visible.
+await expect.element(page.getByTestId('todo-item').first()).toBeVisible()
+
+// At least one of the two elements is visible, possibly both.
+await expect.element(
+ page.getByRole('button', { name: 'Sign in' })
+ .or(page.getByRole('button', { name: 'Sign up' }))
+ .first()
+).toBeVisible()
+```
+
+## toContainElement
+
+```ts
+function toContainElement(element: HTMLElement | SVGElement | null): Promise
+```
+
+This allows you to assert whether an element contains another element as a descendant or not.
+
+```html
+
+```
+
+```ts
+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
+
+```ts
+function toContainHTML(htmlText: string): Promise
+```
+
+Assert whether a string representing a HTML element is contained in another element. The string should contain valid html, and not any incomplete html.
+
+```html
+
+```
+
+```ts
+// These are valid usages
+await expect.element(getByTestId('parent')).toContainHTML('')
+await expect.element(getByTestId('parent')).toContainHTML('')
+await expect.element(getByTestId('parent')).not.toContainHTML(' ')
+
+// These won't work
+await expect.element(getByTestId('parent')).toContainHTML('data-testid="child"')
+await expect.element(getByTestId('parent')).toContainHTML('data-testid')
+await expect.element(getByTestId('parent')).toContainHTML('')
+```
+
+::: warning
+Chances are you probably do not need to use this matcher. We encourage testing from the perspective of how the user perceives the app in a browser. That's why testing against a specific DOM structure is not advised.
+
+It could be useful in situations where the code being tested renders html that was obtained from an external source, and you want to validate that that html code was used as intended.
+
+It should not be used to check DOM structure that you control. Please, use [`toContainElement`](#tocontainelement) instead.
+:::
+
+## toHaveAccessibleDescription
+
+```ts
+function toHaveAccessibleDescription(description?: string | RegExp): Promise
+```
+
+This allows you to assert that an element has the expected
+[accessible description](https://w3c.github.io/accname/).
+
+You can pass the exact string of the expected accessible description, or you can
+make a partial match passing a regular expression, or by using
+[`expect.stringContaining`](/api/expect#expect-stringcontaining) or [`expect.stringMatching`](/api/expect#expect-stringmatching).
+
+```html
+Start
+About
+
+
+The logo of Our Company
+
+```
+
+```ts
+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
+
+```ts
+function toHaveAccessibleErrorMessage(message?: string | RegExp): Promise
+```
+
+This allows you to assert that an element has the expected
+[accessible error message](https://w3c.github.io/aria/#aria-errormessage).
+
+You can pass the exact string of the expected accessible error message.
+Alternatively, you can perform a partial match by passing a regular expression
+or by using
+[`expect.stringContaining`](/api/expect#expect-stringcontaining) or [`expect.stringMatching`](/api/expect#expect-stringmatching).
+
+```html
+
+
This field is invalid
+
+
+
+```
+
+```ts
+// Inputs with Valid Error Messages
+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!')
+
+// Inputs without Valid Error Messages
+await expect.element(
+ getByRole('textbox', { name: 'No Error Attributes' }),
+).not.toHaveAccessibleErrorMessage()
+
+await expect.element(
+ getByRole('textbox', { name: 'Not Invalid' }),
+).not.toHaveAccessibleErrorMessage()
+```
+
+## toHaveAccessibleName
+
+```ts
+function toHaveAccessibleName(name?: string | RegExp): Promise
+```
+
+This allows you to assert that an element has the expected
+[accessible name](https://w3c.github.io/accname/). It is useful, for instance,
+to assert that form elements and buttons are properly labelled.
+
+You can pass the exact string of the expected accessible name, or you can make a
+partial match passing a regular expression, or by using
+[`expect.stringContaining`](/api/expect#expect-stringcontaining) or [`expect.stringMatching`](/api/expect#expect-stringmatching).
+
+```html
+
+
+
+
+
Test content
+
+
+
+```
+
+```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
+
+```ts
+function toHaveAttribute(attribute: string, value?: unknown): Promise
+```
+
+This allows you to check whether the given element has an attribute or not. You
+can also optionally check that the attribute has a specific expected value or
+partial match using [`expect.stringContaining`](/api/expect#expect-stringcontaining) or [`expect.stringMatching`](/api/expect#expect-stringmatching).
+
+```html
+
+```
+
+```ts
+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
+
+```ts
+function toHaveClass(...classNames: string[], options?: { exact: boolean }): Promise
+function toHaveClass(...classNames: (string | RegExp)[]): Promise
+```
+
+This allows you to check whether the given element has certain classes within
+its `class` attribute. You must provide at least one class, unless you are
+asserting that an element does not have any classes.
+
+The list of class names may include strings and regular expressions. Regular
+expressions are matched against each individual class in the target element, and
+it is NOT matched against its full `class` attribute value as whole.
+
+::: warning
+Note that you cannot use `exact: true` option when only regular expressions are provided.
+:::
+
+```html
+
+
+```
+
+```ts
+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/)
+
+// ⚠️ regexp matches against individual classes, not the whole classList
+await expect.element(deleteButton).not.toHaveClass(/btn extra/)
+
+// the element has EXACTLY a set of classes (in any order)
+await expect.element(deleteButton).toHaveClass('btn-danger extra btn', {
+ exact: true
+})
+// if it has more than expected it is going to fail
+await expect.element(deleteButton).not.toHaveClass('btn-danger extra', {
+ exact: true
+})
+
+await expect.element(noClasses).not.toHaveClass()
+```
+
+## toHaveFocus
+
+```ts
+function toHaveFocus(): Promise
+```
+
+This allows you to assert whether an element has focus or not.
+
+```html
+
+```
+
+```ts
+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
+
+```ts
+function toHaveFormValues(expectedValues: Record): Promise
+```
+
+This allows you to check if a form or fieldset contains form controls for each given name, and having the specified value.
+
+::: tip
+It is important to stress that this matcher can only be invoked on a [form](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement) or a [fieldset](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFieldSetElement) element.
+
+This allows it to take advantage of the [`.elements`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements) property in `form` and `fieldset` to reliably fetch all form controls within them.
+
+This also avoids the possibility that users provide a container that contains more than one `form`, thereby intermixing form controls that are not related, and could even conflict with one another.
+:::
+
+This matcher abstracts away the particularities with which a form control value
+is obtained depending on the type of form control. For instance, ``
+elements have a `value` attribute, but `