@vitest/browser 4.0.0-beta.1 → 4.0.0-beta.10

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2021-Present Vitest Team
+Copyright (c) 2021-Present VoidZero Inc. and Vitest contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,7 @@
 # @vitest/browser
 
-[Browser runner](https://vitest.dev/guide/browser/) for Vitest.
+[![NPM version](https://img.shields.io/npm/v/@vitest/browser?color=a1b858&label=)](https://www.npmjs.com/package/@vitest/browser)
 
-> ⚠️ This package is **experimental**. While this package will be released along with other packages, it will not follow SemVer for breaking changes until we mark it as ready.
+Running Vitest tests in the real browser.
 
-## Development Setup
-
-At project root:
-
-```bash
-cd test/browser
-# runs relevant tests for the browser mode
-# useful to confirm everything works fine
-pnpm test
-# runs tests as the browser mode
-# useful during development
-pnpm test-fixtures
-```
+[GitHub](https://github.com/vitest-dev/vitest) | [Documentation](https://vitest.dev/guide/browser/)

package/context.d.ts

@@ -44,6 +44,129 @@ export interface ScreenshotOptions {
   save?: boolean
 }
 
+export interface ScreenshotComparatorRegistry {
+  pixelmatch: {
+    /**
+     * The maximum number of pixels that are allowed to differ between the captured
+     * screenshot and the stored reference image.
+     *
+     * If set to `undefined`, any non-zero difference will cause the test to fail.
+     *
+     * For example, `allowedMismatchedPixels: 10` means the test will pass if 10
+     * or fewer pixels differ, but fail if 11 or more differ.
+     *
+     * If both this and `allowedMismatchedPixelRatio` are set, the more restrictive
+     * value (i.e., fewer allowed mismatches) will be used.
+     *
+     * @default undefined
+     */
+    allowedMismatchedPixels?: number | undefined
+    /**
+     * The maximum allowed ratio of differing pixels between the captured screenshot
+     * and the reference image.
+     *
+     * Must be a value between `0` and `1`.
+     *
+     * For example, `allowedMismatchedPixelRatio: 0.02` means the test will pass
+     * if up to 2% of pixels differ, but fail if more than 2% differ.
+     *
+     * If both this and `allowedMismatchedPixels` are set, the more restrictive
+     * value (i.e., fewer allowed mismatches) will be used.
+     *
+     * @default undefined
+     */
+    allowedMismatchedPixelRatio?: number | undefined
+    /**
+     * Acceptable perceived color difference between the same pixel in two images.
+     *
+     * Value ranges from `0` (strict) to `1` (very lenient). Lower values mean
+     * small differences will be detected.
+     *
+     * The comparison uses the {@link https://en.wikipedia.org/wiki/YIQ | YIQ color space}.
+     *
+     * @default 0.1
+     */
+    threshold?: number | undefined
+    /**
+     * If `true`, disables detection and ignoring of anti-aliased pixels.
+     *
+     * @default false
+     */
+    includeAA?: boolean | undefined
+    /**
+     * Blending level of unchanged pixels in the diff image.
+     *
+     * Ranges from `0` (white) to `1` (original brightness).
+     *
+     * @default 0.1
+     */
+    alpha?: number | undefined
+    /**
+     * Color used for anti-aliased pixels in the diff image.
+     *
+     * Format: `[R, G, B]`
+     *
+     * @default [255, 255, 0]
+     */
+    aaColor?: [r: number, g: number, b: number] | undefined
+    /**
+     * Color used for differing pixels in the diff image.
+     *
+     * Format: `[R, G, B]`
+     *
+     * @default [255, 0, 0]
+     */
+    diffColor?: [r: number, g: number, b: number] | undefined
+    /**
+     * Optional alternative color for dark-on-light differences, to help show
+     * what's added vs. removed.
+     *
+     * If not set, `diffColor` is used for all differences.
+     *
+     * Format: `[R, G, B]`
+     *
+     * @default undefined
+     */
+    diffColorAlt?: [r: number, g: number, b: number] | undefined
+    /**
+     * If `true`, shows only the diff as a mask on a transparent background,
+     * instead of overlaying it on the original image.
+     *
+     * Anti-aliased pixels won't be shown (if detected).
+     *
+     * @default false
+     */
+    diffMask?: boolean | undefined
+  }
+}
+
+export interface ScreenshotMatcherOptions<
+  ComparatorName extends keyof ScreenshotComparatorRegistry = keyof ScreenshotComparatorRegistry
+> {
+  /**
+   * The name of the comparator to use for visual diffing.
+   *
+   * Must be one of the keys from {@linkcode ScreenshotComparatorRegistry}.
+   *
+   * @defaultValue `'pixelmatch'`
+   */
+  comparatorName?: ComparatorName
+  comparatorOptions?: ScreenshotComparatorRegistry[ComparatorName]
+  screenshotOptions?: Omit<
+    ScreenshotOptions,
+    'element' | 'base64' | 'path' | 'save' | 'type'
+  >
+  /**
+   * Time to wait until a stable screenshot is found.
+   *
+   * Setting this value to `0` disables the timeout, but if a stable screenshot
+   * can't be determined the process will not end.
+   *
+   * @default 5000
+   */
+  timeout?: number
+}
+
 export interface BrowserCommands {
   readFile: (
     path: string,
@@ -332,6 +455,8 @@ interface LocatorSelectors {
   getByTestId: (text: string | RegExp) => Locator
 }
 
+export interface FrameLocator extends LocatorSelectors {}
+
 export interface Locator extends LocatorSelectors {
   /**
    * Selector string that will be used to locate the element by the browser provider.
@@ -350,6 +475,12 @@ export interface Locator extends LocatorSelectors {
    */
   readonly selector: string
 
+  /**
+   * The number of elements that this locator is matching.
+   * @see {@link https://vitest.dev/guide/browser/locators#length}
+   */
+  readonly length: number
+
   /**
    * 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}
@@ -421,7 +552,7 @@ export interface Locator extends LocatorSelectors {
    *
    * @see {@link https://vitest.dev/guide/browser/locators#element}
    */
-  element(): Element
+  element(): HTMLElement | SVGElement
   /**
    * Returns an array of elements matching the selector.
    *
@@ -429,7 +560,7 @@ export interface Locator extends LocatorSelectors {
    *
    * @see {@link https://vitest.dev/guide/browser/locators#elements}
    */
-  elements(): Element[]
+  elements(): (HTMLElement | SVGElement)[]
   /**
    * Returns an element matching the selector.
    *
@@ -438,7 +569,7 @@ export interface Locator extends LocatorSelectors {
    *
    * @see {@link https://vitest.dev/guide/browser/locators#query}
    */
-  query(): Element | null
+  query(): HTMLElement | SVGElement | null
   /**
    * Wraps an array of `.elements()` matching the selector in a new `Locator`.
    *
@@ -578,6 +709,25 @@ export interface BrowserPage extends LocatorSelectors {
    * @see {@link https://vitest.dev/guide/browser/locators}
    */
   elementLocator(element: Element): Locator
+  /**
+   * The iframe locator. This is a document locator that enters the iframe body
+   * and works similarly to the `page` object.
+   *
+   * As the first argument, pass down the locator to the `<iframe>` element itself.
+   *
+   * **Warning:** At the moment, this is supported only by the `playwright` provider.
+   * @example
+   * ```ts
+   * const frame = page.frameLocator(
+   *   page.getByTestId('iframe')
+   * )
+   *
+   * await frame.getByText('Hello World').click()
+   * ```
+   * @param locator The locator object.
+   * @see {@link https://vitest.dev/guide/browser/locators}
+   */
+  frameLocator(locator: Locator): FrameLocator
 }
 
 export interface BrowserLocators {

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

@@ -1,24 +1,24 @@
 {
-  "_utils-Owv5OOOf.js": {
-    "file": "__vitest_browser__/utils-Owv5OOOf.js",
+  "_utils-CPmDBIKG.js": {
+    "file": "__vitest_browser__/utils-CPmDBIKG.js",
     "name": "utils"
   },
   "orchestrator.html": {
-    "file": "__vitest_browser__/orchestrator-CQgVbcQq.js",
+    "file": "__vitest_browser__/orchestrator-BXX6oamz.js",
     "name": "orchestrator",
     "src": "orchestrator.html",
     "isEntry": true,
     "imports": [
-      "_utils-Owv5OOOf.js"
+      "_utils-CPmDBIKG.js"
     ]
   },
   "tester/tester.html": {
-    "file": "__vitest_browser__/tester-BScMoGFI.js",
+    "file": "__vitest_browser__/tester-CMhJ1E1W.js",
     "name": "tester",
     "src": "tester/tester.html",
     "isEntry": true,
     "imports": [
-      "_utils-Owv5OOOf.js"
+      "_utils-CPmDBIKG.js"
     ]
   }
 }