Localizzatori 2.1.0+

Un localizzatore rappresenta un elemento o un insieme di elementi. Ogni localizzatore è definito da una stringa chiamata selettore. Vitest astrae l'uso diretto dei selettori fornendo metodi pratici che li generano automaticamente.

L'API dei localizzatori si basa su un fork dei localizzatori di Playwright chiamato Ivya. Tuttavia, Vitest rende questa API disponibile per tutti i provider.

getByRole

function getByRole(
  role: ARIARole | string,
  options?: LocatorByRoleOptions
): Locator;

Crea un localizzatore per trovare un elemento in base al suo ruolo ARIA, agli attributi ARIA e al nome accessibile.

TIP

Se stai cercando un singolo elemento con getByText('Il nome'), è spesso preferibile usare getByRole(ruolo atteso, { name: 'Il nome' }). La ricerca per nome accessibile non sostituisce altre query come *ByAltText o *ByTitle. Sebbene il nome accessibile possa coincidere con questi attributi, ciò non sostituisce la loro funzionalità specifica.

Considera la seguente struttura DOM:

<h3>Registrati</h3>
<label>
  Login
  <input type="text" />
</label>
<label>
  Password
  <input type="password" />
</label>
<br />
<button>Invia</button>

Puoi localizzare ogni elemento in base al suo ruolo implicito:

await expect
  .element(page.getByRole('heading', { name: 'Registrati' }))
  .toBeVisible();

await page.getByRole('textbox', { name: 'Login' }).fill('admin');
await page.getByRole('textbox', { name: 'Password' }).fill('admin');

await page.getByRole('button', { name: /invia/i }).click();

WARNING

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

Per impostazione predefinita, molti elementi semantici in HTML hanno un ruolo; ad esempio, <input type="radio"> ha il ruolo "radio". Gli elementi non semantici in HTML non hanno un ruolo; <div> e <span> senza semantica aggiunta restituiscono null. L'attributo role può fornire semantica.

Assegnare ruoli tramite gli attributi role o aria-* a elementi nativi che hanno già un ruolo implicito è fortemente sconsigliato dalle linee guida ARIA.

Opzioni

• exact: boolean

  Indica se il name deve essere confrontato esattamente: sensibile alle maiuscole e all'intera stringa. Disabilitato per impostazione predefinita. Questa opzione viene ignorata se name è un'espressione regolare. Si noti che anche con corrispondenza esatta vengono eliminati gli spazi bianchi.

  <button>Ciao Mondo</button>;
  
  page.getByRole('button', { name: 'ciao mondo' }); // ✅
  page.getByRole('button', { name: 'ciao mondo', exact: true }); // ❌
  page.getByRole('button', { name: 'Ciao Mondo', exact: true }); // ✅

• checked: boolean

  Specifica se gli elementi selezionati (impostati da aria-checked o <input type="checkbox"/>) devono essere inclusi o meno. Per impostazione predefinita, il filtro non viene applicato.

  Vedi aria-checked per maggiori informazioni.

  <>
    <button role="checkbox" aria-checked="true" />
    <input type="checkbox" checked />
  </>;
  
  page.getByRole('checkbox', { checked: true }); // ✅
  page.getByRole('checkbox', { checked: false }); // ❌

• disabled: boolean

  Specifica se gli elementi disabilitati devono essere inclusi o meno. Per impostazione predefinita, il filtro non viene applicato. Nota che, a differenza di altri attributi, lo stato disabled è ereditato.

  Vedi aria-disabled per maggiori informazioni.

  <input type="text" disabled />;
  
  page.getByRole('textbox', { disabled: true }); // ✅
  page.getByRole('textbox', { disabled: false }); // ❌

• expanded: boolean

  Specifica se gli elementi espansi devono essere inclusi o meno. Per impostazione predefinita, il filtro non viene applicato.

  Vedi aria-expanded per maggiori informazioni.

  <a aria-expanded="true" href="example.com">
    Link
  </a>;
  
  page.getByRole('link', { expanded: true }); // ✅
  page.getByRole('link', { expanded: false }); // ❌

