命令 API

命令是一種函式，它會在伺服器端呼叫另一個函式，並將結果傳回瀏覽器。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 開發者工具協定 (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" />

命令 API ​

內建命令 ​

檔案處理 ​

CDP 會話 ​

自訂命令 ​

自訂 playwright 命令 ​

自訂 webdriverio 命令 ​