Localizadores 2.1.0+

Um localizador representa um ou mais elementos na página. Cada localizador é definido por uma string chamada seletor. O Vitest abstrai o uso direto de seletores, oferecendo métodos convenientes que geram esses seletores internamente.

A API de localizador utiliza um fork dos localizadores do Playwright, chamado Ivya. No entanto, o Vitest disponibiliza essa API para cada provedor configurado.

getByRole

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

Cria um localizador para encontrar um elemento com base em seu papel ARIA, atributos ARIA e nome acessível.

TIP

Se você precisa encontrar apenas um único elemento com getByText('O nome'), geralmente é preferível usar getByRole(expectedRole, { name: 'O nome' }). A consulta por nome acessível não substitui outras consultas como *ByAltText ou *ByTitle. Embora o nome acessível possa ser igual a esses atributos, ele não substitui a funcionalidade que eles proporcionam.

Considere a seguinte estrutura DOM:

html

<h3>Sign up</h3>
<label>
  Login
  <input type="text" />
</label>
<label>
  Password
  <input type="password" />
</label>
<br />
<button>Submit</button>

Você pode localizar cada elemento por seu papel implícito:

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

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

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

WARNING

Os papéis são correspondidos por igualdade de string, sem herdar da hierarquia de papéis ARIA. Portanto, consultar um papel de superclasse como checkbox não incluirá elementos com um papel de subclasse como switch.

Por padrão, muitos elementos semânticos em HTML possuem um papel; por exemplo, <input type="radio"> tem o papel "radio". Elementos não semânticos em HTML não possuem um papel; <div> e <span> sem semântica adicional retornam null. O atributo role pode fornecer semântica.

Fornecer papéis via atributos role ou aria-* a elementos nativos que já possuem um papel implícito é altamente desencorajado pelas diretrizes ARIA.

Opções

exact: boolean
Define se o name deve ser correspondido exatamente: sensível a maiúsculas/minúsculas e à string completa. Desabilitado por padrão. Esta opção é ignorada se name for uma expressão regular. Note que a correspondência exata ainda remove espaços em branco.
tsx
```
<button>Hello World</button>;

page.getByRole('button', { name: 'hello world' }); // ✅
page.getByRole('button', { name: 'hello world', exact: true }); // ❌
page.getByRole('button', { name: 'Hello World', exact: true }); // ✅
```

checked: boolean

Filtra elementos marcados (definidos por aria-checked ou <input type="checkbox"/>). Por padrão, o filtro não é aplicado.

Consulte aria-checked para mais informações.

tsx

<>
  <button role="checkbox" aria-checked="true" />
  <input type="checkbox" checked />
</>;

page.getByRole('checkbox', { checked: true }); // ✅
page.getByRole('checkbox', { checked: false }); // ❌

disabled: boolean
Filtra elementos desabilitados. Por padrão, o filtro não é aplicado. Note que, ao contrário de outros atributos, o estado de desabilitação é herdado.
Consulte aria-disabled para mais informações.
tsx
```
<input type="text" disabled />;

page.getByRole('textbox', { disabled: true }); // ✅
page.getByRole('textbox', { disabled: false }); // ❌
```

expanded: boolean

Filtra elementos expandidos. Por padrão, o filtro não é aplicado.

Consulte aria-expanded para mais informações.

tsx

<a aria-expanded="true" href="example.com">
  Link
</a>;

page.getByRole('link', { expanded: true }); // ✅
page.getByRole('link', { expanded: false }); // ❌

includeHidden: boolean
Indica se elementos que são normalmente excluídos da árvore de acessibilidade devem ser incluídos na consulta. Por padrão, apenas elementos visíveis são correspondidos pelo seletor de papel.
Note que os papéis none e presentation são sempre incluídos na consulta.
tsx
```
<button style="display: none" />;

page.getByRole('button'); // ❌
page.getByRole('button', { includeHidden: false }); // ❌
page.getByRole('button', { includeHidden: true }); // ✅
```

level: number

Um atributo numérico geralmente presente para os papéis heading, listitem, row, treeitem, com valores padrão para elementos <h1>-<h6>. Por padrão, o filtro não é aplicado.

Consulte aria-level para mais informações.

tsx

<>
  <h1>Heading Level One</h1>
  <div role="heading" aria-level="1">
    Second Heading Level One
  </div>