• includeHidden: boolean

  Specifica se gli elementi che sono normalmente esclusi dall'albero di accessibilità devono essere considerati. Per impostazione predefinita, solo gli elementi visibili vengono confrontati dal selettore di ruolo.

  Nota che i ruoli none e presentation sono sempre inclusi.

  <button style="display: none" />;
  
  page.getByRole('button'); // ❌
  page.getByRole('button', { includeHidden: false }); // ❌
  page.getByRole('button', { includeHidden: true }); // ✅

• level: number

  Un attributo numerico solitamente presente per i ruoli heading, listitem, row, treeitem con valori predefiniti per gli elementi <h1>-<h6>. Per impostazione predefinita, il filtro non viene applicato.

  Vedi aria-level per maggiori informazioni.

  <>
    <h1>Intestazione Livello Uno</h1>
    <div role="heading" aria-level="1">
      Seconda Intestazione Livello Uno
    </div>
  </>;
  
  page.getByRole('heading', { level: 1 }); // ✅
  page.getByRole('heading', { level: 2 }); // ❌

• name: string | RegExp

  Un nome accessibile. Per impostazione predefinita, la corrispondenza non è sensibile alle maiuscole e cerca una sottostringa. Usa l'opzione exact per controllare questo comportamento.

  <button>Cliccami!</button>;
  
  page.getByRole('button', { name: 'Cliccami!' }); // ✅
  page.getByRole('button', { name: 'cliccami!' }); // ✅
  page.getByRole('button', { name: 'Cliccami?' }); // ❌

• pressed: boolean

  Specifica se gli elementi premuti devono essere inclusi o meno. Per impostazione predefinita, il filtro non viene applicato.

  Vedi aria-pressed per maggiori informazioni.

  <button aria-pressed="true">👍</button>;
  
  page.getByRole('button', { pressed: true }); // ✅
  page.getByRole('button', { pressed: false }); // ❌

• selected: boolean

  Specifica se gli elementi selezionati devono essere inclusi o meno. Per impostazione predefinita, il filtro non viene applicato.

  Vedi aria-selected per maggiori informazioni.

  <button role="tab" aria-selected="true">
    Vue
  </button>;
  
  page.getByRole('button', { selected: true }); // ✅
  page.getByRole('button', { selected: false }); // ❌

Vedi anche

• Elenco dei ruoli ARIA su MDN
• Elenco dei ruoli ARIA su w3.org
• ByRole di testing-library

getByAltText

function getByAltText(text: string | RegExp, options?: LocatorOptions): Locator;

Crea un localizzatore in grado di trovare un elemento con un attributo alt che corrisponde al testo. A differenza dell'implementazione di testing-library, Vitest corrisponderà a qualsiasi elemento che abbia un attributo alt corrispondente.

<img alt="Poster di Incredibili 2" src="/incredibles-2.png" />;

page.getByAltText(/incredibili.*? poster/i); // ✅
page.getByAltText('testo alt non esistente'); // ❌

Opzioni

• exact: boolean

  Indica se il text viene confrontato esattamente: sensibile alle maiuscole e all'intera stringa. Disabilitato per impostazione predefinita. Questa opzione viene ignorata se text è un'espressione regolare. Nota che la corrispondenza esatta rimuove comunque gli spazi bianchi.

Vedi anche

• ByAltText di testing-library

getByLabelText

function getByLabelText(
  text: string | RegExp,
  options?: LocatorOptions
): Locator;

Crea un localizzatore in grado di trovare un elemento che ha un'etichetta associata.

Il localizzatore page.getByLabelText('Nome utente') troverà ogni input nell'esempio seguente:

<!-- relazione for/htmlFor tra label e id dell'elemento form -->
<label for="username-input">Nome utente</label>
<input id="username-input" />

<!-- L'attributo aria-labelledby con elementi form -->
<label id="username-label">Nome utente</label>
<input aria-labelledby="username-label" />

<!-- Etichette contenitore -->
<label>Nome utente <input /></label>

<!-- Etichette contenitore dove il testo dell'etichetta si trova in un altro elemento figlio -->
<label>
  <span>Nome utente</span>
  <input />
