API di Asserzione

Vitest offre un'ampia gamma di asserzioni DOM pronte all'uso, derivate dalla libreria @testing-library/jest-dom, con l'aggiunta del supporto per i localizzatori e una funzionalità di riprovo integrata.

Supporto TypeScript

Se utilizzi TypeScript o desideri suggerimenti di tipo accurati in expect, assicurati di aver referenziato @vitest/browser/context da qualche parte. Se non hai mai importato da lì, puoi aggiungere un commento reference in qualsiasi file coperto dal tuo tsconfig.json:

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

I test nel browser possono fallire in modo inconsistente a causa della loro natura asincrona. Per questo motivo, è fondamentale disporre di un meccanismo che garantisca il successo delle asserzioni, anche se la condizione è ritardata (ad esempio, da un timeout, una richiesta di rete o un'animazione). A tale scopo, Vitest fornisce asserzioni riprovabili pronte all'uso tramite le API expect.poll e expect.element:

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

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

  // Questo crea un localizzatore che cercherà l'elemento quando viene invocato uno dei suoi metodi.
  // Questa chiamata da sola non verifica l'esistenza dell'elemento.
  const banner = page.getByRole('alert', {
    name: /error/i,
  });

  // Vitest fornisce `expect.element` con la funzionalità di riprovo integrata.
  // Verificherà ripetutamente che l'elemento esista nel DOM e che il contenuto di `element.textContent` sia uguale a "Error!" fino a quando tutte le condizioni non saranno soddisfatte.
  await expect.element(banner).toHaveTextContent('Error!');
});

Si consiglia di utilizzare sempre expect.element con i localizzatori page.getBy* per ridurre l'instabilità dei test. Si noti che expect.element accetta una seconda opzione:

interface ExpectPollOptions {
  // L'intervallo in millisecondi per ritentare l'asserzione.
  // Il valore predefinito è l'opzione di configurazione "expect.poll.interval".
  interval?: number;
  // Tempo in millisecondi per ritentare l'asserzione.
  // Il valore predefinito è l'opzione di configurazione "expect.poll.timeout".
  timeout?: number;
  // Il messaggio stampato quando l'asserzione fallisce.
  message?: string;
}

TIP

expect.element è un'abbreviazione per expect.poll(() => element) e funziona esattamente allo stesso modo.

toHaveTextContent e tutte le altre asserzioni sono ancora disponibili su un normale expect senza un meccanismo di riprovo integrato:

// fallirà immediatamente se .textContent non è `'Error!'`
expect(banner).toHaveTextContent('Error!');

toBeDisabled

function toBeDisabled(): Promise<void>;

Consente di verificare se un elemento è disabilitato dal punto di vista dell'utente.

Si verifica una corrispondenza se l'elemento è un controllo di modulo e l'attributo disabled è specificato su questo elemento, oppure se l'elemento è un discendente di un elemento di modulo con un attributo disabled.

Si noti che solo gli elementi di controllo nativi come HTML button, input, select, textarea, option, optgroup possono essere disabilitati tramite l'attributo "disabled". L'attributo "disabled" su altri elementi viene ignorato, a meno che non sia un elemento personalizzato.

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

Consente di verificare se un elemento non è disabilitato dal punto di vista dell'utente.

Funziona come not.toBeDisabled(). Utilizzare questo matcher per evitare la doppia negazione nei test.

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

Questo consente di verificare se un elemento non ha contenuto visibile per l'utente. Ignora i commenti, ma fallirà se l'elemento contiene spazi bianchi.

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

Verifica se un elemento è presente nel documento.

html

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

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

WARNING

Questo matcher non trova elementi staccati. L'elemento deve essere aggiunto al documento per essere trovato da toBeInTheDocument. Se si desidera cercare in un elemento staccato, si prega di usare: toContainElement.

toBeInvalid

function toBeInvalid(): Promise<void>;

Questo consente di verificare se un elemento è attualmente invalido.