</>;

page.getByRole('heading', { level: 1 }); // ✅
page.getByRole('heading', { level: 2 }); // ❌

name: string | RegExp

Um nome acessível. Por padrão, a correspondência não diferencia maiúsculas de minúsculas e busca por uma substring. Use a opção exact para controlar esse comportamento.

tsx

<button>Click Me!</button>;

page.getByRole('button', { name: 'Click Me!' }); // ✅
page.getByRole('button', { name: 'click me!' }); // ✅
page.getByRole('button', { name: 'Click Me?' }); // ❌

pressed: boolean

Filtra elementos pressionados. Por padrão, o filtro não é aplicado.

Consulte aria-pressed para mais informações.

tsx

<button aria-pressed="true">👍</button>;

page.getByRole('button', { pressed: true }); // ✅
page.getByRole('button', { pressed: false }); // ❌

selected: boolean

Filtra elementos selecionados. Por padrão, o filtro não é aplicado.

Consulte aria-selected para mais informações.

tsx

<button role="tab" aria-selected="true">
  Vue
</button>;

page.getByRole('button', { selected: true }); // ✅
page.getByRole('button', { selected: false }); // ❌

Veja também

getByAltText

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

Cria um localizador capaz de encontrar um elemento com um atributo alt que corresponda ao texto. Ao contrário da implementação do testing-library, o Vitest encontrará qualquer elemento que possua um atributo alt correspondente.

tsx

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

page.getByAltText(/incredibles.*? poster/i); // ✅
page.getByAltText('non existing alt text'); // ❌

Opções

exact: boolean
Define se o text deve ser correspondido exatamente: sensível a maiúsculas/minúsculas e à string completa. Desabilitado por padrão. Esta opção é ignorada se text for uma expressão regular. Note que a correspondência exata ainda remove espaços em branco.

Veja também

ByAltText do testing-library

getByLabelText

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

Cria um localizador capaz de encontrar um elemento que tenha um rótulo associado.

O localizador page.getByLabelText('Username') encontrará todos os inputs nos exemplos abaixo:

html

<!-- Relação for/htmlFor entre label e id do elemento do formulário -->
<label for="username-input">Username</label>
<input id="username-input" />

<!-- O atributo aria-labelledby com elementos de formulário -->
<label id="username-label">Username</label>
<input aria-labelledby="username-label" />

<!-- Rótulos que englobam o input -->
<label>Username <input /></label>

<!-- Rótulos que englobam o input onde o texto do rótulo está em outro elemento filho -->
<label>
  <span>Username</span>
  <input />
</label>

<!-- Atributos aria-label -->
<!-- Cuidado: este não é um rótulo visível para usuários na página, -->
<!-- portanto, o propósito do seu input deve ser óbvio para usuários visuais. -->
<input aria-label="Username" />

Opções

exact: boolean
Define se o text deve ser correspondido exatamente: sensível a maiúsculas/minúsculas e à string completa. Desabilitado por padrão. Esta opção é ignorada se text for uma expressão regular. Note que a correspondência exata ainda remove espaços em branco.

Veja também

ByLabelText do testing-library

getByPlaceholder

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

Cria um localizador capaz de encontrar um elemento que tenha o atributo placeholder especificado. O Vitest encontrará qualquer elemento que possua um atributo placeholder correspondente, não apenas inputs.

tsx

<input placeholder="Username" />;

page.getByPlaceholder('Username'); // ✅
page.getByPlaceholder('not found'); // ❌

WARNING

Geralmente é preferível usar um rótulo com getByLabelText em vez de um placeholder para identificar elementos.

Opções

exact: boolean
Define se o text deve ser correspondido exatamente: sensível a maiúsculas/minúsculas e à string completa. Desabilitado por padrão. Esta opção é ignorada se text for uma expressão regular. Note que a correspondência exata ainda remove espaços em branco.

Veja também

ByPlaceholderText do testing-library

getByText

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

Cria um localizador capaz de encontrar um elemento que contenha o texto especificado. O texto será correspondido ao nodeValue de um TextNode ou ao valor de um input se o tipo for button ou reset. A correspondência por texto sempre normaliza espaços em branco, mesmo com correspondência exata. Por exemplo, transforma múltiplos espaços em um único espaço, transforma quebras de linha em espaços e ignora espaços em branco iniciais e finais.

