Lokátorok

A lokátor egy vagy több elem reprezentációja. Minden lokátort egy szelektornak nevezett string definiál. A Vitest absztrahálja a szelektorok közvetlen használatát azáltal, hogy kényelmes metódusokat biztosít, amelyek a háttérben generálják azokat.

A lokátor API a Playwright lokátorainak egy elágazását, az Ivya nevű könyvtárat használja. A Vitest azonban ezt az API-t minden szolgáltató számára biztosítja, nem csak a Playwright számára.

TIP

Ez az oldal az API használatát tárgyalja. A lokátorok és használatuk jobb megértéséhez olvassa el a Playwright "Locators" dokumentációját.

getByRole

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

Egy elem megtalálására szolgál az ARIA szerepe, ARIA attribútumai és hozzáférhető neve alapján.

TIP

Ha csak egyetlen elemet kérdez le a getByText('A név') paranccsal, gyakran jobb a getByRole(expectedRole, { name: 'A név' }) használata. A hozzáférhető név alapú keresés nem helyettesíti a többi keresési módot, mint például a *ByAltText vagy a *ByTitle. Bár a hozzáférhető név megegyezhet ezekkel az attribútumokkal, nem helyettesíti ezen attribútumok 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álhat 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 egyezés alapján kerülnek illesztésre, anélkül, hogy öröklődnének az ARIA szerephierarchiából. Ennek eredményeként egy szuperosztály szerep, mint például a checkbox lekérdezése nem fogja tartalmazni az alosztály szereppel rendelkező elemeket, mint például a switch.

Alapértelmezés szerint sok szemantikai HTML elemnek van szerepe; például az <input type="radio"> "radio" szerepet kap. A nem szemantikai HTML elemeknek nincs szerepe; a <div> és <span> hozzáadott szemantika nélkül null értékkel tér vissza. A role attribútum szemantikát biztosíthat.

Az ARIA irányelvek erősen ellenjavallják, hogy role vagy aria-* attribútumokkal adjunk szerepeket olyan beépített elemeknek, amelyeknek már van implicit szerepük.

Opciók

exact: boolean
A name pontosan egyezik-e: kis- és nagybetű érzékeny és teljes egyezésű. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a name reguláris kifejezés. Vegye figyelembe, hogy a pontos egyezés továbbra is eltávolítja a felesleges szóközöket.
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
A bejelölt elemeket (az aria-checked vagy <input type="checkbox"/> által beállított) tartalmazza-e a keresés. Alapértelmezés szerint a szűrő nincs alkalmazva.
További információkért lásd az aria-checked részt.
tsx
```
<>
  <button role="checkbox" aria-checked="true" />
  <input type="checkbox" checked />
</>;

page.getByRole('checkbox', { checked: true }); // ✅
page.getByRole('checkbox', { checked: false }); // ❌
```
disabled: boolean
A letiltott elemeket tartalmazza-e a keresés. Alapértelmezés szerint a szűrő nincs alkalmazva. Vegye figyelembe, hogy más attribútumokkal ellentétben a letiltott állapot öröklődik.
További információkért lásd az aria-disabled részt.
tsx
```
<input type="text" disabled />;

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

expanded: boolean

A kibontott elemeket tartalmazza-e a keresés. Alapértelmezés szerint a szűrő nincs alkalmazva.

További információkért lásd az aria-expanded részt.

tsx

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

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

includeHidden: boolean
Lekérdezi-e azokat az elemeket is, amelyek általában ki vannak zárva az akadálymentességi fából. Alapértelmezés szerint a szerepválasztó csak a nem rejtett elemeket illeszti.
Vegye figyelembe, 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 a heading, listitem, row, treeitem szerepeknél van jelen, és alapértelmezett értékekkel rendelkezik a <h1>-<h6> elemek számára. Alapértelmezés szerint a szűrő nincs alkalmazva.
További információkért lásd az aria-level részt.
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

Hozzáférhető név. Alapértelmezés szerint az illesztés kis- és nagybetű érzéketlen, és részleges egyezést keres. Az exact opcióval szabályozható ez a viselkedés.

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
A lenyomott elemeket tartalmazza-e a keresés. Alapértelmezés szerint a szűrő nincs alkalmazva.
További információkért lásd az aria-pressed részt.
tsx
```
<button aria-pressed="true">👍</button>;

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

selected: boolean

A kiválasztott elemeket tartalmazza-e a keresés. Alapértelmezés szerint a szűrő nincs alkalmazva.

