Lokátorok 2.1.0+

A lokátor egy vagy több elem reprezentációja. Minden lokátort egy selector nevű karakterlánc definiál. A Vitest absztrahálja ezt a selectort kényelmes metódusokkal, amelyek a háttérben generálják ezeket a selectorokat.

A lokátor API a Playwright lokátorainak egy elágazását használja, amelynek neve Ivya. A Vitest azonban ezt az API-t minden szolgáltatóhoz biztosítja.

getByRole

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

Lehetővé teszi egy elem megtalálását az ARIA szerepe, ARIA attribútumai és elérhető neve alapján.

TIP

Ha csak egyetlen elemet keresel a getByText('A név') paranccsal, általában jobb a getByRole(vártSzerep, { name: 'A név' }) használata. Az elérhető név lekérdezés nem helyettesíti a többi lekérdezést, mint például a *ByAltText vagy a *ByTitle. Bár a hozzáférhető név egyenlő lehet ezekkel az attribútumokkal, nem helyettesíti azok funkcionalitását.

Tekintsük a következő DOM struktúrát.

html

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

Minden elemet megtalálhatsz az implicit szerepe alapján:

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

A szerepek string egyenlőség alapján egyeznek, az ARIA szerephierarchiából való öröklődés nélkül. Ennek eredményeként egy szuperosztály szerep, mint a checkbox lekérdezése nem fogja tartalmazni az olyan alosztály szereppel rendelkező elemeket, mint a switch.

Alapértelmezés szerint sok jelentésű HTML elemnek van szerepe; például az <input type="radio"> "radio" szereppel rendelkezik. A nem szemantikus HTML elemeknek nincs szerepe; a <div> és <span> hozzáadott szemantika nélkül null-t ad vissza. A role attribútum szemantikát biztosíthat.

Az ARIA irányelvek erősen ellenjavallják a szerepek biztosítását a role vagy aria-* attribútumokon keresztül olyan beépített elemekhez, amelyeknek már van implicit szerepe.

Opciók

exact: boolean
Pontosan egyezik-e a name: kis- és nagybetűérzékeny és teljes string. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a name reguláris kifejezés. Ne feledd, hogy a pontos egyezés továbbra is levágja a szóközt.
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

Tartalmazza-e a bejelölt elemeket (az aria-checked vagy <input type="checkbox"/> által beállított) vagy sem. Alapértelmezés szerint a szűrő nincs alkalmazva.

További információért lásd: aria-checked

tsx

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

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

disabled: boolean
Tartalmazza-e a letiltott elemeket vagy sem. Alapértelmezés szerint a szűrő nincs alkalmazva. Ne feledd, hogy más attribútumokkal ellentétben a disable állapot öröklődik.
További információért lásd: aria-disabled
tsx
```
<input type="text" disabled />;

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

expanded: boolean

Tartalmazza-e a kibővített elemeket vagy sem. Alapértelmezés szerint a szűrő nincs alkalmazva.

További információért lásd: aria-expanded

tsx

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

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

includeHidden: boolean
Lekérdezze-e azokat az elemeket, amelyek általában ki vannak zárva a hozzáférhetőségi fából. Alapértelmezés szerint csak a nem rejtett elemek egyeznek a szerep selectorral.
Ne feledd, hogy a none és presentation szerepek mindig szerepelnek.
tsx
```
<button style="display: none" />;

page.getByRole('button'); // ❌
page.getByRole('button', { includeHidden: false }); // ❌
page.getByRole('button', { includeHidden: true }); // ✅
```
level: number
Egy szám attribútum, amely általában jelen van a heading, listitem, row, treeitem szerepeknél, alapértelmezett értékekkel a <h1>-<h6> elemekhez. Alapértelmezés szerint a szűrő nincs alkalmazva.
További információért lásd: aria-level
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
Egy hozzáférhető név. Alapértelmezés szerint az egyezés kis- és nagybetűérzéketlen, és egy substringet keres. Használd az exact opciót ennek a viselkedésnek a szabályozására.
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
Tartalmazza-e a lenyomott elemeket vagy sem. Alapértelmezés szerint a szűrő nincs alkalmazva.
További információért lásd: aria-pressed
tsx
```
<button aria-pressed="true">👍</button>;

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

selected: boolean

Tartalmazza-e a kiválasztott elemeket vagy sem. Alapértelmezés szerint a szűrő nincs alkalmazva.

További információért lásd: aria-selected

tsx

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

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

Lásd még

getByAltText

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

Létrehoz egy lokátort, amely képes megtalálni egy elemet, amelynek alt attribútuma megegyezik a szöveggel. A testing-library implementációjával ellentétben a Vitest minden olyan elemet megtalál, amelynek van egyező alt attribútuma.

tsx

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

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

Opciók

exact: boolean
Pontosan egyezik-e a text: kis- és nagybetűérzékeny és teljes string. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Ne feledd, hogy a pontos egyezés továbbra is levágja a szóközt.

Lásd még

testing-library ByAltText

getByLabelText

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

Létrehoz egy lokátort, amely képes megtalálni egy elemet, amelyhez társított címke tartozik.

