API du Contexte

Vitest expose un module de contexte via le point d'entrée @vitest/browser/context. À partir de la version 2.0, il offre un ensemble d'utilitaires qui peuvent s'avérer utiles dans vos tests.

userEvent

TIP

L'API userEvent est expliquée en détail dans API d'Interactivité.

/**
 * Gestionnaire pour les interactions utilisateur. Le support est assuré par le fournisseur de navigateur (`playwright` ou `webdriverio`).
 * Si utilisé avec le fournisseur `preview`, utilise en repli des événements simulés via `@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

Cette API est expliquée en détail dans API de Commandes.

/**
 * Commandes disponibles pour le navigateur.
 * Un raccourci vers `server.commands`.
 */
export const commands: BrowserCommands;

page

L'export page fournit des utilitaires pour interagir avec la page actuelle.

WARNING

Bien qu'il expose certains utilitaires de l'objet page de Playwright, ce n'est pas le même objet. Étant donné que le contexte du navigateur est évalué dans le navigateur, vos tests n'ont pas accès à l'objet page de Playwright, car ce dernier s'exécute sur le serveur.

Utilisez l'API de Commandes si vous avez besoin d'accéder à l'objet page de Playwright.

export const page: {
  /**
   * Modifie la taille de la zone d'affichage de l'iframe.
   */
  viewport(width: number, height: number): Promise<void>;
  /**
   * Effectue une capture d'écran de l'iframe de test ou d'un élément spécifique.
   * @returns Renvoie le chemin vers le fichier de capture d'écran, ou le chemin et la chaîne base64.
   */
  screenshot(
    options: Omit<ScreenshotOptions, 'base64'> & { base64: true }
  ): Promise<{
    path: string;
    base64: string;
  }>;
  screenshot(options?: ScreenshotOptions): Promise<string>;
  /**
   * Étend l'objet `page` par défaut en y ajoutant des méthodes personnalisées.
   */
  extend(methods: Partial<BrowserPage>): BrowserPage;
  /**
   * Encapsule un élément HTML dans un `Locator`. Lors de la recherche d'éléments, c'est toujours cet élément qui sera retourné.
   */
  elementLocator(element: Element): Locator;

  /**
   * API des Locators. Voir sa documentation pour plus de détails.
   */
  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

L'API getBy* est expliquée dans l'API des Locators.

ATTENTION 3.2.0+

Notez que screenshot retournera toujours une chaîne base64 si save est défini sur false. Le path est également ignoré dans ce cas.

cdp

L'export cdp renvoie la session actuelle du protocole Chrome DevTools. Il est principalement utile aux auteurs de bibliothèques pour construire des outils basés sur celui-ci.

WARNING

La session CDP ne fonctionne qu'avec le fournisseur playwright et uniquement lors de l'utilisation du navigateur chromium. Vous pouvez en savoir plus à ce sujet dans la documentation de Playwright sur CDPSession.

export const cdp: () => CDPSession;

server

L'export server représente l'environnement Node.js où le serveur Vitest est en cours d'exécution. Il est principalement utile pour le débogage ou pour limiter vos tests en fonction de l'environnement.

export const server: {
  /**
   * Plateforme sur laquelle le serveur Vitest est en cours d'exécution.
   * Identique à l'appel de `process.platform` sur le serveur.
   */
  platform: Platform;
  /**
   * Version d'exécution du serveur Vitest.
   * Identique à l'appel de `process.version` sur le serveur.
   */
  version: string;
  /**
   * Nom du fournisseur de navigateur.
   */
  provider: string;
  /**
   * Nom du navigateur actuel.
   */
  browser: string;
  /**
   * Commandes disponibles pour le navigateur.
   */
  commands: BrowserCommands;
  /**
   * Configuration de test sérialisée.
   */
  config: SerializedConfig;
};