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 的详细信息请参见命令 API。

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

page

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

WARNING

虽然它提供了一些 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 在 Locators API 中有解释。

警告 3.2.0+

请注意，如果 save 设置为 false，screenshot 将始终返回 base64 字符串。 在这种情况下，path 也将被忽略。

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