Assertion API

Vitest standardně poskytuje širokou škálu DOM asercí, převzatých z knihovny @testing-library/jest-dom s přidanou podporou pro lokátory a vestavěnou funkcí opakování.

Podpora TypeScriptu

Pokud používáte TypeScript nebo chcete mít správné typové informace v expect, ujistěte se, že někde odkazujete na @vitest/browser/context. Pokud jste z něj nikdy neimportovali, můžete přidat reference komentář do libovolného souboru, na který se vztahuje váš tsconfig.json:

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

Testy v prohlížeči mohou selhávat nepravidelně kvůli jejich asynchronní povaze. Proto je důležité mít způsob, jak zajistit, že aserce uspějí, i když je podmínka zpožděna (například časovým limitem, síťovým požadavkem nebo animací). Pro tento účel Vitest standardně poskytuje opakovatelné aserce prostřednictvím API expect.poll a expect.element:

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

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

  // Tím se vytvoří lokátor, který se pokusí najít prvek při volání kterékoli z jeho metod.
  // Toto volání samo o sobě nekontroluje existenci prvku.
  const banner = page.getByRole('alert', {
    name: /error/i,
  });

  // Vitest poskytuje `expect.element` s vestavěným opakováním.
  // Bude opakovaně kontrolovat, zda prvek existuje v DOM a zda obsah `element.textContent` je roven "Error!", dokud se všechny podmínky nesplní.
  await expect.element(banner).toHaveTextContent('Error!');
});

Doporučujeme vždy používat expect.element při práci s lokátory page.getBy*, abyste snížili kolísavost testů. Všimněte si, že expect.element přijímá volitelný druhý argument:

interface ExpectPollOptions {
  // Interval opakování aserce (v milisekundách)
  // Výchozí hodnota je konfigurační volba "expect.poll.interval"
  interval?: number;
  // Časový limit pro opakování aserce (v milisekundách)
  // Výchozí hodnota je konfigurační volba "expect.poll.timeout"
  timeout?: number;
  // Zpráva zobrazená při selhání aserce
  message?: string;
}

TIP

expect.element je zkratka pro expect.poll(() => element) a funguje naprosto stejně.

toHaveTextContent a všechny ostatní aserce jsou stále k dispozici u běžného expect bez vestavěného mechanismu opakovatelnosti:

// selže okamžitě, pokud .textContent není `'Error!'`
expect(banner).toHaveTextContent('Error!');

toBeDisabled

function toBeDisabled(): Promise<void>;

Umožňuje zkontrolovat, zda je prvek uživatelsky zakázán.

Shoda nastane, pokud je prvek ovládacím prvkem formuláře a atribut disabled je buď přímo na tomto prvku, nebo je prvek potomkem formulářového prvku s atributem disabled.

Všimněte si, že pouze standardní ovládací prvky, jako jsou HTML button, input, select, textarea, option, optgroup, lze zakázat nastavením atributu "disabled". Atribut "disabled" na jiných prvcích je ignorován, pokud se nejedná o uživatelsky definovaný prvek.

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

Umožňuje zkontrolovat, zda prvek není uživatelsky zakázán.

Funguje jako not.toBeDisabled(). Použijte tento matcher, abyste se vyhnuli dvojité negaci ve svých testech.

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

To vám umožní ověřit, zda prvek nemá žádný viditelný obsah. Ignoruje komentáře, ale neprojde, pokud prvek obsahuje prázdné znaky.

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

Ověřte, zda je prvek přítomen v dokumentu.

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

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

WARNING

Tento matcher nenajde odpojené DOM prvky. Prvek musí být přidán do dokumentu, aby byl nalezen pomocí toBeInTheDocument. Pokud chcete hledat v odpojeném prvku, použijte prosím: toContainElement.

toBeInvalid

function toBeInvalid(): Promise<void>;

To vám umožní zkontrolovat, zda je prvek momentálně neplatný.

Prvek je neplatný, pokud má atribut aria-invalid bez hodnoty nebo s hodnotou "true", nebo pokud je výsledek checkValidity() false.

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