</label>

<!-- attributi aria-label -->
<!-- Attenzione: questo non è un'etichetta visibile sulla pagina per gli utenti, -->
<!-- quindi lo scopo del tuo input deve essere ovvio per gli utenti visivi. -->
<input aria-label="Nome utente" />

Opzioni

• exact: boolean

  Indica se il text viene confrontato esattamente: sensibile alle maiuscole e all'intera stringa. Disabilitato per impostazione predefinita. Questa opzione viene ignorata se text è un'espressione regolare. Nota che la corrispondenza esatta rimuove comunque gli spazi bianchi.

Vedi anche

• ByLabelText di testing-library

getByPlaceholder

function getByPlaceholder(
  text: string | RegExp,
  options?: LocatorOptions
): Locator;

Crea un localizzatore in grado di trovare un elemento che ha l'attributo placeholder specificato. Vitest corrisponderà a qualsiasi elemento che abbia un attributo placeholder corrispondente, non solo input.

<input placeholder="Nome utente" />;

page.getByPlaceholder('Nome utente'); // ✅
page.getByPlaceholder('non trovato'); // ❌

WARNING

È generalmente preferibile fare affidamento su un'etichetta usando getByLabelText piuttosto che su un placeholder.

Opzioni

• exact: boolean

  Indica se il text viene confrontato esattamente: sensibile alle maiuscole e all'intera stringa. Disabilitato per impostazione predefinita. Questa opzione viene ignorata se text è un'espressione regolare. Nota che la corrispondenza esatta rimuove comunque gli spazi bianchi.

Vedi anche

• ByPlaceholderText di testing-library

getByText

function getByText(text: string | RegExp, options?: LocatorOptions): Locator;

Crea un localizzatore in grado di trovare un elemento che contiene il testo specificato. Il testo verrà confrontato con il nodeValue del TextNode o con il valore dell'input se il tipo è button o reset. La corrispondenza per testo normalizza sempre gli spazi bianchi, anche con corrispondenza esatta. Ad esempio, trasforma più spazi in uno, trasforma le interruzioni di riga in spazi e ignora gli spazi bianchi iniziali e finali.

<a href="/about">Informazioni ℹ️</a>;

page.getByText(/informazioni/i); // ✅
page.getByText('informazioni', { exact: true }); // ❌

TIP

Questo localizzatore è utile per localizzare elementi non interattivi. Se devi localizzare un elemento interattivo, come un pulsante o un input, preferisci getByRole.

Opzioni

• exact: boolean

  Indica se il text viene confrontato esattamente: sensibile alle maiuscole e all'intera stringa. Disabilitato per impostazione predefinita. Questa opzione viene ignorata se text è un'espressione regolare. Nota che la corrispondenza esatta rimuove comunque gli spazi bianchi.

Vedi anche

• ByText di testing-library

getByTitle

function getByTitle(text: string | RegExp, options?: LocatorOptions): Locator;

Crea un localizzatore in grado di trovare un elemento che ha l'attributo title specificato. A differenza di getByTitle di testing-library, Vitest non può trovare elementi title all'interno di un SVG.

<span title="Elimina" id="2"></span>;

page.getByTitle('Elimina'); // ✅
page.getByTitle('Crea'); // ❌

Opzioni

• exact: boolean

  Indica se il text viene confrontato esattamente: sensibile alle maiuscole e all'intera stringa. Disabilitato per impostazione predefinita. Questa opzione viene ignorata se text è un'espressione regolare. Nota che la corrispondenza esatta rimuove comunque gli spazi bianchi.

Vedi anche

• ByTitle di testing-library

getByTestId

function getByTestId(text: string | RegExp): Locator;

Crea un localizzatore in grado di trovare un elemento che corrisponde all'attributo test id specificato. Puoi configurare il nome dell'attributo con browser.locators.testIdAttribute.

<div data-testid="elemento-personalizzato" />;

page.getByTestId('elemento-personalizzato'); // ✅
page.getByTestId('elemento-non-esistente'); // ❌

WARNING

Si consiglia di usare questo metodo solo come ultima risorsa. L'uso degli attributi data-testid non riflette l'utilizzo reale del tuo software e dovrebbe essere evitato se possibile.

