Assertion API

Vitest bietet eine breite Palette von DOM-Assertions, die auf der @testing-library/jest-dom-Bibliothek basieren. Diese wurden um zusätzliche Unterstützung für Locators und eine integrierte Wiederholungsfunktion erweitert.

TypeScript-Unterstützung

Wenn Sie TypeScript verwenden oder korrekte Typinformationen für expect wünschen, stellen Sie sicher, dass @vitest/browser/context irgendwo referenziert wird. Falls Sie noch nie von dort importiert haben, können Sie einen reference-Kommentar in jeder Datei hinzufügen, die von Ihrer tsconfig.json abgedeckt wird:

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

Tests im Browser können aufgrund ihrer asynchronen Natur unzuverlässig fehlschlagen. Daher ist es entscheidend, dass Assertions auch unter verzögerten Bedingungen (z. B. durch ein Timeout, eine Netzwerkanfrage oder eine Animation) erfolgreich sind. Zu diesem Zweck bietet Vitest standardmäßig wiederholbare Assertions über die APIs expect.poll und expect.element:

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

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

  // Dies erstellt einen Locator, der versucht, das Element zu ermitteln, sobald eine seiner Methoden aufgerufen wird.
  // Dieser Aufruf allein prüft nicht, ob das Element existiert.
  const banner = page.getByRole('alert', {
    name: /error/i,
  });

  // Vitest bietet `expect.element` mit integriertem Wiederholungsmechanismus.
  // Es wird wiederholt überprüfen, ob das Element im DOM existiert und ob der Inhalt von `element.textContent` gleich "Error!" ist, bis alle Bedingungen erfüllt sind.
  await expect.element(banner).toHaveTextContent('Error!');
});

Wir empfehlen, expect.element immer dann zu verwenden, wenn Sie mit page.getBy*-Locators arbeiten, um die Testinstabilität zu reduzieren. Beachten Sie: expect.element akzeptiert eine zweite Option:

interface ExpectPollOptions {
  // Das Wiederholungsintervall für die Assertion in Millisekunden.
  // Standard: Konfigurationsoption "expect.poll.interval".
  interval?: number;
  // Die maximale Wartezeit für die Assertion in Millisekunden.
  // Standard: Konfigurationsoption "expect.poll.timeout".
  timeout?: number;
  // Die Meldung, die angezeigt wird, wenn die Assertion fehlschlägt.
  message?: string;
}

TIP

expect.element ist eine Kurzform für expect.poll(() => element) und funktioniert genau auf die gleiche Weise.

toHaveTextContent und alle anderen Assertions sind weiterhin auf einem regulären expect ohne integrierten Wiederholungsmechanismus verfügbar:

// schlägt sofort fehl, wenn .textContent nicht `'Error!'` ist
expect(banner).toHaveTextContent('Error!');

toBeDisabled

function toBeDisabled(): Promise<void>;

Dieser Matcher prüft, ob ein Element für den Benutzer deaktiviert ist.

Er passt, wenn das Element ein Formularsteuerelement ist und das disabled-Attribut an diesem Element gesetzt ist oder das Element ein Nachkomme eines Formularelements mit einem disabled-Attribut ist.

Beachten Sie, dass nur native Steuerelemente wie HTML button, input, select, textarea, option, optgroup durch das "disabled"-Attribut deaktiviert werden können. Das "disabled"-Attribut bei anderen Elementen wird ignoriert, es sei denn, es handelt sich um ein benutzerdefiniertes Element.

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

Dieser Matcher prüft, ob ein Element für den Benutzer nicht deaktiviert ist.

Er funktioniert wie not.toBeDisabled(). Verwenden Sie diesen Matcher, um doppelte Negationen in Ihren Tests zu vermeiden.

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

Dieser Matcher bestätigt, dass ein Element für den Benutzer keinen sichtbaren Inhalt hat. Er ignoriert Kommentare, schlägt aber fehl, wenn das Element Leerraumzeichen enthält.

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

Dieser Matcher bestätigt, ob ein Element im Dokument vorhanden ist oder nicht.

html

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

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

WARNING

Dieser Matcher findet keine vom DOM getrennten Elemente. Das Element muss dem Dokument hinzugefügt werden, um von toBeInTheDocument gefunden zu werden. Wenn Sie in einem vom DOM getrennten Element suchen möchten, verwenden Sie bitte: toContainElement.

toBeInvalid

function toBeInvalid(): Promise<void>;

Dieser Matcher prüft, ob ein Element derzeit ungültig ist.

Ein Element ist ungültig, wenn es ein aria-invalid-Attribut ohne oder mit dem Wert "true" hat, oder wenn das Ergebnis von checkValidity() false ist.

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

