@vitest/browser 2.0.4 → 2.1.0-beta.1

package/aria-role.d.ts

@@ -0,0 +1,96 @@
+type ARIAWidgetRole =
+    | "button"
+    | "checkbox"
+    | "gridcell"
+    | "link"
+    | "menuitem"
+    | "menuitemcheckbox"
+    | "menuitemradio"
+    | "option"
+    | "progressbar"
+    | "radio"
+    | "scrollbar"
+    | "searchbox"
+    | "slider"
+    | "spinbutton"
+    | "switch"
+    | "tab"
+    | "tabpanel"
+    | "textbox"
+    | "treeitem";
+
+type ARIACompositeWidgetRole =
+    | "combobox"
+    | "grid"
+    | "listbox"
+    | "menu"
+    | "menubar"
+    | "radiogroup"
+    | "tablist"
+    | "tree"
+    | "treegrid";
+
+type ARIADocumentStructureRole =
+    | "application"
+    | "article"
+    | "blockquote"
+    | "caption"
+    | "cell"
+    | "columnheader"
+    | "definition"
+    | "deletion"
+    | "directory"
+    | "document"
+    | "emphasis"
+    | "feed"
+    | "figure"
+    | "generic"
+    | "group"
+    | "heading"
+    | "img"
+    | "insertion"
+    | "list"
+    | "listitem"
+    | "math"
+    | "meter"
+    | "none"
+    | "note"
+    | "paragraph"
+    | "presentation"
+    | "row"
+    | "rowgroup"
+    | "rowheader"
+    | "separator"
+    | "strong"
+    | "subscript"
+    | "superscript"
+    | "table"
+    | "term"
+    | "time"
+    | "toolbar"
+    | "tooltip";
+
+type ARIALandmarkRole =
+    | "banner"
+    | "complementary"
+    | "contentinfo"
+    | "form"
+    | "main"
+    | "navigation"
+    | "region"
+    | "search";
+
+type ARIALiveRegionRole = "alert" | "log" | "marquee" | "status" | "timer";
+
+type ARIAWindowRole = "alertdialog" | "dialog";
+
+type ARIAUncategorizedRole = "code";
+
+export type ARIARole =
+    | ARIAWidgetRole
+    | ARIACompositeWidgetRole
+    | ARIADocumentStructureRole
+    | ARIALandmarkRole
+    | ARIALiveRegionRole
+    | ARIAWindowRole
+    | ARIAUncategorizedRole;

package/context.d.ts

@@ -1,4 +1,5 @@
-import type { ResolvedConfig } from 'vitest'
+import type { SerializedConfig } from 'vitest'
+import { ARIARole } from './aria-role'
 
 export type BufferEncoding =
   | 'ascii'