To vám umožní zkontrolovat, zda je prvek formuláře momentálně povinný.

Prvek je povinný, pokud má atribut required nebo aria-required="true".

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

To vám umožní zkontrolovat, zda je hodnota prvku aktuálně platná.

Prvek je platný, pokud nemá atribut aria-invalid nebo má hodnotu atributu "false". Výsledek checkValidity() musí být také true, pokud se jedná o prvek formuláře.

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

To vám umožní zkontrolovat, zda je prvek aktuálně viditelný pro uživatele.

Prvek je považován za viditelný, pokud má neprázdný ohraničující obdélník a nemá vypočtený CSS styl visibility:hidden.

Všimněte si, že podle této definice:

• Prvky s nulovou velikostí nejsou považovány za viditelné.
• Prvky s display:none nejsou považovány za viditelné.
• Prvky s opacity:0 jsou považovány za viditelné.

Chcete-li zkontrolovat, zda je viditelný alespoň jeden prvek ze seznamu, použijte locator.first().

// Konkrétní prvek je viditelný.
await expect.element(page.getByText('Welcome')).toBeVisible();

// Alespoň jedna položka v seznamu je viditelná.
await expect.element(page.getByTestId('todo-item').first()).toBeVisible();

// Alespoň jeden ze dvou prvků je viditelný, případně oba.
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>;

To vám umožní ověřit, zda prvek obsahuje jiný prvek jako potomka.

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

Ověřte, zda řetězec reprezentující HTML prvek je obsažen v jiném prvku. Řetězec by měl obsahovat platné HTML, nikoli neúplné HTML.

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

// Toto jsou platná použití
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 />');

// Toto nebude fungovat
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

Je pravděpodobné, že tento matcher nepotřebujete používat. Doporučujeme testovat z pohledu toho, jak uživatel v prohlížeči vnímá aplikaci. Proto se nedoporučuje testovat proti konkrétní struktuře DOM.

Může být užitečné v situacích, kdy testovaný kód vykresluje HTML, které bylo získáno z externího zdroje, a chcete ověřit, že tento HTML kód byl použit zamýšleným způsobem.

Neměl by být používán ke kontrole struktury DOM, kterou ovládáte. Místo toho použijte prosím toContainElement.

toHaveAccessibleDescription

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

To vám umožní ověřit, že prvek má očekávaný přístupný popis.

Můžete předat přesný řetězec očekávaného přístupného popisu, nebo můžete provést částečnou shodu předáním regulárního výrazu, nebo použitím expect.stringContaining nebo expect.stringMatching.

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

To vám umožní ověřit, že prvek má očekávanou přístupnou chybovou zprávu.

Můžete předat přesný řetězec očekávané přístupné chybové zprávy. Alternativně můžete provést částečnou shodu předáním regulárního výrazu nebo použitím expect.stringContaining nebo expect.stringMatching.

<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"
/>

// Vstupy s platnými chybovými zprávami
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!');

// Vstupy bez platných chybových zpráv
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>;

To vám umožní ověřit, že prvek má očekávaný přístupný název. Je to užitečné například pro ověření, že prvky formuláře a tlačítka jsou správně označeny.

Můžete předat přesný řetězec očekávaného přístupného názvu, nebo můžete provést částečnou shodu předáním regulárního výrazu, nebo použitím expect.stringContaining nebo expect.stringMatching.

<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" />

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

To vám umožní zkontrolovat, zda daný prvek má atribut. Můžete také volitelně zkontrolovat, zda atribut má specifickou očekávanou hodnotu nebo částečnou shodu pomocí expect.stringContaining nebo expect.stringMatching.

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

To vám umožní zkontrolovat, zda daný prvek má určité třídy v rámci svého atributu class. Musíte poskytnout alespoň jednu třídu, pokud neověřujete, že prvek nemá žádné třídy.

Seznam názvů tříd může obsahovat řetězce a regulární výrazy. Regulární výrazy jsou porovnávány s každou jednotlivou třídou v cílovém prvku a NEJSOU porovnávány s celou hodnotou atributu class jako celkem.

WARNING