Dieser Matcher prüft, ob ein Formularelement aktuell erforderlich ist.

Ein Element ist erforderlich, wenn es ein required- oder aria-required="true"-Attribut besitzt.

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

Dieser Matcher prüft, ob der Wert eines Elements aktuell gültig ist.

Ein Element ist gültig, wenn es kein aria-invalid-Attribut oder einen Attributwert von "false" hat. Das Ergebnis von checkValidity() muss ebenfalls true sein, wenn es sich um ein Formularelement handelt.

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

Dieser Matcher prüft, ob ein Element für den Benutzer sichtbar ist.

Ein Element gilt als sichtbar, wenn es eine nicht leere Bounding Box besitzt und keinen berechneten Stil visibility:hidden aufweist.

Beachten Sie, dass gemäß dieser Definition:

Elemente mit der Größe Null gelten nicht als sichtbar.
Elemente mit display:none gelten nicht als sichtbar.
Elemente mit opacity:0 gelten als sichtbar.

Um zu überprüfen, ob mindestens ein Element aus der Liste sichtbar ist, verwenden Sie locator.first().

// Ein bestimmtes Element ist sichtbar.
await expect.element(page.getByText('Welcome')).toBeVisible();

// Mindestens ein Element in der Liste ist sichtbar.
await expect.element(page.getByTestId('todo-item').first()).toBeVisible();

// Mindestens eines der beiden Elemente ist sichtbar, möglicherweise beide.
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>;

Dieser Matcher bestätigt, dass ein Element ein anderes Element als Nachkommen enthält oder nicht.

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

Dieser Matcher bestätigt, ob eine Zeichenkette, die ein HTML-Element darstellt, in einem anderen Element enthalten ist. Die Zeichenkette sollte gültiges HTML enthalten und darf kein unvollständiges HTML sein.

html

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

// Dies sind gültige Verwendungen
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 />');

// Diese funktionieren nicht
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

Vermutlich benötigen Sie diesen Matcher nicht. Wir empfehlen, Tests aus der Benutzerperspektive zu schreiben, wie die App im Browser wahrgenommen wird. Daher ist das Testen gegen eine spezifische DOM-Struktur nicht ratsam.

Es könnte in Situationen nützlich sein, in denen der getestete Code HTML rendert, das aus einer externen Quelle stammt, und Sie überprüfen möchten, ob der HTML-Code wie beabsichtigt verwendet wurde.

Es sollte nicht verwendet werden, um die DOM-Struktur zu überprüfen, die Sie kontrollieren. Bitte verwenden Sie stattdessen toContainElement.

toHaveAccessibleDescription

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

Dieser Matcher bestätigt, dass ein Element die erwartete zugängliche Beschreibung hat.

Sie können die genaue Zeichenkette der erwarteten zugänglichen Beschreibung übergeben oder eine teilweise Übereinstimmung mit einem regulären Ausdruck oder durch Verwendung von expect.stringContaining oder expect.stringMatching vornehmen.

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

Dieser Matcher bestätigt, dass ein Element die erwartete zugängliche Fehlermeldung hat.

Sie können die genaue Zeichenkette der erwarteten zugänglichen Fehlermeldung übergeben. Alternativ können Sie eine teilweise Übereinstimmung mit einem regulären Ausdruck oder durch Verwendung von expect.stringContaining oder expect.stringMatching vornehmen.

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"
/>

// Eingaben mit gültigen Fehlermeldungen
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!');

// Eingaben ohne gültige Fehlermeldungen
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>;

Dieser Matcher bestätigt, dass ein Element den erwarteten zugänglichen Namen hat. Dies ist beispielsweise nützlich, um zu bestätigen, dass Formularelemente und Schaltflächen richtig beschriftet sind.

Sie können die genaue Zeichenkette des erwarteten zugänglichen Namens übergeben oder eine teilweise Übereinstimmung mit einem regulären Ausdruck oder durch Verwendung von expect.stringContaining oder expect.stringMatching vornehmen.

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

Dieser Matcher bestätigt, ob das gegebene Element ein Attribut hat. Sie können auch optional überprüfen, ob das Attribut einen bestimmten erwarteten Wert hat oder teilweise mit expect.stringContaining oder expect.stringMatching übereinstimmt.

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

Dieser Matcher bestätigt, dass das gegebene Element bestimmte Klassen in seinem class-Attribut hat. Sie müssen mindestens eine Klasse angeben, es sei denn, Sie bestätigen, dass ein Element keine Klassen hat.

Die Liste der Klassennamen kann Zeichenketten und reguläre Ausdrücke enthalten. Reguläre Ausdrücke werden gegen jede einzelne Klasse im Zielelement abgeglichen und NICHT gegen den gesamten Wert des class-Attributs als Ganzes.

