上下文 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 在命令 API 中有详细解释。

/**
 * 浏览器可用的命令。
 * `server.commands` 的快捷方式。
 */
export const commands: BrowserCommands;

page

page 导出提供了与当前页面交互的实用工具。

WARNING

虽然它暴露了 Playwright 的 page 中的一些实用工具，但它与 Playwright 的 page 对象并不相同。由于浏览器上下文在浏览器中评估，你的测试无法访问 Playwright 的 page，因为它是在服务器上运行。

如果需要访问 Playwright 的 page 对象，请使用命令 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 在定位器 API 中有解释。

cdp

cdp 导出返回当前的 Chrome DevTools Protocol 会话。它主要对库作者在其之上构建工具很有用。

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