Všimněte si, že nemůžete použít volbu exact: true, pokud jsou poskytnuty pouze regulární výrazy.

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

// ⚠️ regulární výraz se shoduje s jednotlivými třídami, nikoli s celým classListem
await expect.element(deleteButton).not.toHaveClass(/btn extra/);

// prvek má PŘESNĚ sadu tříd (v libovolném pořadí)
await expect.element(deleteButton).toHaveClass('btn-danger extra btn', {
  exact: true,
});
// pokud má více, než se očekávalo, selže
await expect.element(deleteButton).not.toHaveClass('btn-danger extra', {
  exact: true,
});

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

toHaveFocus

function toHaveFocus(): Promise<void>;

To vám umožní ověřit, zda má prvek fokus.

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

To vám umožní zkontrolovat, zda formulář nebo fieldset obsahuje ovládací prvky formuláře pro každý daný název se specifikovanou hodnotou.

TIP

Je důležité zdůraznit, že tento matcher lze vyvolat pouze na prvku form nebo fieldset.

To mu umožňuje využít vlastnost .elements ve form a fieldset k spolehlivému načtení všech ovládacích prvků formuláře uvnitř nich.

Tím se také zabrání možnosti, že uživatelé poskytnou kontejner, který obsahuje více než jeden form, čímž se smíchají ovládací prvky formuláře, které nejsou vzájemně propojeny a mohly by si dokonce navzájem odporovat.

Tento matcher abstrahuje zvláštnosti, s nimiž je hodnota ovládacího prvku formuláře získána v závislosti na typu ovládacího prvku formuláře. Například prvky <input> mají atribut value, ale prvky <select> nikoli. Zde je seznam všech pokrytých případů:

• Prvky <input type="number"> vrací hodnotu jako číslo, nikoli jako řetězec.
• Prvky <input type="checkbox">:
  • pokud je s daným atributem name pouze jeden, je považován za boolean, vrací true, pokud je zaškrtávací políčko zaškrtnuto, false, pokud není zaškrtnuto.
  • pokud je více než jedno zaškrtávací políčko se stejným atributem name, jsou všechny považovány kolektivně za jeden ovládací prvek formuláře, který vrací hodnotu jako pole obsahující všechny hodnoty vybraných zaškrtávacích políček v kolekci.
• Prvky <input type="radio"> jsou všechny seskupeny podle atributu name a taková skupina je považována za jeden ovládací prvek formuláře. Tento ovládací prvek formuláře vrací hodnotu jako řetězec odpovídající atributu value vybraného rádiového tlačítka ve skupině.
• Prvky <input type="text"> vrací hodnotu jako řetězec. To platí také pro prvky <input> s jakýmkoli jiným možným atributem type, který není explicitně pokryt v jiných pravidlech výše (např. search, email, date, password, hidden atd.)
• Prvky <select> bez atributu multiple vrací hodnotu jako řetězec odpovídající atributu value vybrané option, nebo undefined, pokud není vybrána žádná možnost.
• Prvky <select multiple> vrací hodnotu jako pole obsahující všechny hodnoty vybraných možností.
• Prvky <textarea> vrací svou hodnotu jako řetězec. Hodnota odpovídá jejich obsahu uzlu.

Výše uvedená pravidla usnadňují například přechod z použití jednoho výběrového ovládacího prvku na použití skupiny rádiových tlačítek. Nebo přechod z ovládacího prvku s vícenásobným výběrem na použití skupiny zaškrtávacích políček. Výsledná sada hodnot formuláře použitá tímto matcherem pro porovnání by byla stejná.

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

To vám umožní zkontrolovat, zda má určitý prvek aplikovány specifické CSS vlastnosti s konkrétními hodnotami. Shoduje se pouze tehdy, pokud má prvek aplikovány všechny očekávané vlastnosti, nikoli jen některé z nich.

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

To funguje také s pravidly, která jsou aplikována na prvek prostřednictvím názvu třídy, pro kterou jsou některá pravidla definována v aktuálně aktivním stylu v dokumentu. Platí obvyklá pravidla priority CSS.

toHaveTextContent

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