Un elemento è invalido se ha un attributo aria-invalid senza valore o con valore "true", o se il risultato di 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>;

Questo consente di verificare se un elemento del modulo è attualmente richiesto.

Un elemento è richiesto se ha un attributo required o 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>;

Questo consente di verificare se il valore di un elemento è attualmente valido.

Un elemento è valido se non ha un attributo aria-invalid o il valore dell'attributo è "false". Il risultato di checkValidity() deve anche essere true se è un elemento di un modulo.

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

Questo consente di verificare se un elemento è attualmente visibile all'utente.

Un elemento è considerato visibile quando ha un riquadro di delimitazione non vuoto e non ha lo stile calcolato visibility:hidden.

Si noti che secondo questa definizione:

Gli elementi di dimensione zero non sono considerati visibili.
Gli elementi con display:none non sono considerati visibili.
Gli elementi con opacity:0 sono considerati visibili.

Per verificare che almeno un elemento dall'elenco sia visibile, utilizzare locator.first().

// Un elemento specifico è visibile.
await expect.element(page.getByText('Welcome')).toBeVisible();

// Almeno una voce nell'elenco è visibile.
await expect.element(page.getByTestId('todo-item').first()).toBeVisible();

// Almeno uno dei due elementi è visibile, possibilmente entrambi.
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>;

Questo ti permette di asserire se un elemento contiene un altro elemento come discendente.

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

Verifica se una stringa che rappresenta un elemento HTML è contenuta in un altro elemento. La stringa dovrebbe contenere HTML valido, e non HTML incompleto.

html

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

// Questi sono usi validi
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 />');

// Questi non funzioneranno
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

È probabile che non sia necessario utilizzare questo matcher. Si incoraggia a testare dal punto di vista di come l'utente percepisce l'app in un browser. Per questo motivo, testare contro una specifica struttura DOM non è consigliato.

Potrebbe essere utile in situazioni in cui il codice testato genera HTML ottenuto da una fonte esterna, e si vuole convalidare che quel codice HTML sia stato usato come previsto.

Non dovrebbe essere utilizzato per controllare la struttura DOM che si gestisce. Si prega di utilizzare toContainElement invece.

toHaveAccessibleDescription

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

Questo ti permette di asserire che un elemento abbia la descrizione accessibile attesa.

È possibile passare la stringa esatta della descrizione accessibile attesa, oppure è possibile effettuare una corrispondenza parziale passando un'espressione regolare, o utilizzando expect.stringContaining o 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>;

Questo ti permette di asserire che un elemento abbia il messaggio di errore accessibile atteso.

È possibile passare la stringa esatta del messaggio di errore accessibile atteso. In alternativa, è possibile eseguire una corrispondenza parziale passando un'espressione regolare o utilizzando expect.stringContaining o 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"
/>

// Input con messaggi di errore validi
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!');

// Input senza messaggi di errore validi
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>;

Questo ti permette di asserire che un elemento abbia il nome accessibile atteso. È utile, ad esempio, per asserire che gli elementi del modulo e i pulsanti siano etichettati correttamente.

È possibile passare la stringa esatta del nome accessibile atteso, oppure è possibile effettuare una corrispondenza parziale passando un'espressione regolare, o utilizzando expect.stringContaining o 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>;

Questo ti permette di verificare se l'elemento dato possiede un attributo. È inoltre possibile verificare facoltativamente che l'attributo abbia un valore specifico atteso o una corrispondenza parziale utilizzando expect.stringContaining o 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>;

Questo ti permette di verificare se l'elemento dato ha determinate classi nel suo attributo class. È necessario fornire almeno una classe, a meno che non si stia asserendo che un elemento non abbia classi.

L'elenco dei nomi delle classi può includere stringhe ed espressioni regolari. Le espressioni regolari vengono confrontate con ogni singola classe nell'elemento di destinazione, e NON vengono confrontate con il valore completo dell'attributo class per intero.

WARNING