WARNING

Beachten Sie, dass Sie die Option exact: true nicht verwenden können, wenn nur reguläre Ausdrücke verwendet werden.

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

// ⚠️ Regulärer Ausdruck gleicht einzelne Klassen ab, nicht die gesamte ClassList
await expect.element(deleteButton).not.toHaveClass(/btn extra/);

// Das Element hat GENAU eine Reihe von Klassen (in beliebiger Reihenfolge)
await expect.element(deleteButton).toHaveClass('btn-danger extra btn', {
  exact: true,
});
// Wenn es mehr als erwartet hat, wird es fehlschlagen
await expect.element(deleteButton).not.toHaveClass('btn-danger extra', {
  exact: true,
});

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

toHaveFocus

function toHaveFocus(): Promise<void>;

Dieser Matcher bestätigt, dass ein Element den Fokus hat.

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

Dieser Matcher bestätigt, dass ein Formular oder ein Fieldset Formularfelder für jeden angegebenen Namen enthält und den angegebenen Wert aufweist.

TIP

Es ist wichtig zu betonen, dass dieser Matcher nur für ein Formular oder ein Fieldset-Element verwendet werden kann.

Dies ermöglicht es, die elements-Eigenschaft von form und fieldset zu nutzen, um alle Formularfelder darin zuverlässig abzurufen.

Dies vermeidet auch die Möglichkeit, dass Benutzer einen Container bereitstellen, der mehr als ein form enthält, wodurch nicht miteinander in Beziehung stehende Formularfelder vermischt werden, die sich sogar gegenseitig widersprechen könnten.

Dieser Matcher abstrahiert die Besonderheiten, wie ein Formularfeldwert je nach Typ des Formularfeldes ermittelt wird. Zum Beispiel haben <input>-Elemente ein value-Attribut, aber <select>-Elemente nicht. Hier ist eine Liste aller abgedeckten Fälle:

<input type="number">-Elemente geben den Wert als Zahl zurück, anstatt einer Zeichenkette.
<input type="checkbox">-Elemente:
- Wenn nur ein einziges mit dem gegebenen name-Attribut vorhanden ist, wird es als Boolescher Wert behandelt, wobei true zurückgegeben wird, wenn das Kontrollkästchen ausgewählt ist, false, wenn es nicht ausgewählt ist.
- Wenn mehr als ein Kontrollkästchen mit demselben name-Attribut vorhanden ist, werden sie alle zusammen als ein einziges Formularfeld behandelt, das den Wert als Array zurückgibt, das alle Werte der ausgewählten Kontrollkästchen in der Sammlung enthält.
<input type="radio">-Elemente werden alle nach dem name-Attribut gruppiert, und eine solche Gruppe wird als ein einziges Formularfeld behandelt. Dieses Formularfeld gibt den Wert als Zeichenkette zurück, die dem value-Attribut des ausgewählten Optionsfeldes innerhalb der Gruppe entspricht.
<input type="text">-Elemente geben den Wert als Zeichenkette zurück. Dies gilt auch für <input>-Elemente, die jedes andere mögliche type-Attribut besitzen, das nicht explizit in anderen Regeln oben abgedeckt ist (z. B. search, email, date, password, hidden usw.).
<select>-Elemente ohne das multiple-Attribut geben den Wert als Zeichenkette zurück, die dem value-Attribut der ausgewählten option entspricht, oder undefined, wenn keine Option ausgewählt wurde.
<select multiple>-Elemente geben den Wert als ein Array zurück, das alle Werte der ausgewählten Optionen enthält.
<textarea>-Elemente geben ihren Wert als Zeichenkette zurück. Der Wert entspricht ihrem Knoteninhalt.

Die oben genannten Regeln vereinfachen es beispielsweise, von der Verwendung eines einzelnen Auswahlfeldes zu einer Gruppe von Optionsfeldern zu wechseln. Oder von einem Mehrfachauswahlfeld zu einer Gruppe von Kontrollkästchen zu wechseln. Der resultierende Satz von Formularwerten, die dieser Matcher für den Vergleich verwendet, wäre derselbe.

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

Dieser Matcher prüft, ob ein bestimmtes Element bestimmte CSS-Eigenschaften mit bestimmten Werten aufweist. Er passt nur, wenn das Element alle erwarteten Eigenschaften aufweist, nicht nur einige davon.

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',
});

Dies funktioniert auch mit Regeln, die auf das Element über einen Klassennamen angewendet werden, wobei einige Regeln in einem derzeit im Dokument aktiven Stylesheet definiert sind. Die üblichen Regeln der CSS-Rangfolge gelten.

toHaveTextContent

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