További információkért lásd az aria-selected részt.

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 megtalálja azokat az elemeket, amelyek alt attribútuma illeszkedik a szöveghez. 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
A text pontosan egyezik-e: kis- és nagybetű érzékeny és teljes egyezésű. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Vegye figyelembe, hogy a pontos egyezés továbbra is eltávolítja a felesleges szóközöket.

Lásd még

testing-library ByAltText

getByLabelText

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

Létrehoz egy lokátort, amely megtalálja a hozzárendelt címkével rendelkező elemeket.

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

html

// for/htmlFor kapcsolat a címke és az űrlap elem id-je 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" />

// Burkoló címkék
<label>Username <input /></label>

// Burkoló címkék, ahol a címke szövege egy másik gyermekelemben van
<label>
  <span>Username</span>
  <input />
</label>

// aria-label attribútumok
// Vigyázat, mert ez nem egy olyan címke, amelyet a felhasználók láthatnak az oldalon, ezért 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
A text pontosan egyezik-e: kis- és nagybetű érzékeny és teljes egyezésű. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Vegye figyelembe, hogy a pontos egyezés továbbra is eltávolítja a felesleges szóközöket.

Lásd még

testing-library ByLabelText

getByPlaceholder

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

Létrehoz egy lokátort, amely megtalálja a megadott placeholder attribútummal rendelkező elemeket. 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 inkább a címkére támaszkodni a getByLabelText használatával, mint egy helyőrzőre.

Opciók

exact: boolean
A text pontosan egyezik-e: kis- és nagybetű érzékeny és teljes egyezésű. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Vegye figyelembe, hogy a pontos egyezés továbbra is eltávolítja a felesleges szóközöket.

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 elemek értékével egyezik, ha a típus button vagy reset. A szöveg alapú illesztés mindig normalizálja a szóközöket, 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ökké alakít, és figyelmen kívül hagyja az elején és végén lévő szóközöket.

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, például gombot vagy beviteli mezőt kell megtalálnia, használja inkább a getByRole metódust.

Opciók

exact: boolean
A text pontosan egyezik-e: kis- és nagybetű érzékeny és teljes egyezésű. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Vegye figyelembe, hogy a pontos egyezés továbbra is eltávolítja a felesleges szóközöket.

Lásd még

testing-library ByText

getByTitle

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

Létrehoz egy lokátort, amely megtalálja a megadott title attribútummal rendelkező elemeket. A testing-library getByTitle funkciójától eltérően a Vitest nem talál title elemeket SVG-n belül.

tsx

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

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

Opciók

exact: boolean
A text pontosan egyezik-e: kis- és nagybetű érzékeny és teljes egyezésű. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Vegye figyelembe, hogy a pontos egyezés továbbra is eltávolítja a felesleges szóközöket.

Lásd még

testing-library ByTitle

getByTestId

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

Létrehoz egy lokátort, amely megtalálja a megadott tesztazonosító attribútumhoz illeszkedő elemeket. Az attribútum nevét a browser.locators.testIdAttribute segítségével állíthatja be.

tsx

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

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

WARNING

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

Opciók

exact: boolean
A text pontosan egyezik-e: kis- és nagybetű érzékeny és teljes egyezésű. Alapértelmezés szerint kikapcsolva. Ez az opció figyelmen kívül marad, ha a text reguláris kifejezés. Vegye figyelembe, hogy a pontos egyezés továbbra is eltávolítja a felesleges szóközöket.

Lásd még

testing-library ByTestId

nth

function nth(index: number): Locator;

Ez a metódus egy új lokátort ad vissza, amely csak egy adott indexet illeszt egy több elemet tartalmazó lekérdezési eredményen belül. Nulla alapú, az nth(0) az első elemet választja ki. Az elements()[n]-től eltérően az nth lokátor addig próbálkozik, amíg az elem meg nem található.

html

<div aria-label="one"><input /><input /><input /></div>
<div aria-label="two"><input /></div>

tsx

page.getByRole('textbox').nth(0); // ✅
page.getByRole('textbox').nth(4); // ❌

TIP

Mielőtt az nth-t használná, hasznos lehet láncolt lokátorokat használni a keresés szűkítésére. Néha nincs jobb módja a megkülönböztetésnek, mint az elem pozíciója; bár ez instabilitáshoz vezethet, jobb, mint a semmi.

tsx

page.getByLabel('two').getByRole('input'); // ✅ jobb alternatíva a page.getByRole('textbox').nth(3) helyett
page.getByLabel('one').getByRole('input'); // ❌ túl kétértelmű
page.getByLabel('one').getByRole('input').nth(1); // ✅ pragmatikus kompromisszum