Si noti che non è possibile utilizzare l'opzione exact: true quando vengono fornite solo espressioni regolari.

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

// ⚠️ le espressioni regolari vengono confrontate con le singole classi, non con l'intera classList
await expect.element(deleteButton).not.toHaveClass(/btn extra/);

// l'elemento ha ESATTAMENTE un insieme di classi (in qualsiasi ordine)
await expect.element(deleteButton).toHaveClass('btn-danger extra btn', {
  exact: true,
});
// se ha più del previsto fallirà
await expect.element(deleteButton).not.toHaveClass('btn-danger extra', {
  exact: true,
});

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

toHaveFocus

function toHaveFocus(): Promise<void>;

Questo ti permette di asserire se un elemento ha il focus.

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

Questo ti permette di verificare se un modulo o un fieldset contiene controlli di modulo per ogni nome dato, e che abbiano il valore specificato.

TIP

È importante sottolineare che questo matcher può essere invocato solo su un elemento form o fieldset.

Questo gli consente di sfruttare la proprietà .elements degli elementi form e fieldset per recuperare in modo affidabile tutti i controlli di modulo al loro interno.

Questo evita anche la possibilità che gli utenti forniscano un contenitore che contiene più di un form, mischiando così controlli di modulo che non sono correlati e potrebbero persino entrare in conflitto tra loro.

Questo matcher astrae le specificità del modo in cui un valore di controllo di modulo viene ottenuto a seconda del tipo di controllo di modulo. Ad esempio, gli elementi <input> hanno un attributo value, ma gli elementi <select> non lo hanno. Ecco un elenco di tutti i casi coperti:

Gli elementi <input type="number"> restituiscono il valore come un numero, invece di una stringa.
Gli elementi <input type="checkbox">:
- se ce n'è uno singolo con l'attributo name dato, viene trattato come un booleano, restituendo true se la casella di controllo è selezionata, false se deselezionata.
- se ci sono più caselle di controllo con lo stesso attributo name, vengono tutte trattate collettivamente come un singolo controllo di modulo, che restituisce il valore come un array contenente tutti i valori delle caselle di controllo selezionate nel gruppo.
Gli elementi <input type="radio"> sono tutti raggruppati per l'attributo name, e un tale gruppo viene trattato come un singolo controllo di modulo. Questo controllo di modulo restituisce il valore come una stringa corrispondente all'attributo value del pulsante radio selezionato all'interno del gruppo.
Gli elementi <input type="text"> restituiscono il valore come una stringa. Questo si applica anche agli elementi <input> che hanno qualsiasi altro possibile attributo type che non è esplicitamente coperto nelle regole precedenti (ad esempio search, email, date, password, hidden, ecc.)
Gli elementi <select> senza l'attributo multiple restituiscono il valore come una stringa corrispondente all'attributo value dell'opzione selezionata, o undefined se non c'è un'opzione selezionata.
Gli elementi <select multiple> restituiscono il valore come un array contenente tutti i valori delle opzioni selezionate.
Gli elementi <textarea> restituiscono il loro valore come una stringa. Il valore corrisponde al contenuto del loro nodo.

Le regole di cui sopra rendono facile, ad esempio, passare da un singolo controllo di selezione a un gruppo di pulsanti radio. O passare da un controllo di selezione multipla a un gruppo di caselle di controllo. L'insieme risultante di valori del modulo utilizzato da questo matcher per il confronto sarebbe lo stesso.

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

Questo ti permette di verificare se un certo elemento ha alcune proprietà CSS specifiche con valori specifici applicati. Si verifica una corrispondenza solo se l'elemento ha tutte le proprietà attese applicate, non solo alcune di esse.

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

Questo funziona anche con le regole che vengono applicate all'elemento tramite un nome di classe, le cui regole sono definite in un foglio di stile attualmente attivo nel documento. Si applicano le solite regole di precedenza CSS.

toHaveTextContent

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

Questo ti permette di verificare se il nodo dato ha un contenuto testuale. Supporta elementi, ma anche nodi di testo e frammenti.

