ロケーター 2.1.0+

ロケーターは、要素または複数要素を表現するものです。すべてのロケーターは、セレクターと呼ばれる文字列によって定義されます。Vitest は、これらのセレクターを内部的に生成する便利なメソッドを提供することで、このセレクターの扱いを抽象化しています。

ロケーター API は、Playwright のロケーターをフォークした Ivya を使用しています。ただし、Vitest はこの API をすべてのプロバイダーに提供します。

getByRole

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

要素を ARIA ロール、ARIA 属性、およびアクセシブルネームで特定する方法を提供します。

TIP

getByText('The name') で単一の要素をクエリする場合、多くの場合、getByRole(expectedRole, { name: 'The name' }) を使用する方が良いです。アクセシブルネームによるクエリは、*ByAltText や *ByTitle などの他のクエリを置き換えるものではありません。アクセシブルネームはこれらの属性と等しい場合がありますが、これらの属性の機能を置き換えるものではありません。

次の DOM 構造を考えてみましょう。

html

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

各要素をその暗黙の役割で特定できます。

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

ロールは、ARIA ロール階層から継承することなく、文字列の等価性によって一致します。その結果、checkbox のようなスーパークラスロールをクエリしても、switch のようなサブクラスロールを持つ要素は含まれません。

デフォルトでは、HTML の多くのセマンティック要素にはロールがあります。たとえば、<input type="radio"> には「radio」ロールがあります。HTML の非セマンティック要素にはロールがありません。セマンティクスが追加されていない <div> と <span> は null を返します。role 属性はセマンティクスを提供します。

ARIA ガイドラインでは、すでに暗黙的なロールを持つ組み込み要素に role または aria-* 属性を介してロールを提供することは強く推奨されていません。

オプション