tsx

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

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

TIP

Este localizador é útil para encontrar elementos não interativos. Se você precisar encontrar um elemento interativo, como um botão ou um input, prefira getByRole.

Opções

exact: boolean
Define se o text deve ser correspondido exatamente: sensível a maiúsculas/minúsculas e à string completa. Desabilitado por padrão. Esta opção é ignorada se text for uma expressão regular. Note que a correspondência exata ainda remove espaços em branco.

Veja também

ByText do testing-library

getByTitle

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

Cria um localizador capaz de encontrar um elemento que tenha o atributo title especificado. Ao contrário do getByTitle do testing-library, o Vitest não consegue encontrar elementos title dentro de um SVG.

tsx

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

page.getByTitle('Delete'); // ✅
page.getByTitle('Create'); // ❌

Opções

exact: boolean
Define se o text deve ser correspondido exatamente: sensível a maiúsculas/minúsculas e à string completa. Desabilitado por padrão. Esta opção é ignorada se text for uma expressão regular. Note que a correspondência exata ainda remove espaços em branco.

Veja também

ByTitle do testing-library

getByTestId

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

Cria um localizador capaz de encontrar um elemento que corresponda ao atributo de ID de teste especificado. Você pode configurar o nome do atributo com browser.locators.testIdAttribute.

tsx

<div data-testid="custom-element" />;

page.getByTestId('custom-element'); // ✅
page.getByTestId('non-existing-element'); // ❌

WARNING

É recomendado usar este localizador apenas quando os outros métodos não forem adequados para o seu caso de uso. Utilizar atributos data-testid não simula a forma como os usuários interagem com o software e deve ser evitado, se possível.

Opções

exact: boolean
Define se o text deve ser correspondido exatamente: sensível a maiúsculas/minúsculas e à string completa. Desabilitado por padrão. Esta opção é ignorada se text for uma expressão regular. Note que a correspondência exata ainda remove espaços em branco.

Veja também

ByTestId do testing-library

Métodos

Todos os métodos são assíncronos e devem ser aguardados. Desde o Vitest 2.2, os testes falharão se um método não for aguardado.

click

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

Clica em um elemento. Você pode usar as opções para definir a posição do cursor.

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

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

Veja mais em userEvent.click

dblClick

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

Aciona um evento de duplo clique em um elemento. Você pode usar as opções para definir a posição do cursor.

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

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

Veja mais em userEvent.dblClick

tripleClick

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

Aciona um evento de triplo clique em um elemento. Como não há um evento tripleclick na API do navegador, este método disparará três eventos de clique em sequência.

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

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

Veja mais em userEvent.tripleClick

clear

function clear(): Promise<void>;

Limpa o conteúdo do elemento de entrada.

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

await page.getByRole('textbox', { name: 'Full Name' }).clear();

Veja mais em userEvent.clear

hover

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

Move a posição do cursor para o elemento selecionado.

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

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

Veja mais em userEvent.hover

unhover

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

Este método funciona de forma semelhante a locator.hover, mas move o cursor para o elemento document.body.

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

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

Veja mais em userEvent.unhover

fill

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

Define o valor do elemento input, textarea ou contenteditable atual.

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

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

Veja mais em userEvent.fill

dropTo

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

Arrasta o elemento atual para o local de destino.

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

const paris = page.getByText('Paris');
const france = page.getByText('France');

await paris.dropTo(france);

Veja mais em userEvent.dragAndDrop

selectOptions

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

Seleciona uma ou mais opções em um elemento <select>.

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

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

await languages.selectOptions('EN');
await languages.selectOptions(['ES', 'FR']);
await languages.selectOptions([
  languages.getByRole('option', { name: 'Spanish' }),
  languages.getByRole('option', { name: 'French' }),
]);

Veja mais em userEvent.selectOptions

screenshot

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

Cria uma captura de tela do elemento que corresponde ao seletor do localizador.

Você pode especificar o local para salvar a captura de tela usando a opção path, que é relativa ao arquivo de teste atual. Se a opção path não for definida, o Vitest usará por padrão browser.screenshotDirectory (__screenshot__ por padrão), juntamente com os nomes do arquivo e do teste para determinar o caminho do arquivo da captura de tela.

