コマンド

コマンドは、サーバー上の関数を呼び出し、その結果をブラウザに返す機能です。Vitestは、ブラウザテストで使用できるいくつかの組み込みコマンドを提供しています。

組み込みコマンド

ファイル処理

ブラウザテストでファイルを処理するには、readFile、writeFile、removeFile APIを使用できます。Vitest 3.2以降、すべてのパスはプロジェクトルート（手動でオーバーライドしない限り、process.cwd()）を基準に解決されます。以前は、パスはテストファイルを基準に解決されていました。

デフォルトでは、Vitestはutf-8エンコーディングを使用しますが、オプションでオーバーライドできます。

TIP

このAPIは、セキュリティ上の理由からserver.fsの制限に従います。

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

const { readFile, writeFile, removeFile } = server.commands;

it('handles files', async () => {
  const file = './test.txt';

  await writeFile(file, 'hello world');
  const content = await readFile(file);

  expect(content).toBe('hello world');

  await removeFile(file);
});

CDPセッション

Vitestは、@vitest/browser/contextからエクスポートされたcdpメソッドを介して、生のChrome Devtools Protocolへのアクセスを提供します。これは主に、ライブラリの作者がその上にツールを構築する際に役立ちます。

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

const input = document.createElement('input');
document.body.appendChild(input);
input.focus();

await cdp().send('Input.dispatchKeyEvent', {
  type: 'keyDown',
  text: 'a',
});

expect(input).toHaveValue('a');

WARNING

CDPセッションはplaywrightプロバイダーでのみ機能し、chromiumブラウザを使用している場合にのみ機能します。詳細については、PlaywrightのCDPSessionドキュメントを参照してください。

カスタムコマンド

browser.commands設定オプションを介して独自のコマンドを追加することもできます。ライブラリを開発している場合は、プラグイン内のconfigフックを介してそれらを提供できます。

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

const myCustomCommand: BrowserCommand<[arg1: string, arg2: string]> = (
  { testPath, provider },
  arg1,
  arg2
) => {
  if (provider.name === 'playwright') {
    console.log(testPath, arg1, arg2);
    return { someValue: true };
  }

  throw new Error(`provider ${provider.name} is not supported`);
};

export default function BrowserCommands(): Plugin {
  return {
    name: 'vitest:custom-commands',
    config() {
      return {
        test: {
          browser: {
            commands: {
              myCustomCommand,
            },
          },
        },
      };
    },
  };
}

その後、@vitest/browser/contextからインポートして、テスト内で呼び出すことができます。

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

test('custom command works correctly', async () => {
  const result = await commands.myCustomCommand('test1', 'test2');
  expect(result).toEqual({ someValue: true });
});

// if you are using TypeScript, you can augment the module
declare module '@vitest/browser/context' {
  interface BrowserCommands {
    myCustomCommand: (
      arg1: string,
      arg2: string
    ) => Promise<{
      someValue: true;
    }>;
  }
}

WARNING

カスタム関数は、同じ名前の場合、組み込み関数をオーバーライドします。

カスタム`playwright`コマンド

Vitestは、コマンドコンテキストにいくつかのplaywright固有のプロパティを公開しています。

pageは、テストiframeを含む完全なページを参照します。これはオーケストレーターHTMLであり、機能を損なわないよう、ほとんど触れるべきではありません。
frameは、テスターのFrameを解決する非同期メソッドです。pageと同様のAPIを持っていますが、一部のメソッドはサポートしていません。要素をクエリする必要がある場合は、より安定して高速なcontext.iframeを使用することを推奨します。
iframeは、ページ上の他の要素をクエリするために使用されるFrameLocatorです。
contextは、一意のBrowserContextを参照します。

import { BrowserCommand } from 'vitest/node';

export const myCommand: BrowserCommand<[string, number]> = async (
  ctx,
  arg1: string,
  arg2: number
) => {
  if (ctx.provider.name === 'playwright') {
    const element = await ctx.iframe.findByRole('alert');
    const screenshot = await element.screenshot();
    // do something with the screenshot
    return difference;
  }
};

TIP

TypeScriptを使用している場合は、セットアップファイルまたは設定ファイルで@vitest/browser/providers/playwrightを参照して、設定、userEvent、およびpageオプションでオートコンプリートを取得することを忘れないでください。

/// <reference types="@vitest/browser/providers/playwright" />

カスタム`webdriverio`コマンド

Vitestは、コンテキストオブジェクトにいくつかのwebdriverio固有のプロパティを公開しています。

browserはWebdriverIO.Browser APIです。

Vitestは、コマンドが呼び出される前にbrowser.switchToFrameを呼び出すことで、webdriverコンテキストをテストiframeに自動的に切り替えます。そのため、$および$$メソッドはオーケストレーターではなくiframe内の要素を参照しますが、非webdriver APIは引き続き親フレームのコンテキストを参照します。

TIP

TypeScriptを使用している場合は、セットアップファイルまたは設定ファイルで@vitest/browser/providers/webdriverioを参照して、オートコンプリートを取得することを忘れないでください。

/// <reference types="@vitest/browser/providers/webdriverio" />

コマンド ​

組み込みコマンド ​

ファイル処理 ​

CDPセッション ​

カスタムコマンド ​

カスタムplaywrightコマンド ​

カスタムwebdriverioコマンド ​