To vám umožní zkontrolovat, zda daný uzel má textový obsah. To podporuje prvky, ale také textové uzly a fragmenty.

Pokud je předán argument string, provede se částečná shoda s rozlišováním velkých a malých písmen s obsahem uzlu.

Pro provedení shody bez rozlišování velkých a malých písmen můžete použít RegExp s modifikátorem /i.

Pokud chcete shodovat celý obsah, můžete k tomu použít RegExp.

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

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

await expect.element(element).toHaveTextContent('Content');
// pro shodu celého obsahu
await expect.element(element).toHaveTextContent(/^Text Content$/);
// pro použití shody bez rozlišování velkých a malých písmen
await expect.element(element).toHaveTextContent(/content$/i);
await expect.element(element).not.toHaveTextContent('content');

toHaveValue

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

To vám umožní zkontrolovat, zda daný prvek formuláře má specifikovanou hodnotu. Přijímá prvky <input>, <select> a <textarea> s výjimkou <input type="checkbox"> a <input type="radio">, které lze smysluplně shodovat pouze pomocí toBeChecked nebo toHaveFormValues.

Přijímá také prvky s rolemi meter, progressbar, slider nebo spinbutton a kontroluje jejich atribut aria-valuenow (jako číslo).

Pro všechny ostatní prvky formuláře je hodnota shodována pomocí stejného algoritmu jako v toHaveFormValues.

<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

function toHaveDisplayValue(
  value: string | RegExp | (string | RegExp)[]
): Promise<void>;

To vám umožní zkontrolovat, zda daný prvek formuláře má specifikovanou zobrazenou hodnotu (tu, kterou uvidí koncový uživatel). Přijímá prvky <input>, <select> a <textarea> s výjimkou <input type="checkbox"> a <input type="radio">, které lze smysluplně shodovat pouze pomocí toBeChecked nebo toHaveFormValues.

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

To vám umožní zkontrolovat, zda je daný prvek zaškrtnutý. Přijímá input typu checkbox nebo radio a prvky s role checkbox, radio nebo switch s platným atributem aria-checked "true" nebo "false".

<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

function toBePartiallyChecked(): Promise<void>;

To vám umožní zkontrolovat, zda je daný prvek částečně zaškrtnutý. Přijímá input typu checkbox a prvky s role checkbox s aria-checked="mixed", nebo input typu checkbox s indeterminate nastaveným na true.

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

To vám umožní ověřit, že prvek má očekávanou roli.

To je užitečné v případech, kdy již máte přístup k prvku prostřednictvím jiného dotazu než samotné role a chcete provést další ověření týkající se jeho přístupnosti.

Role se může shodovat buď s explicitní rolí (prostřednictvím atributu role), nebo s implicitní rolí prostřednictvím implicitní sémantiky ARIA.

<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

Role jsou shodovány doslovně podle rovnosti řetězců, bez dědění z hierarchie rolí ARIA. V důsledku toho dotazování na roli nadtřídy, jako je checkbox, nebude zahrnovat prvky s rolí podtřídy, jako je switch.

Všimněte si také, že na rozdíl od testing-library Vitest ignoruje všechny vlastní role kromě první platné, podle chování Playwrightu:

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

To umožňuje zkontrolovat, že prvek má označení textu.

To je užitečné pro kontrolu, zda je text nebo část textu vybrána v rámci prvku. Prvek může být buď vstup typu text, textarea, nebo jakýkoli jiný prvek, který obsahuje text, jako je odstavec, span, div atd.

WARNING

Očekávaný výběr je řetězec, neumožňuje kontrolovat indexy označeného rozsahu.

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

// výběr potomka se vztahuje i na rodiče
range.selectNodeContents(getByTestId('child').element());
await expect.element(getByTestId('child')).toHaveSelection('selected');
await expect.element(getByTestId('parent')).toHaveSelection('selected');

// Výběr, který zahrnuje text od předchozího prvku, text rodiče před potomkem a část textu potomka.
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();

// Výběr, který zahrnuje část textu potomka, text rodiče po potomkovi a část textu dalšího prvku.
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');