exact: boolean
name が正確に一致するかどうかを指定します。大文字と小文字を区別し、文字列全体を一致させます。デフォルトでは無効です。name が正規表現の場合、このオプションは無視されます。正確な一致でも空白はトリムされることに注意してください。
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
チェック済み要素 (aria-checked または <input type="checkbox"/> で設定) を含めるかどうかを指定します。デフォルトではフィルターは適用されません。
詳細については、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
無効化された要素を含めるかどうかを指定します。デフォルトではフィルターは適用されません。他の属性とは異なり、disable 状態は継承されることに注意してください。
詳細については、aria-disabled を参照してください。
tsx
```
<input type="text" disabled />;

page.getByRole('textbox', { disabled: true }); // ✅
page.getByRole('textbox', { disabled: false }); // ❌
```
expanded: boolean
展開済み要素を含めるかどうかを指定します。デフォルトではフィルターは適用されません。
詳細については、aria-expanded を参照してください。
tsx
```
<a aria-expanded="true" href="example.com">
  Link
</a>;

page.getByRole('link', { expanded: true }); // ✅
page.getByRole('link', { expanded: false }); // ❌
```
includeHidden: boolean
アクセシビリティツリーから通常除外される要素をクエリするかどうかを指定します。デフォルトでは、非表示でない要素のみがロールセレクターによって一致します。
ロール none および presentation は常に含まれることに注意してください。
tsx
```
<button style="display: none" />;

page.getByRole('button'); // ❌
page.getByRole('button', { includeHidden: false }); // ❌
page.getByRole('button', { includeHidden: true }); // ✅
```
level: number
heading、listitem、row、treeitem ロールに通常存在する数値属性で、<h1>-<h6> 要素のデフォルト値があります。デフォルトではフィルターは適用されません。
詳細については、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
アクセシブルネームを指定します。デフォルトでは、大文字小文字を区別せず、部分文字列を検索します。この動作を制御するには、exact オプションを使用します。
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
押下された要素を含めるかどうかを指定します。デフォルトではフィルターは適用されません。
詳細については、aria-pressed を参照してください。
tsx
```
<button aria-pressed="true">👍</button>;

page.getByRole('button', { pressed: true }); // ✅
page.getByRole('button', { pressed: false }); // ❌
```
selected: boolean
選択済み要素を含めるかどうかを指定します。デフォルトではフィルターは適用されません。
詳細については、aria-selected を参照してください。
tsx
```
<button role="tab" aria-selected="true">
  Vue
</button>;

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

参照

getByAltText

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

テキストに一致する alt 属性を持つ要素を見つけることができるロケーターを作成します。testing-library の実装とは異なり、Vitest は一致する alt 属性を持つ任意の要素に一致します。

tsx

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

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

オプション

exact: boolean
text が正確に一致するかどうかを指定します。大文字と小文字を区別し、文字列全体を一致させます。デフォルトでは無効です。text が正規表現の場合、このオプションは無視されます。正確な一致でも空白はトリムされることに注意してください。

参照

testing-library の ByAltText

getByLabelText

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

関連付けられたラベルを持つ要素を見つけることができるロケーターを作成します。

page.getByLabelText('Username') ロケーターは、以下の例のすべての入力を見つけます。

html

<!-- for/htmlFor relationship between label and form element id -->
<label for="username-input">Username</label>
<input id="username-input" />

<!-- The aria-labelledby attribute with form elements -->
<label id="username-label">Username</label>
<input aria-labelledby="username-label" />

<!-- Wrapper labels -->
<label>Username <input /></label>

<!-- Wrapper labels where the label text is in another child element -->
<label>
  <span>Username</span>
  <input />
</label>

<!-- aria-label attributes -->
<!-- これはユーザーがページ上で見ることができるラベルではないため、注意が必要です。 -->
<!-- そのため、入力の目的は視覚的なユーザーにとって明らかである必要があります。 -->
<input aria-label="Username" />

オプション

exact: boolean
text が正確に一致するかどうかを指定します。大文字と小文字を区別し、文字列全体を一致させます。デフォルトでは無効です。text が正規表現の場合、このオプションは無視されます。正確な一致でも空白はトリムされることに注意してください。

参照

testing-library の ByLabelText

getByPlaceholder

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

指定された placeholder 属性を持つ要素を見つけることができるロケーターを作成します。Vitest は、input だけでなく、一致する placeholder 属性を持つ任意の要素に一致します。

tsx

<input placeholder="Username" />;

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

WARNING

一般的に、プレースホルダーよりも getByLabelText を使用してラベルに依存する方が優れています。

オプション

exact: boolean
text が正確に一致するかどうかを指定します。大文字と小文字を区別し、文字列全体を一致させます。デフォルトでは無効です。text が正規表現の場合、このオプションは無視されます。正確な一致でも空白はトリムされることに注意してください。

参照

testing-library の ByPlaceholderText

getByText

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

指定されたテキストを含む要素を見つけることができるロケーターを作成します。テキストは、TextNode の nodeValue またはタイプが button または reset の場合は入力の値と一致します。テキストによる一致は、正確な一致でも常に空白を正規化します。たとえば、複数のスペースを 1 つに変換し、改行をスペースに変換し、先頭と末尾の空白を無視します。

tsx

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

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

TIP

このロケーターは、非インタラクティブな要素を見つけるのに役立ちます。ボタンや入力などのインタラクティブな要素を見つける必要がある場合は、getByRole を優先してください。

オプション

exact: boolean
text が正確に一致するかどうかを指定します。大文字と小文字を区別し、文字列全体を一致させます。デフォルトでは無効です。text が正規表現の場合、このオプションは無視されます。正確な一致でも空白はトリムされることに注意してください。

参照

testing-library の ByText

getByTitle

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

指定された title 属性を持つ要素を見つけることができるロケーターを作成します。testing-library の getByTitle とは異なり、Vitest は SVG 内の title 要素を見つけることができません。

tsx

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

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

オプション

exact: boolean
text が正確に一致するかどうかを指定します。大文字と小文字を区別し、文字列全体を一致させます。デフォルトでは無効です。text が正規表現の場合、このオプションは無視されます。正確な一致でも空白はトリムされることに注意してください。

参照

testing-library の ByTitle

getByTestId

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

指定されたテスト ID 属性に一致する要素を見つけることができるロケーターを作成します。属性名は browser.locators.testIdAttribute で設定できます。

tsx

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

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

WARNING

他のロケーターがユースケースに合わない場合にのみ、これを使用することをお勧めします。data-testid 属性を使用することは、ソフトウェアがどのように使用されるかとは似ていないため、可能であれば避けるべきです。

オプション

exact: boolean
text が正確に一致するかどうかを指定します。大文字と小文字を区別し、文字列全体を一致させます。デフォルトでは無効です。text が正規表現の場合、このオプションは無視されます。正確な一致でも空白はトリムされることに注意してください。

参照

testing-library の ByTestId

メソッド

すべてのメソッドは非同期であり、待機する必要があります。Vitest 2.2 以降、メソッドが待機されない場合、テストは失敗します。

click

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

要素をクリックします。オプションを使用してカーソル位置を設定できます。

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

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

userEvent.click の詳細はこちら

dblClick

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

要素でダブルクリックイベントをトリガーします。オプションを使用してカーソル位置を設定できます。

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

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

userEvent.dblClick の詳細はこちら

tripleClick

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

要素でトリプルクリックイベントをトリガーします。ブラウザ API には tripleclick がないため、このメソッドは 3 つのクリックイベントを連続して発生させます。

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

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

userEvent.tripleClick の詳細はこちら

clear

function clear(): Promise<void>;

入力要素の内容をクリアします。

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

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

userEvent.clear の詳細はこちら

hover

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

カーソル位置を指定した要素に移動します。

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

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

userEvent.hover の詳細はこちら

unhover

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

これは locator.hover と同じように機能しますが、カーソルを document.body 要素に移動します。

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

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

userEvent.unhover の詳細はこちら

fill

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

現在の input、textarea、または conteneditable 要素の値を設定します。

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

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

userEvent.fill の詳細はこちら

dropTo

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

現在の要素をターゲット位置にドラッグします。

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

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

await paris.dropTo(france);

userEvent.dragAndDrop の詳細はこちら

selectOptions

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

<select> 要素から 1 つ以上の値を選択します。

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

userEvent.selectOptions の詳細はこちら

screenshot

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

ロケーターのセレクターに一致する要素のスクリーンショットを作成します。

path オプションを使用して、スクリーンショットの保存場所を指定できます。これは現在のテストファイルからの相対パスです。path オプションが設定されていない場合、Vitest はデフォルトで browser.screenshotDirectory (__screenshot__ がデフォルト) を使用し、ファイル名とテスト名を使用してスクリーンショットのファイルパスを決定します。

スクリーンショットの内容も必要な場合は、base64: true を指定して、スクリーンショットが保存されるファイルパスと一緒に返すことができます。

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 文字列も返す
});
// path - スクリーンショットへのフルパス
// bas64 - スクリーンショットの base64 エンコードされた文字列

query

function query(): Element | null;

このメソッドは、ロケーターのセレクターに一致する単一の要素を返します。要素が見つからない場合は null を返します。

複数の要素がセレクターに一致する場合、このメソッドはエラーをスローします。一致する全てのDOM要素が必要な場合は .elements() を使用し、セレクターに一致するロケーター配列が必要な場合は .all() を使用します。

次の DOM 構造を考えてみましょう。

html

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

これらのロケーターはエラーをスローしません。

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

これらのロケーターはエラーをスローします。

// 複数の要素を返す
page.getByText('Hello').query(); // ❌
page.getByText(/^Hello/).query(); // ❌

element

function element(): Element;

このメソッドは、ロケーターのセレクターに一致する単一の要素を返します。

セレクターに一致する要素がない場合、エラーがスローされます。要素が存在するかどうかを確認するだけでよい場合は、.query() の使用を検討してください。

複数の要素がセレクターに一致する場合、エラーがスローされます。一致する全てのDOM要素が必要な場合は .elements() を使用し、セレクターに一致するロケーター配列が必要な場合は .all() を使用します。

TIP

このメソッドは、外部ライブラリに渡す際に役立ちます。ロケーターが expect.element と一緒に使用されるたびに、アサーションが再試行されるたびに自動的に呼び出されます。

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

次の DOM 構造を考えてみましょう。

html

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

これらのロケーターはエラーをスローしません。

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

これらのロケーターはエラーをスローします。

// 複数の要素を返す
page.getByText('Hello').element(); // ❌
page.getByText(/^Hello/).element(); // ❌

// 要素を返さない
page.getByText('Hello USA').element(); // ❌

elements

function elements(): Element[];

このメソッドは、ロケーターのセレクターに一致する要素配列を返します。

この関数はエラーを発生させません。セレクターに一致する要素がない場合、このメソッドは空配列を返します。

次の DOM 構造を考えてみましょう。

html

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

これらのロケーターは必ず成功します。

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

このメソッドは、セレクターに一致する新規ロケーター配列を返します。

内部的には、このメソッドは .elements を呼び出し、page.elementLocator を使用してすべての要素をラップします。

locator.elements() を参照

ロケーター 2.1.0+ ​

getByRole ​

オプション ​

参照 ​

getByAltText ​

オプション ​

参照 ​

getByLabelText ​

オプション ​

参照 ​

getByPlaceholder ​

オプション ​

参照 ​

getByText ​

オプション ​

参照 ​

getByTitle ​

オプション ​

参照 ​

getByTestId ​

オプション ​

参照 ​

メソッド ​

click ​

dblClick ​

tripleClick ​

clear ​

hover ​

unhover ​

fill ​

dropTo ​

selectOptions ​

screenshot ​

query ​

element ​

elements ​

all ​

ロケーター 2.1.0+

getByRole

オプション

参照

getByAltText

オプション

参照

getByLabelText

オプション

参照

getByPlaceholder

オプション

参照

getByText

オプション

参照

getByTitle

オプション

参照

getByTestId

オプション

参照

メソッド

click

dblClick

tripleClick

clear

hover

unhover

fill

dropTo

selectOptions

screenshot

query

element

elements

all