first

function first(): Locator;

Ez a metódus egy új lokátort ad vissza, amely csak egy több elemet tartalmazó lekérdezési eredmény első indexét illeszti. Ez az nth(0) rövidített alakja.

html

<input /> <input /> <input />

tsx

page.getByRole('textbox').first(); // ✅

last

function last(): Locator;

Ez a metódus egy új lokátort ad vissza, amely csak egy több elemet tartalmazó lekérdezési eredmény utolsó indexét illeszti. Ez az nth(-1) rövidített alakja.

html

<input /> <input /> <input />

tsx

page.getByRole('textbox').last(); // ✅

and

function and(locator: Locator): Locator;

Ez a metódus egy új lokátort hoz létre, amely a szülő és a megadott lokátorhoz is illeszkedik. A következő példa egy gombot talál egy adott címmel:

page.getByRole('button').and(page.getByTitle('Subscribe'));

or

function or(locator: Locator): Locator;

Ez a metódus egy új lokátort hoz létre, amely illeszkedik az egyik vagy mindkét lokátorhoz.

WARNING

Vegye figyelembe, hogy ha a lokátor több elemet talál, egy másik metódus hívása hibát dobhat, ha egyetlen elemet vár:

tsx

<>
  <button>Click me</button>
  <a href="https://vitest.dev">Error happened!</a>
</>;

page.getByRole('button').or(page.getByRole('link')).click(); // ❌ több elemet illeszt

filter

function filter(options: LocatorOptions): Locator;

Ez a metódus az opciók szerint szűkíti a lokátort, például szöveg alapján történő szűréssel. Láncolható több szűrő alkalmazásához.

has

Típus: Locator

Ez az opció szűkíti a szelektorot, hogy csak azokat az elemeket találja meg, amelyek más, a megadott lokátorhoz illeszkedő elemeket tartalmaznak. Például ezzel a HTML-lel:

html

<article>
  <div>Vitest</div>
</article>
<article>
  <div>Rolldown</div>
</article>

Szűkíthetjük a lokátort, hogy csak azt az article elemet találja meg, amelyben a Vitest szöveg található:

page.getByRole('article').filter({ has: page.getByText('Vitest') }); // ✅

WARNING

A megadott lokátornak (a példában page.getByText('Vitest')) a szülő lokátorhoz (a példában page.getByRole('article')) képest relatívnak kell lennie. A lekérdezés a szülő lokátortól kezdődik, nem a dokumentum gyökerétől kezdve.

Ez azt jelenti, hogy nem adhat át olyan lokátort, amely a szülő lokátoron kívüli elemet kérdez le:

page.getByText('Vitest').filter({ has: page.getByRole('article') }); // ❌

Ez a példa hibát fog eredményezni, mert az article elem a Vitest szöveget tartalmazó elemen kívül van.

TIP

Ez a metódus láncolható az elem további szűkítéséhez:

page
  .getByRole('article')
  .filter({ has: page.getByRole('button', { name: 'delete row' }) })
  .filter({ has: page.getByText('Vitest') });

hasNot

Típus: Locator

Ez az opció szűkíti a szelektorot, hogy csak azokat az elemeket találja meg, amelyek nem tartalmaznak más, a megadott lokátorhoz illeszkedő elemeket. Például ezzel a HTML-lel:

html

<article>
  <div>Vitest</div>
</article>
<article>
  <div>Rolldown</div>
</article>

Szűkíthetjük a lokátort, hogy csak azt az article elemet találja meg, amely nem tartalmazza a Rolldown szöveget.

page.getByRole('article').filter({ hasNot: page.getByText('Rolldown') }); // ✅
page.getByRole('article').filter({ hasNot: page.getByText('Vitest') }); // ❌

WARNING

Vegye figyelembe, hogy a megadott lokátor a szülőhöz képest kerül lekérdezésre, nem a dokumentum gyökeréhez képest, akárcsak a has opció.

hasText

Típus: string | RegExp

Ez az opció szűkíti a szelektorot, hogy csak azokat az elemeket találja meg, amelyek valahol belül tartalmazzák a megadott szöveget. Ha string kerül átadásra, az illesztés kis- és nagybetű érzéketlen, és részleges egyezést keres.

html

<article>
  <div>Vitest</div>
</article>
<article>
  <div>Rolldown</div>
</article>

Mindkét lokátor ugyanazt az elemet megtalálja, mert a keresés kis- és nagybetű érzéketlen:

page.getByRole('article').filter({ hasText: 'Vitest' }); // ✅
page.getByRole('article').filter({ hasText: 'Vite' }); // ✅