Opzioni

• exact: boolean

  Indica se il text viene confrontato esattamente: sensibile alle maiuscole e all'intera stringa. Disabilitato per impostazione predefinita. Questa opzione viene ignorata se text è un'espressione regolare. Nota che la corrispondenza esatta rimuove comunque gli spazi bianchi.

Vedi anche

• ByTestId di testing-library

Metodi

Tutti i metodi sono asincroni e devono essere attesi. A partire da Vitest 2.2, i test falliranno se un metodo non viene atteso.

click

function click(options?: UserEventClickOptions): Promise<void>;

Esegue un clic su un elemento. Puoi usare le opzioni per impostare la posizione del cursore.

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

await page.getByRole('img', { name: 'Rosa' }).click();

• Vedi di più su userEvent.click

dblClick

function dblClick(options?: UserEventDoubleClickOptions): Promise<void>;

Genera un evento di doppio clic su un elemento. Puoi usare le opzioni per impostare la posizione del cursore.

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

await page.getByRole('img', { name: 'Rosa' }).dblClick();

• Vedi di più su userEvent.dblClick

tripleClick

function tripleClick(options?: UserEventTripleClickOptions): Promise<void>;

Attiva un evento di triplo clic su un elemento. Poiché non esiste un tripleclick nell'API del browser, questo metodo attiverà tre eventi click in successione.

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

await page.getByRole('img', { name: 'Rosa' }).tripleClick();

• Vedi di più su userEvent.tripleClick

clear

function clear(): Promise<void>;

Svuota il contenuto dell'elemento input.

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

await page.getByRole('textbox', { name: 'Nome completo' }).clear();

• Vedi di più su userEvent.clear

hover

function hover(options?: UserEventHoverOptions): Promise<void>;

Posiziona il cursore sull'elemento selezionato.

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

await page.getByRole('img', { name: 'Rosa' }).hover();

• Vedi di più su userEvent.hover

unhover

function unhover(options?: UserEventHoverOptions): Promise<void>;

Questo funziona allo stesso modo di locator.hover, ma sposta il cursore sull'elemento document.body invece.

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

await page.getByRole('img', { name: 'Rosa' }).unhover();

• Vedi di più su userEvent.unhover

fill

function fill(text: string, options?: UserEventFillOptions): Promise<void>;

Imposta il valore dell'elemento corrente input, textarea o conteneditable.

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

await page.getByRole('input', { name: 'Nome completo' }).fill('Mr. Bean');

• Vedi di più su userEvent.fill

dropTo

function dropTo(
  target: Locator,
  options?: UserEventDragAndDropOptions
): Promise<void>;

Rilascia l'elemento corrente nella posizione di destinazione.

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

const paris = page.getByText('Parigi');
const france = page.getByText('Francia');

await paris.dropTo(france);

• Vedi di più su userEvent.dragAndDrop

selectOptions

function selectOptions(
  values: HTMLElement | HTMLElement[] | Locator | Locator[] | string | string[],
  options?: UserEventSelectOptions
): Promise<void>;

Scegli uno o più valori da un elemento <select>.

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

const languages = page.getByRole('select', { name: 'Lingue' });

await languages.selectOptions('IT');
await languages.selectOptions(['ES', 'FR']);
await languages.selectOptions([
  languages.getByRole('option', { name: 'Spagnolo' }),
  languages.getByRole('option', { name: 'Francese' }),
]);

• Vedi di più su userEvent.selectOptions

screenshot

function screenshot(
  options: LocatorScreenshotOptions & { base64: true }
): Promise<{
  path: string;
  base64: string;
}>;
function screenshot(
  options?: LocatorScreenshotOptions & { base64?: false }
): Promise<string>;

Acquisisce uno screenshot dell'elemento che corrisponde al selettore del localizzatore.

Puoi specificare la posizione di salvataggio per lo screenshot usando l'opzione path, che è relativa al file di test corrente. Se l'opzione path non è impostata, Vitest utilizzerà per impostazione predefinita browser.screenshotDirectory (__screenshot__ per impostazione predefinita), insieme ai nomi del file e del test per determinare il percorso del file dello screenshot.