Quando viene passata una stringa come argomento, eseguirà una corrispondenza parziale sensibile alle maiuscole/minuscole con il contenuto del nodo.

Per eseguire una corrispondenza insensibile alle maiuscole/minuscole, è possibile utilizzare una RegExp con il modificatore /i.

Se si desidera corrispondere all'intero contenuto, è possibile utilizzare una RegExp per farlo.

html

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

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

await expect.element(element).toHaveTextContent('Content');
// per corrispondere all'intero contenuto
await expect.element(element).toHaveTextContent(/^Text Content$/);
// per usare la corrispondenza insensibile alle maiuscole/minuscole
await expect.element(element).toHaveTextContent(/content$/i);
await expect.element(element).not.toHaveTextContent('content');

toHaveValue

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

Questo ti permette di verificare se l'elemento del modulo dato ha il valore specificato. Accetta elementi <input>, <select> e <textarea> con l'eccezione di <input type="checkbox"> e <input type="radio">, che possono essere abbinati in modo significativo solo utilizzando toBeChecked o toHaveFormValues.

Accetta anche elementi con ruoli meter, progressbar, slider o spinbutton e controlla il loro attributo aria-valuenow (come numero).

Per tutti gli altri elementi del modulo, il valore viene abbinato utilizzando lo stesso algoritmo di 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>;

Questo ti permette di verificare se l'elemento del modulo dato ha il valore visualizzato specificato (quello che l'utente finale vedrà). Accetta elementi <input>, <select> e <textarea> con l'eccezione di <input type="checkbox"> e <input type="radio">, che possono essere significativamente abbinati solo utilizzando toBeChecked o 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>;

Questo ti permette di verificare se l'elemento dato è selezionato. Accetta un input di tipo checkbox o radio ed elementi con un role di checkbox, radio o switch con un attributo aria-checked valido di "true" o "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>;

Questo ti permette di verificare se l'elemento dato è parzialmente selezionato. Accetta un input di tipo checkbox ed elementi con un role di checkbox con un attributo aria-checked="mixed", o un input di tipo checkbox con indeterminate impostato su 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>;

Questo ti permette di asserire che un elemento abbia il ruolo atteso.

Questo è utile nei casi in cui si ha già accesso a un elemento tramite una query diversa dal ruolo stesso, e si desidera fare asserzioni aggiuntive riguardo alla sua accessibilità.

Il ruolo può corrispondere sia a un ruolo esplicito (tramite l'attributo role), sia a uno implicito tramite le semantiche ARIA implicite.

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

I ruoli vengono confrontati letteralmente per uguaglianza di stringa, senza ereditare dalla gerarchia dei ruoli ARIA. Di conseguenza, interrogare un ruolo di superclasse come checkbox non includerà elementi con un ruolo di sottoclasse come switch.

Si noti inoltre che, a differenza di testing-library, Vitest ignora tutti i ruoli personalizzati tranne il primo valido, seguendo il comportamento di 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>;

Questo permette di asserire che un elemento abbia una selezione di testo.

Questo è utile per verificare se il testo o parte del testo è selezionato all'interno di un elemento. L'elemento può essere un input di tipo testo, una textarea, o qualsiasi altro elemento che contenga testo, come un paragrafo, uno span, un div ecc.

WARNING

La selezione attesa è una stringa, non permette di controllare gli indici dell'intervallo di selezione.

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

// la selezione del figlio si applica anche al genitore
range.selectNodeContents(getByTestId('child').element());
await expect.element(getByTestId('child')).toHaveSelection('selected');
await expect.element(getByTestId('parent')).toHaveSelection('selected');

// selezione che si applica da "prev all", testo genitore prima del figlio, e parte del figlio.
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();

// selezione che si applica da parte del figlio, testo genitore dopo il figlio e parte dell'elemento successivo.
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');

API di Asserzione ​

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 ​

API di Asserzione

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