hasNotText

Típus: string | RegExp

Ez az opció szűkíti a szelektorot, hogy csak azokat az elemeket találja meg, amelyek valahol belül nem tartalmazzák a megadott szöveget. Ha string kerül átadásra, az illesztés kis- és nagybetű érzéketlen, és részleges egyezést keres.

Metódusok

Minden metódus aszinkron, és await kulcsszóval kell használni. A Vitest 3 óta a tesztek hibát eredményeznek, ha egy metódust nem várnak meg.

click

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

Egy elemre kattint. Az opciók segítségével beállítható a kurzor pozíciója.

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

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

További információ a userEvent.click oldalon

dblClick

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

Kettős kattintást szimulál egy elemen. Az opciók segítségével beállítható a kurzor pozíciója.

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

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

További információ a userEvent.dblClick oldalon

tripleClick

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

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

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

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

További információ a userEvent.tripleClick oldalon

clear

function clear(options?: UserEventClearOptions): Promise<void>;

Kitörli a beviteli mező tartalmát.

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

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

További információ a userEvent.clear oldalon

hover

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

A kurzort a kiválasztott elem fölé viszi.

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

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

További információ a userEvent.hover oldalon

unhover

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

Ez hasonlóan működik, mint a locator.hover, de a kurzort a document.body elemre mozgatja.

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

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

További információ a userEvent.unhover oldalon

fill

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

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

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

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

További információ a userEvent.fill oldalon

dropTo

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

Az aktuális elemet a célhelyre húzza és ott elengedi.

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

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

await paris.dropTo(france);

További információ a userEvent.dragAndDrop oldalon

selectOptions

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

Kiválaszt 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ó a userEvent.selectOptions oldalon

screenshot

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

Képernyőképet készít a lokátor szelektora által megtalált elemről.

A képernyőképek mentési útvonalát a path opcióval adhatja meg, 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) értéket használja. A fájl és a teszt neve alapján határozza meg a képernyőképek fájlútvonalát.

Ha a képernyőképek tartalmát is szeretné, megadhatja a base64: true opciót, hogy azt a képernyőképek mentési útvonalával együtt adja vissza.

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, // base64 stringet is visszaad
});
// path - a képernyőképek teljes útvonala
// bas64 - a képernyőképek base64 kódolású stringje

FIGYELEM 3.2.0+

Vegye figyelembe, hogy a screenshot mindig base64 stringet fog visszaadni, ha a save értéke false. Ebben az esetben a path is figyelmen kívül marad.

query

function query(): Element | null;

Ez a metódus egyetlen elemet ad vissza, amely megfelel a lokátor szelektorához, vagy null értéket, ha nem található elem.

Ha több elem illeszkedik a szelektorhoz, ez a metódus hibát fog eredményezni. Használja az .elements() metódust, ha az összes illeszkedő DOM elemet, vagy az .all() metódust, ha a szelektorhoz illeszkedő lokátorok tömbjére van szüksége.

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:

// több elemet ad vissza
page.getByText('Hello').query(); // ❌
page.getByText(/^Hello/).query(); // ❌

element

function element(): Element;

Ez a metódus egyetlen elemet ad vissza, amely illeszkedik a lokátor szeletorához.

Ha nincs elem, amely illeszkedik a szelektorhoz, hiba keletkezik. Fontolja meg a .query() használatát, ha csak az elem létezését kell ellenőriznie.

Ha több elem illeszkedik a szelektorhoz, hiba keletkezik. Használja az .elements() metódust, ha az összes illeszkedő DOM elemet, vagy az .all() metódust, ha a szelektorhoz illeszkedő lokátorok tömbjére van szüksége.

TIP

Ez a metódus hasznos lehet, ha külső könyvtárnak szeretné átadni. 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:

// több elemet ad vissza
page.getByText('Hello').element(); // ❌
page.getByText(/^Hello/).element(); // ❌

// nem ad vissza elemet
page.getByText('Hello USA').element(); // ❌

elements

function elements(): Element[];

Ez a metódus egy tömböt ad vissza a lokátor szelektora által illesztett elemekből.

Ez a függvény soha nem eredményez hibát. Ha nincsenek elemek, amelyek megfelelnek a szelektorhoz, 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').element(); // ✅ [HTMLElement, HTMLElement]
page.getByText('Hello USA').elements(); // ✅ []

all

function all(): Locator[];

Ez a metódus új lokátorok tömbjét adja vissza, amelyek megfelelnek a szelektorhoz.

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