Se hai bisogno anche del contenuto dello screenshot, puoi specificare base64: true per restituirlo insieme al percorso del file in cui viene salvato lo screenshot.

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

const button = page.getByRole('button', { name: 'Cliccami!' });

const path = await button.screenshot();

const { path, base64 } = await button.screenshot({
  path: './button-click-me.png',
  base64: true, // restituisce inoltre la stringa base64
});
// path - percorso completo dello screenshot
// base64 - stringa codificata in base64 dello screenshot

query

function query(): Element | null;

Questo metodo restituisce un singolo elemento che corrisponde al selettore del localizzatore o null se non viene trovato alcun elemento.

Se più elementi corrispondono al selettore, questo metodo genererà un errore. Usa .elements() quando hai bisogno di tutti gli elementi DOM corrispondenti o .all() se hai bisogno di un array di localizzatori che corrispondono al selettore.

Considera la seguente struttura DOM:

<div>Ciao <span>Mondo</span></div>
<div>Ciao</div>

Questi selettori non causeranno errori:

page.getByText('Ciao Mondo').query(); // ✅ HTMLDivElement
page.getByText('Ciao Germania').query(); // ✅ null
page.getByText('Mondo').query(); // ✅ HTMLSpanElement
page.getByText('Ciao', { exact: true }).query(); // ✅ HTMLSpanElement

Questi localizzatori genereranno un errore:

// restituisce più elementi
page.getByText('Ciao').query(); // ❌
page.getByText(/^Ciao/).query(); // ❌

element

function element(): Element;

Questo metodo restituisce un singolo elemento che corrisponde al selettore del localizzatore.

Se nessun elemento corrisponde al selettore, viene generato un errore. Considera l'utilizzo di .query() quando devi solo verificare se l'elemento esiste.

Se più elementi corrispondono al selettore, viene generato un errore. Usa .elements() quando hai bisogno di tutti gli elementi DOM corrispondenti o .all() se hai bisogno di un array di localizzatori che corrispondono al selettore.

TIP

Questo metodo può essere utile se devi passarlo a una libreria esterna. Viene chiamato automaticamente quando il localizzatore viene utilizzato con expect.element ogni volta che l'asserzione viene ritentata:

await expect.element(page.getByRole('button')).toBeDisabled();

Considera la seguente struttura DOM:

<div>Ciao <span>Mondo</span></div>
<div>Ciao Germania</div>
<div>Ciao</div>

Questi localizzatori non genereranno un errore:

page.getByText('Ciao Mondo').element(); // ✅
page.getByText('Ciao Germania').element(); // ✅
page.getByText('Mondo').element(); // ✅
page.getByText('Ciao', { exact: true }).element(); // ✅

Questi localizzatori genereranno un errore:

// restituisce più elementi
page.getByText('Ciao').element(); // ❌
page.getByText(/^Ciao/).element(); // ❌

// restituisce nessun elemento
page.getByText('Ciao USA').element(); // ❌

elements

function elements(): Element[];

Questo metodo restituisce un array di elementi che corrispondono al selettore del localizzatore.

Questa funzione non genera mai un errore. Se non ci sono elementi che corrispondono al selettore, questo metodo restituirà un array vuoto.

Considera la seguente struttura DOM:

<div>Ciao <span>Mondo</span></div>
<div>Ciao</div>

Questi localizzatori avranno sempre successo:

page.getByText('Ciao Mondo').elements(); // ✅ [HTMLElement]
page.getByText('Mondo').elements(); // ✅ [HTMLElement]
page.getByText('Ciao', { exact: true }).elements(); // ✅ [HTMLElement]
page.getByText('Ciao').element(); // ✅ [HTMLElement, HTMLElement]
page.getByText('Ciao USA').elements(); // ✅ []

all

function all(): Locator[];

Questo metodo restituisce un array di nuovi localizzatori che corrispondono al selettore.

Internamente, questo metodo chiama .elements e avvolge ogni elemento usando page.elementLocator.

• Vedi locator.elements()