Context API

Vitest 透過 @vitest/browser/context 進入點提供了一個上下文模組。截至 2.0 版，它公開了一小部分在測試中可能對您有用的工具。

userEvent

TIP

userEvent API 在互動性 API 中有詳細解釋。

/**
 * 用於使用者互動的處理器。其支援由瀏覽器提供者（`playwright` 或 `webdriverio`）實作。
 * 如果與 `preview` 提供者一起使用，則會回退至透過 `@testing-library/user-event` 模擬事件。
 * @experimental
 */
export const userEvent: {
  setup: () => UserEvent;
  cleanup: () => Promise<void>;
  click: (element: Element, options?: UserEventClickOptions) => Promise<void>;
  dblClick: (
    element: Element,
    options?: UserEventDoubleClickOptions
  ) => Promise<void>;
  tripleClick: (
    element: Element,
    options?: UserEventTripleClickOptions
  ) => Promise<void>;
  selectOptions: (
    element: Element,
    values: HTMLElement | HTMLElement[] | string | string[],
    options?: UserEventSelectOptions
  ) => Promise<void>;
  keyboard: (text: string) => Promise<void>;
  type: (
    element: Element,
    text: string,
    options?: UserEventTypeOptions
  ) => Promise<void>;
  clear: (element: Element) => Promise<void>;
  tab: (options?: UserEventTabOptions) => Promise<void>;
  hover: (element: Element, options?: UserEventHoverOptions) => Promise<void>;
  unhover: (element: Element, options?: UserEventHoverOptions) => Promise<void>;
  fill: (
    element: Element,
    text: string,
    options?: UserEventFillOptions
  ) => Promise<void>;
  dragAndDrop: (
    source: Element,
    target: Element,
    options?: UserEventDragAndDropOptions
  ) => Promise<void>;
};

commands

TIP

此 API 的詳細解釋請參閱 Commands API。

/**
 * 瀏覽器可用的指令。
 * `server.commands` 的快捷方式。
 */
export const commands: BrowserCommands;

page

page 匯出提供了與當前 page 互動的工具。

WARNING

儘管它公開了 Playwright page 的一些工具，但它並非相同的物件。由於瀏覽器上下文是在瀏覽器中評估的，您的測試無法存取 Playwright 的 page，因為後者是在伺服器上執行。

如果您需要存取 Playwright 的 page 物件，請使用 Commands API。

export const page: {
  /**
   * 變更 iframe 視埠的大小。
   */
  viewport(width: number, height: number): Promise<void>;
  /**
   * 擷取測試 iframe 或特定元素的螢幕截圖。
   * @returns 螢幕截圖檔案的路徑或路徑與 base64 編碼。
   */
  screenshot(
    options: Omit<ScreenshotOptions, 'base64'> & { base64: true }
  ): Promise<{
    path: string;
    base64: string;
  }>;
  screenshot(options?: ScreenshotOptions): Promise<string>;
  /**
   * 使用自訂方法擴充預設的 `page` 物件。
   */
  extend(methods: Partial<BrowserPage>): BrowserPage;
  /**
   * 將 HTML 元素包裝成 `Locator`。當查詢元素時，搜尋結果將始終返回此元素。
   */
  elementLocator(element: Element): Locator;

  /**
   * Locator API。更多詳細資訊請參閱其文件。
   */
  getByRole(role: ARIARole | string, options?: LocatorByRoleOptions): Locator;
  getByLabelText(text: string | RegExp, options?: LocatorOptions): Locator;
  getByTestId(text: string | RegExp): Locator;
  getByAltText(text: string | RegExp, options?: LocatorOptions): Locator;
  getByPlaceholder(text: string | RegExp, options?: LocatorOptions): Locator;
  getByText(text: string | RegExp, options?: LocatorOptions): Locator;
  getByTitle(text: string | RegExp, options?: LocatorOptions): Locator;
};

TIP

getBy* API 在 Locators API 中有解釋。

cdp

cdp 匯出會傳回當前的 Chrome 開發者工具協定會話。它主要對函式庫作者有用，以便在其基礎上建構工具。

WARNING

CDP 會話僅適用於 playwright 提供者，且僅在使用 chromium 瀏覽器時。您可以在 Playwright 的 CDPSession 文件中閱讀更多相關資訊。

export const cdp: () => CDPSession;

server

server 匯出代表 Vitest 伺服器正在執行的 Node.js 環境。它主要用於除錯，或根據環境限制您的測試。

export const server: {
  /**
   * Vitest 伺服器執行的平台。
   * 與在伺服器上呼叫 `process.platform` 的結果相同。
   */
  platform: Platform;
  /**
   * Vitest 伺服器的執行階段版本。
   * 與在伺服器上呼叫 `process.version` 的結果相同。
   */
  version: string;
  /**
   * 瀏覽器提供者的名稱。
   */
  provider: string;
  /**
   * 當前瀏覽器的名稱。
   */
  browser: string;
  /**
   * 瀏覽器可用的指令。
   */
  commands: BrowserCommands;
  /**
   * 序列化的測試組態。
   */
  config: SerializedConfig;
};