@@ -24,9 +25,9 @@ export interface CDPSession {
 }
 
 export interface ScreenshotOptions {
-  element?: Element
+  element?: Element | Locator
   /**
-   * Path relative to the `screenshotDirectory` in the test config.
+   * Path relative to the current test file.
    */
   path?: string
   /**
@@ -49,6 +50,14 @@ export interface BrowserCommands {
 }
 
 export interface UserEvent {
+  /**
+   * Creates a new user event instance. This is useful if you need to keep the
+   * state of keyboard to press and release buttons correctly.
+   *
+   * **Note:** Unlike `@testing-library/user-event`, the default `userEvent` instance
+   * from `@vitest/browser/context` is created once, not every time its methods are called!
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api.html#userevent-setup}
+   */
   setup: () => UserEvent
   /**
    * Click on an element. Uses provider's API under the hood and supports all its options.
@@ -56,21 +65,21 @@ export interface UserEvent {
    * @see {@link https://webdriver.io/docs/api/element/click/} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/convenience/#click} testing-library API
    */
-  click: (element: Element, options?: UserEventClickOptions) => Promise<void>
+  click: (element: Element | Locator, options?: UserEventClickOptions) => Promise<void>
   /**
    * Triggers a double click event on an element. Uses provider's API under the hood.
    * @see {@link https://playwright.dev/docs/api/class-locator#locator-dblclick} Playwright API
    * @see {@link https://webdriver.io/docs/api/element/doubleClick/} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/convenience/#dblClick} testing-library API
    */
-  dblClick: (element: Element, options?: UserEventDoubleClickOptions) => Promise<void>
+  dblClick: (element: Element | Locator, options?: UserEventDoubleClickOptions) => Promise<void>
   /**
    * Triggers a triple click event on an element. Uses provider's API under the hood.
    * @see {@link https://playwright.dev/docs/api/class-locator#locator-click} Playwright API: using `click` with `clickCount: 3`
    * @see {@link https://webdriver.io/docs/api/browser/actions/} WebdriverIO API: using actions api with `move` plus three `down + up + pause` events in a row
    * @see {@link https://testing-library.com/docs/user-event/convenience/#tripleclick} testing-library API
    */
-  tripleClick: (element: Element, options?: UserEventTripleClickOptions) => Promise<void>
+  tripleClick: (element: Element | Locator, options?: UserEventTripleClickOptions) => Promise<void>
   /**
    * Choose one or more values from a select element. Uses provider's API under the hood.
    * If select doesn't have `multiple` attribute, only the first value will be selected.
@@ -92,7 +101,7 @@ export interface UserEvent {
    */
   selectOptions: (
     element: Element,
-    values: HTMLElement | HTMLElement[] | string | string[],
+    values: HTMLElement | HTMLElement[] | Locator | Locator[] | string | string[],
     options?: UserEventSelectOptions,
   ) => Promise<void>
   /**
@@ -103,7 +112,7 @@ export interface UserEvent {
    * await userEvent.keyboard('foo') // translates to: f, o, o
    * await userEvent.keyboard('{{a[[') // translates to: {, a, [
    * await userEvent.keyboard('{Shift}{f}{o}{o}') // translates to: Shift, f, o, o
-   * @see {@link https://playwright.dev/docs/api/class-locator#locator-press} Playwright API
+   * @see {@link https://playwright.dev/docs/api/class-keyboard} Playwright API
    * @see {@link https://webdriver.io/docs/api/browser/keys} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/keyboard} testing-library API
    */
@@ -111,6 +120,7 @@ export interface UserEvent {
   /**
    * Types text into an element. Uses provider's API under the hood.
    * **Supports** [user-event `keyboard` syntax](https://testing-library.com/docs/user-event/keyboard) (e.g., `{Shift}`) even with `playwright` and `webdriverio` providers.
+   * This method can be significantly slower than `userEvent.fill`, so it should be used only when necessary.
    * @example
    * await userEvent.type(input, 'foo') // translates to: f, o, o
    * await userEvent.type(input, '{{a[[') // translates to: {, a, [
@@ -119,17 +129,17 @@ export interface UserEvent {
    * @see {@link https://webdriver.io/docs/api/browser/action#key-input-source} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/utility/#type} testing-library API
    */
-  type: (element: Element, text: string, options?: UserEventTypeOptions) => Promise<void>
+  type: (element: Element | Locator, text: string, options?: UserEventTypeOptions) => Promise<void>
   /**
    * Removes all text from an element. Uses provider's API under the hood.
    * @see {@link https://playwright.dev/docs/api/class-locator#locator-clear} Playwright API
    * @see {@link https://webdriver.io/docs/api/element/clearValue} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/utility/#clear} testing-library API
    */
-  clear: (element: Element) => Promise<void>
+  clear: (element: Element | Locator) => Promise<void>
   /**
    * Sends a `Tab` key event. Uses provider's API under the hood.
-   * @see {@link https://playwright.dev/docs/api/class-locator#locator-press} Playwright API
+   * @see {@link https://playwright.dev/docs/api/class-keyboard} Playwright API
    * @see {@link https://webdriver.io/docs/api/element/keys} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/convenience/#tab} testing-library API
    */
@@ -140,7 +150,7 @@ export interface UserEvent {
    * @see {@link https://webdriver.io/docs/api/element/moveTo/} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/convenience/#hover} testing-library API
    */
-  hover: (element: Element, options?: UserEventHoverOptions) => Promise<void>
+  hover: (element: Element | Locator, options?: UserEventHoverOptions) => Promise<void>
   /**
    * Moves cursor position to the body element. Uses provider's API under the hood.
    * By default, the cursor position is in the center (in webdriverio) or in some visible place (in playwright)
@@ -149,7 +159,7 @@ export interface UserEvent {
    * @see {@link https://webdriver.io/docs/api/element/moveTo/} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/convenience/#hover} testing-library API
    */
-  unhover: (element: Element, options?: UserEventHoverOptions) => Promise<void>
+  unhover: (element: Element | Locator, options?: UserEventHoverOptions) => Promise<void>
   /**
    * Fills an input element with text. This will remove any existing text in the input before typing the new text.
    * Uses provider's API under the hood.
@@ -162,13 +172,13 @@ export interface UserEvent {
    * @see {@link https://webdriver.io/docs/api/element/setValue} WebdriverIO API
    * @see {@link https://testing-library.com/docs/user-event/utility/#type} testing-library API
    */
-  fill: (element: Element, text: string, options?: UserEventFillOptions) => Promise<void>
+  fill: (element: Element | Locator, text: string, options?: UserEventFillOptions) => Promise<void>
   /**
    * Drags a source element on top of the target element. This API is not supported by "preview" provider.
    * @see {@link https://playwright.dev/docs/api/class-frame#frame-drag-and-drop} Playwright API
    * @see {@link https://webdriver.io/docs/api/element/dragAndDrop/} WebdriverIO API
    */
-  dragAndDrop: (source: Element, target: Element, options?: UserEventDragAndDropOptions) => Promise<void>
+  dragAndDrop: (source: Element | Locator, target: Element | Locator, options?: UserEventDragAndDropOptions) => Promise<void>
 }
 
 export interface UserEventFillOptions {}
@@ -179,6 +189,199 @@ export interface UserEventDoubleClickOptions {}
 export interface UserEventTripleClickOptions {}
 export interface UserEventDragAndDropOptions {}
 
+export interface LocatorOptions {
+  /**
+   * Whether to find an exact match: case-sensitive and whole-string. Default to false. Ignored when locating by a
+   * regular expression. Note that exact match still trims whitespace.
+   */
+  exact?: boolean
+}
+
+export interface LocatorByRoleOptions extends LocatorOptions {
+  /**
+   * Should checked elements (set by `aria-checked` or `<input type="checkbox"/>`) be included or not. By default, the filter is not applied.
+   *
+   * See [`aria-checked`](https://www.w3.org/TR/wai-aria-1.2/#aria-checked) for more information
+   */
+  checked?: boolean
+  /**
+   * Should disabled elements be included or not. By default, the filter is not applied. Note that unlike other attributes, `disable` state is inherited.
+   *
+   * See [`aria-disabled`](https://www.w3.org/TR/wai-aria-1.2/#aria-disabled) for more information
+   */
+  disabled?: boolean
+  /**
+   * Should expanded elements be included or not. By default, the filter is not applied.
+   *
+   * See [`aria-expanded`](https://www.w3.org/TR/wai-aria-1.2/#aria-expanded) for more information
+   */
+  expanded?: boolean
+  /**
+   * Should elements that are [normally excluded](https://www.w3.org/TR/wai-aria-1.2/#tree_exclusion) from the accessibility tree be queried. By default, only non-hidden elements are matched by role selector.
+   *
+   * Note that roles `none` and `presentation` are always included.
+   * @default false
+   */
+  includeHidden?: boolean
+  /**
+   * A number attribute that is usually present for `heading`, `listitem`, `row`, `treeitem` roles with default values for `<h1>-<h6>` elements. By default, the filter is not applied.
+   *
+   * See [`aria-level`](https://www.w3.org/TR/wai-aria-1.2/#aria-level) for more information
+   */
+  level?: number
+  /**
+   * Option to match the [accessible name](https://w3c.github.io/accname/#dfn-accessible-name). By default, matching is
+   * case-insensitive and searches for a substring, use `exact` to control this behavior.
+   */
+  name?: string | RegExp
+  /**
+   * Should pressed elements be included or not. By default, the filter is not applied.
+   *
+   * See [`aria-pressed`](https://www.w3.org/TR/wai-aria-1.2/#aria-pressed) for more information
+   */
+  pressed?: boolean
+  /**
+   * Should selected elements be included or not. By default, the filter is not applied.
+   *
+   * See [`aria-selected`](https://www.w3.org/TR/wai-aria-1.2/#aria-selected) for more information
+   */
+  selected?: boolean
+}
+
+interface LocatorScreenshotOptions extends Omit<ScreenshotOptions, 'element'> {}
+
+interface LocatorSelectors {
+  /**
+   * Creates a way to locate an element by its [ARIA role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles), [ARIA attributes](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes) and [accessible name](https://developer.mozilla.org/en-US/docs/Glossary/Accessible_name).
+   * @see {@link https://vitest.dev/guide/browser/locators#getbyrole}
+   */
+  getByRole(role: ARIARole | ({} & string), options?: LocatorByRoleOptions): Locator
+  /**
+   * @see {@link https://vitest.dev/guide/browser/locators#getbylabeltext}
+   */
+  getByLabelText(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * Creates a locator capable of finding an element with an `alt` attribute that matches the text. Unlike testing-library's implementation, Vitest will match any element that has an `alt` attribute.
+   * @see {@link https://vitest.dev/guide/browser/locators#getbyalttext}
+   */
+  getByAltText(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * Creates a locator capable of finding an element that has the specified placeholder text. Vitest will match any element that has a matching `placeholder` attribute, not just `input`.
+   * @see {@link https://vitest.dev/guide/browser/locators#getbyplaceholder}
+   */
+  getByPlaceholder(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * Creates a locator capable of finding an element that contains the specified text. The text will be matched against TextNode's [`nodeValue`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeValue) or input's value if the type is `button` or `reset`.
+   * Matching by text always normalizes whitespace, even with exact match.
+   * For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.
+   * @see {@link https://vitest.dev/guide/browser/locators#getbytext}
+   */
+  getByText(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * Creates a locator capable of finding an element that has the specified `title` attribute. Unlike testing-library's `getByTitle`, Vitest cannot find `title` elements within an SVG.
+   * @see {@link https://vitest.dev/guide/browser/locators#getbytitle}
+   */
+  getByTitle(text: string | RegExp, options?: LocatorOptions): Locator
+  /**
+   * Creates a locator capable of finding an element that matches the specified test id attribute. You can configure the attribute name with [`browser.locators.testIdAttribute`](/config/#browser-locators-testidattribute).
+   * @see {@link https://vitest.dev/guide/browser/locators#getbytestid}
+   */
+  getByTestId(text: string | RegExp): Locator
+}
+
+export interface Locator extends LocatorSelectors {
+  /**
+   * Click on an element. You can use the options to set the cursor position.
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-click}
+   */
+  click(options?: UserEventClickOptions): Promise<void>
+  /**
+   * Triggers a double click event on an element. You can use the options to set the cursor position.
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-dblclick}
+   */
+  dblClick(options?: UserEventDoubleClickOptions): Promise<void>
+  /**
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-tripleclick}
+   */
+  tripleClick(options?: UserEventTripleClickOptions): Promise<void>
+  /**
+   * Clears the input element content
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-clear}
+   */
+  clear(): Promise<void>
+  /**
+   * Moves the cursor position to the selected element
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-hover}
+   */
+  hover(options?: UserEventHoverOptions): Promise<void>
+  /**
+   * This works the same as `locator.hover`, but moves the cursor to the `document.body` element instead.
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-unhover}
+   */
+  unhover(options?: UserEventHoverOptions): Promise<void>
+  /**
+   * Sets the value of the current `input`, `textarea` or `conteneditable` element.
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-fill}
+   */
+  fill(text: string, options?: UserEventFillOptions): Promise<void>
+  /**
+   * Drags the current element to the target location.
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-dropto}
+   */
+  dropTo(target: Locator, options?: UserEventDragAndDropOptions): Promise<void>
+  /**
+   * Choose one or more values from a `<select>` element.
+   * @see {@link https://vitest.dev/guide/browser/interactivity-api#userevent-selectoptions}
+   */
+  selectOptions(
+    values: HTMLElement | HTMLElement[] | Locator | Locator[] | string | string[],
+    options?: UserEventSelectOptions,
+  ): Promise<void>
+
+  /**
+   * Make a screenshot of an element matching the locator.
+   * @see {@link https://vitest.dev/guide/browser/locators#screenshot}
+   */
+  screenshot(options: Omit<LocatorScreenshotOptions, 'base64'> & { base64: true }): Promise<{
+    path: string
+    base64: string
+  }>
+  screenshot(options?: LocatorScreenshotOptions): Promise<string>
+
+  /**
+   * Returns an element matching the selector.
+   *
+   * - If multiple elements match the selector, an error is thrown.
+   * - If no elements match the selector, an error is thrown.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#element}
+   */
+  element(): Element
+  /**
+   * Returns an array of elements matching the selector.
+   *
+   * If no elements match the selector, an empty array is returned.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#elements}
+   */
+  elements(): Element[]
+  /**
+   * Returns an element matching the selector.
+   *
+   * - If multiple elements match the selector, an error is thrown.
+   * - If no elements match the selector, returns `null`.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#query}
+   */
+  query(): Element | null
+  /**
+   * Wraps an array of `.elements()` matching the selector in a new `Locator`.
+   *
+   * @see {@link https://vitest.dev/guide/browser/locators#all}
+   */
+  all(): Locator[]
+}
+
 export interface UserEventTabOptions {
   shift?: boolean
 }
@@ -225,6 +428,10 @@ export const server: {
    * @see {@link https://vitest.dev/guide/browser/commands}
    */
   commands: BrowserCommands
+  /**
+   * Serialized test config.
+   */
+  config: SerializedConfig
 }
 
 /**
@@ -241,11 +448,7 @@ export const userEvent: UserEvent
  */
 export const commands: BrowserCommands
 
-export interface BrowserPage {
-  /**
-   * Serialized test config.
-   */
-  config: ResolvedConfig
+export interface BrowserPage extends LocatorSelectors {
   /**
    * Change the size of iframe's viewport.
    */
@@ -259,6 +462,15 @@ export interface BrowserPage {
     base64: string
   }>
   screenshot(options?: ScreenshotOptions): Promise<string>
+  /**
+   * Extend default `page` object with custom methods.
+   */
+  extend(methods: Partial<BrowserPage>): BrowserPage
+  /**
+   * Wrap an HTML element in a `Locator`. When querying for elements, the search will always return this element.
+   * @see {@link https://vitest.dev/guide/browser/locators}
+   */
+  elementLocator(element: Element): Locator
 }
 
 export const page: BrowserPage

package/dist/client/.vite/manifest.json

@@ -4,7 +4,7 @@
     "name": "preload-helper"
   },
   "orchestrator.html": {
-    "file": "__vitest_browser__/orchestrator-CNOAigTE.js",
+    "file": "__vitest_browser__/orchestrator-BObhEEvc.js",
     "name": "orchestrator",
     "src": "orchestrator.html",
     "isEntry": true,
@@ -13,7 +13,7 @@
     ]
   },
   "tester/tester.html": {
-    "file": "__vitest_browser__/tester-BSSDPE9E.js",
+    "file": "__vitest_browser__/tester-CRcWWhrn.js",
     "name": "tester",
     "src": "tester/tester.html",
     "isEntry": true,