Dieser Matcher bestätigt, dass der gegebene Knoten einen Textinhalt hat. Dies gilt für Elemente, aber auch für Textknoten und Fragmente.

Wenn ein string-Argument übergeben wird, wird eine teilweise, Groß-/Kleinschreibung beachtende Übereinstimmung mit dem Knoteninhalt durchgeführt.

Um eine Groß-/Kleinschreibung ignorierende Übereinstimmung durchzuführen, können Sie einen RegExp mit dem /i-Modifikator verwenden.

Wenn Sie den gesamten Inhalt abgleichen möchten, können Sie einen RegExp dafür verwenden.

html

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

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

await expect.element(element).toHaveTextContent('Content');
// um den gesamten Inhalt abzugleichen
await expect.element(element).toHaveTextContent(/^Text Content$/);
// um eine Groß-/Kleinschreibung ignorierende Übereinstimmung zu verwenden
await expect.element(element).toHaveTextContent(/content$/i);
await expect.element(element).not.toHaveTextContent('content');

toHaveValue

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

Dieser Matcher bestätigt, dass das gegebene Formularelement den angegebenen Wert hat. Er akzeptiert <input>, <select> und <textarea>-Elemente mit Ausnahme von <input type="checkbox"> und <input type="radio">, die nur sinnvoll mit toBeChecked oder toHaveFormValues verglichen werden können.

Er akzeptiert auch Elemente mit den Rollen meter, progressbar, slider oder spinbutton und prüft deren aria-valuenow-Attribut (als Zahl).

Für alle anderen Formularelemente wird der Wert mit demselben Algorithmus abgeglichen, der in toHaveFormValues verwendet wird.

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

Dieser Matcher prüft, ob das gegebene Formularelement den angegebenen angezeigten Wert (den der Endbenutzer wahrnimmt) hat. Er akzeptiert <input>, <select> und <textarea>-Elemente mit Ausnahme von <input type="checkbox"> und <input type="radio">, die nur sinnvoll mit toBeChecked oder toHaveFormValues verglichen werden können.

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

Dieser Matcher prüft, ob das gegebene Element ausgewählt ist. Er akzeptiert ein input vom Typ checkbox oder radio und Elemente, die die Rolle checkbox, radio oder switch haben, mit einem gültigen aria-checked-Attribut von "true" oder "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>;

Dieser Matcher prüft, ob das gegebene Element teilweise ausgewählt ist. Er akzeptiert ein input vom Typ checkbox und Elemente, die die Rolle checkbox haben, mit einem aria-checked="mixed", oder input vom Typ checkbox, dessen indeterminate-Eigenschaft auf true gesetzt ist.

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

Dieser Matcher bestätigt, dass ein Element die erwartete Rolle hat.

Dies ist nützlich in Fällen, in denen Sie bereits über eine andere Abfrage als die Rolle selbst auf ein Element zugreifen und zusätzliche Überprüfungen bezüglich seiner Barrierefreiheit vornehmen möchten.

Die Rolle kann entweder einer expliziten Rolle (über das role-Attribut) oder einer impliziten Rolle über die implizite ARIA-Semantik entsprechen.

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

Rollen werden wörtlich durch exakte Zeichenkettenübereinstimmung abgeglichen, ohne von der ARIA-Rollenhierarchie zu erben. Infolgedessen schließt das Abfragen einer Oberklassenrolle wie checkbox keine Elemente mit einer Unterklassenrolle wie switch ein.

Beachten Sie auch, dass Vitest im Gegensatz zu testing-library alle benutzerdefinierten Rollen außer der ersten gültigen ignoriert, entsprechend dem Verhalten von 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>;

Dieser Matcher bestätigt, dass ein Element eine Textauswahl hat.

Dies ist nützlich, um zu überprüfen, ob Text oder Teile des Textes innerhalb eines Elements ausgewählt sind. Das Element kann entweder ein Texteingabefeld, ein Textbereich oder jedes andere Element sein, das Text enthält, wie z. B. ein Absatz, ein Span, ein Div usw.

WARNING

Die erwartete Auswahl ist eine Zeichenkette; es ermöglicht keine Überprüfung von Auswahlbereichsindizes.

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

// Die Auswahl des Kindes wirkt sich auch auf das Elternelement aus.
range.selectNodeContents(getByTestId('child').element());
await expect.element(getByTestId('child')).toHaveSelection('selected');
await expect.element(getByTestId('parent')).toHaveSelection('selected');

// Auswahl, die sich über das Element 'prev', den Text des Elternelements vor dem Kindelement und einen Teil des Kindelements erstreckt.
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();

// Auswahl, die sich über einen Teil des Kindelements, den Text des Elternelements nach dem Kindelement und einen Teil des nächsten Elements erstreckt.
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