Lásd a locator.elements() metódust

Tulajdonságok

selector

A selector egy string, amelyet a böngésző szolgáltatója fog használni az elem megtalálásához. A Playwright playwright lokátor szintaxist használ, míg a preview és a webdriverio CSS-t.

DANGER

Ezt a stringet nem javasolt közvetlenül használni a tesztkódban. A selector stringet csak a Commands API-val való munka során javasolt használni:

import type { BrowserCommand } from 'vitest/node';

const test: BrowserCommand<string> = function test(context, selector) {
  // playwright
  await context.iframe.locator(selector).click();
  // webdriverio
  await context.browser.$(selector).click();
};

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

test('works correctly', async () => {
  await commands.test(page.getByText('Hello').selector); // ✅
  // a vitest automatikusan stringgé bontja
  await commands.test(page.getByText('Hello')); // ✅
});

Egyéni lokátorok 3.2.0+ haladó

Kiterjesztheti a beépített lokátor API-t lokátorgyár objektumok definiálásával. Ezek a metódusok a page objektumon és bármely létrehozott lokátoron metódusként létezni fognak.

Ezek a lokátorok hasznosak lehetnek, ha a beépített lokátorok nem elegendőek. Például, ha egyéni keretrendszert használ a felhasználói felületéhez.

A lokátorgyárnak egy szelektor stringet vagy magát a lokátort vissza kell adnia.

TIP

A szelektor szintaxisa megegyezik a Playwright lokátorokéval. Kérjük, olvassa el útmutatójukat, hogy jobban megértse a velük való munkát.

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

locators.extend({
  getByArticleTitle(title) {
    return `[data-title="${title}"]`;
  },
  getByArticleCommentsCount(count) {
    return `.comments :text("${count} comments")`;
  },
  async previewComments() {
    // hozzáférhet az aktuális lokátorhoz a "this" segítségével
    // vigyázat, ha a metódust a `page` objektumon meghívták, a `this` a `page` lesz,
    // nem a lokátor!
    if (this !== page) {
      await this.click();
    }
    // ...
  },
});

// ha typescriptet használ, kiterjesztheti a LocatorSelectors interfészt
// az automatikus kiegészítéshez a locators.extend, page.* és locator.* metódusokban
declare module '@vitest/browser/context' {
  interface LocatorSelectors {
    // ha az egyéni metódus stringet ad vissza, lokátorrá alakul át
    // ha bármi mást ad vissza, akkor az változatlanul kerül visszaadásra
    getByArticleTitle(title: string): Locator;
    getByArticleCommentsCount(count: number): Locator;

    // a Vitest ígéretet ad vissza, és nem próbálja lokátorrá konvertálni
    previewComments(this: Locator): Promise<void>;
  }
}

Ha a metódust a globális page objektumon meghívják, akkor a szelektor az egész oldalra vonatkozik. Az alábbi példában a getByArticleTitle minden olyan elemet megtalál, amelynek data-title attribútuma a title értékű. Ha azonban a metódust a lokátoron hívják meg, akkor az a lokátorra lesz korlátozva.

html

<article data-title="Hello, World!">
  Hello, World!
  <button id="comments">2 comments</button>
</article>

<article data-title="Hello, Vitest!">
  Hello, Vitest!
  <button id="comments">0 comments</button>
</article>

const articles = page.getByRole('article');
const worldArticle = page.getByArticleTitle('Hello, World!'); // ✅
const commentsElement = worldArticle.getByArticleCommentsCount(2); // ✅
const wrongCommentsElement = worldArticle.getByArticleCommentsCount(0); // ❌
const wrongElement = page.getByArticleTitle('No Article!'); // ❌

await commentsElement.previewComments(); // ✅
await wrongCommentsElement.previewComments(); // ❌

Lokátorok ​

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 ​

nth ​

first ​

last ​

and ​

or ​

filter ​

has ​

hasNot ​

hasText ​

hasNotText ​

Metódusok ​

click ​

dblClick ​

tripleClick ​

clear ​

hover ​

unhover ​

fill ​

dropTo ​

selectOptions ​

screenshot ​

query ​

element ​

elements ​

all ​

Tulajdonságok ​

selector ​

Egyéni lokátorok 3.2.0+ haladó ​

Lokátorok

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

nth

first

last

and

or

filter

has

hasNot

hasText

hasNotText

Metódusok

click

dblClick

tripleClick

clear

hover

unhover

fill

dropTo

selectOptions

screenshot

query

element

elements

all

Tulajdonságok

selector

Egyéni lokátorok 3.2.0+ haladó