A page.getByLabelText('Felhasználónév') lokátor megtalálja az összes beviteli mezőt az alábbi példában:

html

<!-- for/htmlFor kapcsolat a címke és az űrlap elem id között -->
<label for="username-input">Username</label>
<input id="username-input" />

<!-- Az aria-labelledby attribútum űrlap elemekkel -->
<label id="username-label">Username</label>
<input aria-labelledby="username-label" />

<!-- Wrapper címkék -->
<label>Username <input /></label>

<!-- Wrapper címkék, ahol a címke szövege egy másik gyermek elemben van -->
<label>
  <span>Username</span>
  <input />
</label>

<!-- aria-label attribútumok -->
<!-- Figyelem: ez nem látható címke a felhasználók számára, -->
<!-- így a beviteli mező céljának nyilvánvalónak kell lennie a vizuális felhasználók számára. -->
<input aria-label="Username" />

Opciók

exact: boolean
Pontosan egyezik-e a text: kis- és nagybetűérzékeny és teljes string. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Ne feledd, hogy a pontos egyezés továbbra is levágja a szóközt.

Lásd még

testing-library ByLabelText

getByPlaceholder

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

Létrehoz egy lokátort, amely képes megtalálni egy elemet, amely rendelkezik a megadott placeholder attribútummal. A Vitest minden olyan elemet megtalál, amelynek van egyező placeholder attribútuma, nem csak az input elemeket.

tsx

<input placeholder="Username" />;

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

WARNING

Általában jobb egy címkére támaszkodni a getByLabelText használatával, mint egy placeholderre.

Opciók

exact: boolean
Pontosan egyezik-e a text: kis- és nagybetűérzékeny és teljes string. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Ne feledd, hogy a pontos egyezés továbbra is levágja a szóközt.

Lásd még

testing-library ByPlaceholderText

getByText

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

Létrehoz egy lokátort, amely képes megtalálni egy elemet, amely tartalmazza a megadott szöveget. A szöveg a TextNode nodeValue értékével vagy az input értékével egyezik, ha a típus button vagy reset. A szöveg szerinti egyezés mindig normalizálja a szóközt, még pontos egyezés esetén is. Például több szóközt egyre alakít, sortöréseket szóközökre alakít, és figyelmen kívül hagyja a vezető és záró szóközt.

tsx

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

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

TIP

Ez a lokátor hasznos nem interaktív elemek megtalálásához. Ha interaktív elemet kell megtalálnod, mint egy gomb vagy egy beviteli mező, részesítsd előnyben a getByRole használatát.

Opciók

exact: boolean
Pontosan egyezik-e a text: kis- és nagybetűérzékeny és teljes string. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Ne feledd, hogy a pontos egyezés továbbra is levágja a szóközt.

Lásd még

testing-library ByText

getByTitle

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

Létrehoz egy lokátort, amely képes megtalálni egy elemet, amely rendelkezik a megadott title attribútummal. A testing-library getByTitle implementációjával ellentétben a Vitest nem talál title elemeket egy SVG-n belül.

tsx

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

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

Opciók

exact: boolean
Pontosan egyezik-e a text: kis- és nagybetűérzékeny és teljes string. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Ne feledd, hogy a pontos egyezés továbbra is levágja a szóközt.

Lásd még

testing-library ByTitle

getByTestId

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

Létrehoz egy lokátort, amely képes megtalálni egy elemet, amely megegyezik a megadott teszt azonosító attribútummal. Az attribútum nevét a browser.locators.testIdAttribute segítségével konfigurálhatod.

tsx

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

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

WARNING

Ajánlott ezt csak akkor használni, ha a többi lokátor nem működik az adott felhasználási esetre. A data-testid attribútumok használata nem hasonlít arra, ahogyan a szoftveredet használják, és lehetőség szerint kerülni kell.

Opciók

exact: boolean
Pontosan egyezik-e a text: kis- és nagybetűérzékeny és teljes string. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Ne feledd, hogy a pontos egyezés továbbra is levágja a szóközt.

Lásd még

testing-library ByTestId

Metódusok

Minden metódus aszinkron, és meg kell várni. A Vitest 2.2 óta a tesztek hibát fognak dobni, ha egy metódust nem várnak meg.

click

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

Kattintás egy elemen. Az opciók segítségével beállíthatod a kurzor pozícióját.

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

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

További információ: userEvent.click

dblClick

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

Kettős kattintás eseményt vált ki egy elemen. Az opciók segítségével beállíthatod a kurzor pozícióját.

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

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

További információ: userEvent.dblClick

tripleClick

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

Háromszoros kattintás eseményt vált ki egy elemen. Mivel nincs tripleclick a böngésző API-ban, ez a metódus három kattintás eseményt fog kiváltani egymás után.

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

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

További információ: userEvent.tripleClick

clear

function clear(): Promise<void>;

Kitörli a beviteli elem tartalmát.

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

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

További információ: userEvent.clear

hover

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

Áthelyezi a kurzor pozícióját a kiválasztott elemre.

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

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