Se você também precisar do conteúdo da captura de tela, pode especificar base64: true para retorná-lo junto com o caminho do arquivo onde a captura de tela é salva.

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

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

const path = await button.screenshot();

const { path, base64 } = await button.screenshot({
  path: './button-click-me.png',
  base64: true, // também retorna a string base64
});
// path - caminho completo para a captura de tela
// bas64 - string codificada em base64 da captura de tela

query

function query(): Element | null;

Este método retorna um único elemento que corresponde ao seletor do localizador ou null se nenhum elemento for encontrado.

Se múltiplos elementos corresponderem ao seletor, este método lançará um erro. Use .elements() quando precisar de todos os elementos DOM correspondentes ou .all() se precisar de um array de localizadores que correspondam ao seletor.

Considere a seguinte estrutura DOM:

html

<div>Hello <span>World</span></div>
<div>Hello</div>

Estes localizadores não lançarão um erro:

page.getByText('Hello World').query(); // ✅ HTMLDivElement
page.getByText('Hello Germany').query(); // ✅ null
page.getByText('World').query(); // ✅ HTMLSpanElement
page.getByText('Hello', { exact: true }).query(); // ✅ HTMLSpanElement

Estes localizadores lançarão um erro:

// retorna múltiplos elementos
page.getByText('Hello').query(); // ❌
page.getByText(/^Hello/).query(); // ❌

element

function element(): Element;

Este método retorna um único elemento que corresponde ao seletor do localizador.

Se nenhum elemento corresponder ao seletor, um erro é lançado. Considere usar .query() quando você apenas precisar verificar se o elemento existe.

Se múltiplos elementos corresponderem ao seletor, um erro é lançado. Use .elements() quando precisar de todos os elementos DOM correspondentes ou .all() se precisar de um array de localizadores que correspondam ao seletor.

TIP

Este método pode ser útil caso você precise passá-lo para uma biblioteca externa. Ele é chamado automaticamente quando o localizador é usado com expect.element toda vez que a asserção é repetida:

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

Considere a seguinte estrutura DOM:

html

<div>Hello <span>World</span></div>
<div>Hello Germany</div>
<div>Hello</div>

Estes localizadores não lançarão um erro:

page.getByText('Hello World').element(); // ✅
page.getByText('Hello Germany').element(); // ✅
page.getByText('World').element(); // ✅
page.getByText('Hello', { exact: true }).element(); // ✅

Estes localizadores lançarão um erro:

// retorna múltiplos elementos
page.getByText('Hello').element(); // ❌
page.getByText(/^Hello/).element(); // ❌

// retorna nenhum elemento
page.getByText('Hello USA').element(); // ❌

elements

function elements(): Element[];

Este método retorna um array de elementos que correspondem ao seletor do localizador.

Este método nunca gera um erro. Se não houver elementos que correspondam ao seletor, este método retornará um array vazio.

Considere a seguinte estrutura DOM:

html

<div>Hello <span>World</span></div>
<div>Hello</div>

Estes localizadores sempre serão bem-sucedidos:

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

all

function all(): Locator[];

Este método retorna um array de novos localizadores que correspondem ao seletor.

Internamente, este método chama .elements e envolve cada elemento usando page.elementLocator.

Veja locator.elements()

Localizadores 2.1.0+ ​

getByRole ​

Opções ​

Veja também ​

getByAltText ​

Opções ​

Veja também ​

getByLabelText ​

Opções ​

Veja também ​

getByPlaceholder ​

Opções ​

Veja também ​

getByText ​

Opções ​

Veja também ​

getByTitle ​

Opções ​

Veja também ​

getByTestId ​

Opções ​

Veja também ​

Métodos ​

click ​

dblClick ​

tripleClick ​

clear ​

hover ​

unhover ​

fill ​

dropTo ​

selectOptions ​

screenshot ​

query ​

element ​

elements ​

all ​

Localizadores 2.1.0+

getByRole

Opções

Veja também

getByAltText

Opções

Veja também

getByLabelText

Opções

Veja também

getByPlaceholder

Opções

Veja também

getByText

Opções

Veja também

getByTitle

Opções

Veja também

getByTestId

Opções

Veja também

Métodos

click

dblClick

tripleClick

clear

hover

unhover

fill

dropTo

selectOptions

screenshot

query

element

elements

all