Context API

Vitest 透過 @vitest/browser/context 入口點公開了一個 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 的一些工具，但它並不是同一個物件。由於瀏覽器 Context 是在瀏覽器中評估的，您的測試無法存取 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 中有詳細說明。

警告 3.2.0+

請注意，如果 save 設定為 false，screenshot 將始終返回 base64 字串。 在這種情況下，path 也會被忽略。

cdp

cdp 匯出返回當前的 Chrome 開發者工具協定 (CDP) 工作階段。它主要用於函式庫作者在其之上建構工具。

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