További információ: userEvent.hover

unhover

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

Ez ugyanúgy működik, mint a locator.hover, de a kurzort a document.body elemre helyezi át.

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

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

További információ: userEvent.unhover

fill

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

Beállítja az aktuális input, textarea vagy contenteditable elem értékét.

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

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

További információ: userEvent.fill

dropTo

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

Áthúzza az aktuális elemet a célhelyre.

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

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

await paris.dropTo(france);

További információ: userEvent.dragAndDrop

selectOptions

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

Válassz ki egy vagy több értéket egy <select> elemből.

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

További információ: userEvent.selectOptions

screenshot

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

Létrehoz egy képernyőképet a lokátor selectorjának megfelelő elemről.

Megadhatod a képernyőkép mentési helyét a path opcióval, amely az aktuális tesztfájlhoz képest relatív. Ha a path opció nincs beállítva, a Vitest alapértelmezés szerint a browser.screenshotDirectory (__screenshot__ alapértelmezés szerint) könyvtárat használja, a fájl és a teszt nevével együtt a képernyőkép fájlútvonalának meghatározásához.

Ha a képernyőkép tartalmára is szükséged van, megadhatod a base64: true opciót, hogy a fájlútvonal mellett a tartalom is visszatérjen.

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, // also return base64 string
});
// path - fullpath to the screenshot
// base64 - base64 encoded string of the screenshot

query

function query(): Element | null;

Ez a metódus egyetlen elemet ad vissza, amely megfelel a lokátor selectorjának, vagy null-t, ha nem található elem.

Ha több elem is megfelel a selectornak, ez a metódus hibát dob. Használd a .elements() metódust, ha az összes megfelelő DOM elemre szükséged van, vagy a .all() metódust, ha a selectornak megfelelő lokátorok tömbjére van szükséged.

Tekintsük a következő DOM struktúrát:

html

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

Ezek a lokátorok nem dobnak hibát:

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

Ezek a lokátorok hibát dobnak:

// returns multiple elements
page.getByText('Hello').query(); // ❌
page.getByText(/^Hello/).query(); // ❌

element

function element(): Element;

Ez a metódus egyetlen elemet ad vissza, amely megfelel a lokátor selectorjának.

Ha nincs elem, amely megfelel a selectornak, hiba dobódik. Fontold meg a .query() használatát, ha csak ellenőrizni szeretnéd, hogy az elem létezik-e.

Ha több elem is megfelel a selectornak, hiba dobódik. Használd a .elements() metódust, ha az összes megfelelő DOM elemre szükséged van, vagy a .all() metódust, ha a selectornak megfelelő lokátorok tömbjére van szükséged.

TIP

Ez a metódus hasznos lehet, ha át kell adnod egy külső könyvtárnak. Automatikusan meghívódik, amikor a lokátort az expect.element paranccsal használják minden alkalommal, amikor az állítás újrapróbálkozik:

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

Tekintsük a következő DOM struktúrát:

html

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

Ezek a lokátorok nem dobnak hibát:

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

Ezek a lokátorok hibát dobnak:

// returns multiple elements
page.getByText('Hello').element(); // ❌
page.getByText(/^Hello/).element(); // ❌

// returns no elements
page.getByText('Hello USA').element(); // ❌

elements

function elements(): Element[];

Ez a metódus egy tömböt ad vissza a lokátor selectorjának megfelelő elemekből.

Ez a függvény soha nem dob hibát. Ha nincsenek elemek, amelyek megfelelnek a selectornak, ez a metódus üres tömböt ad vissza.

Tekintsük a következő DOM struktúrát:

html

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

Ezek a lokátorok mindig sikeresek lesznek:

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

Ez a metódus egy tömböt ad vissza új lokátorokból, amelyek megfelelnek a selectornak.

Belsőleg ez a metódus meghívja a .elements metódust, és minden elemet becsomagol a page.elementLocator segítségével.

További információ: locator.elements()

Lokátorok 2.1.0+ ​

getByRole ​

Opciók ​

Lásd még ​

getByAltText ​

Opciók ​

Lásd még ​

getByLabelText ​

Opciók ​

Lásd még ​

getByPlaceholder ​

Opciók ​

Lásd még ​

getByText ​

Opciók ​

Lásd még ​

getByTitle ​

Opciók ​

Lásd még ​

getByTestId ​

Opciók ​

Lásd még ​

Metódusok ​

click ​

dblClick ​

tripleClick ​

clear ​

hover ​

unhover ​

fill ​

dropTo ​

selectOptions ​

screenshot ​

query ​

element ​

elements ​

all ​

Lokátorok 2.1.0+

getByRole

Opciók

Lásd még

getByAltText

Opciók

Lásd még

getByLabelText

Opciók

Lásd még

getByPlaceholder

Opciók

Lásd még

getByText

Opciók

Lásd még

getByTitle

Opciók

Lásd még

getByTestId

Opciók

Lásd még

Metódusok

click

dblClick

tripleClick

clear

hover

unhover

fill

dropTo

selectOptions

screenshot

query

element

elements

all