@quickpickle/vitest-browser 0.0.3 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # @quickpickle/vitest-browser
 
+## 0.2.0
+
+### Minor Changes
+
+- 8273918: Switched to VisualWorld class for visual regression testing
+
+### Patch Changes
+
+- Updated dependencies [e617638]
+  - quickpickle@1.9.0
+
+## 0.1.0
+
+### Minor Changes
+
+- 8a32a09: Add a true path sanitizer to the base World object
+
+  BREAKING CHANGE:
+
+  The base world object no longer has a public `projectRoot` property.
+  Instead of constructing paths that way, developers should use the
+  `world.fullPath()` method to get the full path to a file or subfolder.
+  This should ensure that only files below the projectRoot are accessed.
+
+  Playwright and Browser world constructors no longer have the
+  sanitizeFilepath method. Instead, there is a new "sanitizePath"
+  method on the base World, which should be relatively safe even
+  for user input, avoiding path traversal and the like.
+
+- 15e0e06: Major refactor with breaking changes, including to the World Constructor APIs.
+
+  - Added tests for all step definitions (using Svelte) based on Playwright package tests
+  - Added basic instructions to README
+  - Added scrolling step definitions
+  - Added screenshot step definitions
+  - Added step definitions to test for integer values
+  - Added step definitions to check that an element is in the viewport
+  - Added step definitions to check for clicked items
+  - Changed the VitestBrowserWorld API to accommodate step definitions
+  - Changed the React, Vue and Svelte worlds to use the new API
+
+  BREAKING CHANGES:
+
+  - When extending the VitestBrowserWorld class, subclasses must implement the `render`
+    and `cleanup` methods. The `render` method must not only render the component
+    but also set the `page` property using RenderResult.container.
+
+### Patch Changes
+
+- Updated dependencies [8a32a09]
+  - quickpickle@1.8.0
+
 ## 0.0.3
 
 ### Patch Changes

package/README.md

@@ -1,4 +1,75 @@
 # Vitest: Browser Mode
 
 This is the library for using Vitest with browser mode for testing components.
+It's still fairly early in development, but you can already use it for some purposes.
 
+## Setup
+
+The following is a pretty basic setup for testing components in Svelte, Vue, or React:
+
+1. `pnpm i -D @quickpickle/vitest-browser@latest`
+
+2. add plugins to the Vitest configuration, in one of the configuration files (`vite.config.ts`, `vitest.config.ts`, or `vitest.workspace.ts`). Here is a working example from a SvelteKit project:
+
+    ```ts
+    // File: vitest.workspace.ts
+    import quickpickle from "quickpickle";
+
+    export default [
+      {
+        plugins: [quickpickle()],
+        extends: './vite.config.ts',
+        test: {
+          name: 'components',
+          environment: 'browser',
+          include: ['src/lib/**/*.feature'], // anticipates putting the .feature files next to components
+          setupFiles: ['./tests/components.steps.ts'], // this file must be created (see step 3)
+          // @ts-ignore
+          quickpickle: {
+            worldConfig: {
+              componentDir: 'src/lib', // The directory where the components are kept
+            }
+          },
+          browser: { // This is configuration for Vitest browser mode, and can be modified as appropriate
+            enabled: true,
+            screenshotFailures: true,
+            name: 'chromium',
+            provider: 'playwright',
+            ui: true,
+            instances: [
+              { browser:'chromium' },
+            ]
+          }
+        }
+      },
+    ]
+    ```
+
+3. Create a step definition file for your component tests:
+
+    ```ts
+    // File: tests/components.steps.ts
+    import '@quickpickle/vitest-browser/actions';
+    import '@quickpickle/vitest-browser/outcomes';
+    import '@quickpickle/vitest-browser/svelte'; // OR react or vue
+    ```
+
+## Known Issues:
+
+* Reactivity is currently broken for Svelte and Vue tests.
+* Selecting elements by css selector doesn't work yet.
+* Performing screenshot comparisons may result in an extra screenshot
+  being created for @vitest/browser versions below 3.2.0
+
+## Suspected Issues:
+
+* I suspect that there will still be issues with the test code
+  not properly waiting for changes to propagate on the page when
+  there are delays for CSS transitions, async fetch calls, etc.
+
+## Plans:
+
+[x] basic actions and outcomes in English, to match @quickpickle/playwright
+[x] basic tests for rendering Svelte, Vue, and React components
+[x] full tests for all actions and outcomes, matching @quickpickle/playwright
+[ ] some sort of Storybook-esque presentation using Vitest UI

package/dist/VitestBrowserWorld.cjs

@@ -2,45 +2,54 @@
 
 var quickpickle = require('quickpickle');
 var defaultsDeep = require('lodash/defaultsDeep');
+var context = require('@vitest/browser/context');
+var buffer = require('buffer');
 
 const defaultVitestWorldConfig = {
     componentDir: '', // directory in which components are kept, relative to project root
     screenshotDir: 'screenshots', // directory in which to save screenshots, relative to project root (default: "screenshots")
-    screenshotOptions: {}, // options for the default screenshot comparisons
+    screenshotOpts: {
+        threshold: 0.1,
+        alpha: 0.6,
+        maxDiffPercentage: .01,
+    },
 };
-class VitestBrowserWorld extends quickpickle.QuickPickleWorld {
+class VitestBrowserWorld extends quickpickle.VisualWorld {
+    async render(name, props, renderOptions) { }
+    ;
+    async cleanup() { }
+    ;
     constructor(context, info) {
         info = defaultsDeep(info || {}, { config: { worldConfig: defaultVitestWorldConfig } });
         super(context, info);
+        this.actions = {
+            clicks: [],
+            doubleClicks: [],
+        };
         if (!info.config.worldConfig.screenshotDir && info.config.worldConfig?.screenshotOptions?.customSnapshotsDir) {
             this.info.config.worldConfig.screenshotDir = info.config.worldConfig.screenshotOptions.customSnapshotsDir;
         }
-        this.renderFn = () => { };
-        this.cleanupFn = () => { };
     }
     async init() {
         let browserContext = await import('@vitest/browser/context');
-        this.page = browserContext.page;
+        this.browserPage = browserContext.page;
         this.userEvent = browserContext.userEvent;
     }
-    async render(name, props, renderOptions) {
-        let component = typeof name === 'string'
-            ? await import(`${this.projectRoot}/${this.worldConfig.componentDir}/${name}`.replace(/\/+/g, '/') /* @vite-ignore */)
-            : name;
-        await this.renderFn(component, props, renderOptions);
-    }
-    ;
-    async cleanup() {
-        await this.cleanupFn();
-    }
-    sanitizeFilepath(filepath) {
-        return filepath.replace(/\/\/+/g, '/').replace(/\/[\.~]+\//g, '/');
-    }
-    get screenshotDir() {
-        return this.sanitizeFilepath(`${this.projectRoot}/${this.worldConfig.screenshotDir}`);
+    get page() {
+        if (!this._page)
+            throw new Error('You must render a component before running tests.');
+        return this._page;
     }
-    get screenshotFilename() {
-        return `${this.toString().replace(/^.+?Feature: /, '').replace(' ' + this.info.step, '')}.png`;
+    set page(value) {
+        while (value.parentNode !== null && value.nodeName !== 'BODY')
+            value = value.parentNode;
+        this._page = this.browserPage.elementLocator(value);
+        value.addEventListener('click', (e) => {
+            this.actions.clicks.push(e.target);
+        });
+        value.addEventListener('dblclick', (e) => {
+            this.actions.doubleClicks.push(e.target);
+        });
     }
     /**
       * Gets a locator based on a certain logic
@@ -111,6 +120,8 @@ class VitestBrowserWorld extends quickpickle.QuickPickleWorld {
     async scroll(locator, direction, px = 100) {
         let horiz = direction.includes('t');
         let el = await locator.element();
+        if (el.nodeName === 'BODY' && el.parentElement)
+            el = el.parentElement;
         if (horiz)
             await el.scrollBy(direction === 'right' ? px : -px, 0);
         else
@@ -159,9 +170,65 @@ class VitestBrowserWorld extends quickpickle.QuickPickleWorld {
         if (toBePresent === (matchingElements.length === 0))
             throw new Error(`The${toBeVisible ? '' : ' hidden'} element "${locator}" was unexpectedly ${toBePresent ? 'not present' : 'present'}.`);
     }
+    async screenshot(opts) {
+        let path;
+        if (!opts?.bufferOnly)
+            path = this.getScreenshotPath(opts?.name);
+        let locator = opts?.locator ?? this.page;
+        return locator.screenshot({ path });
+    }
+    async expectScreenshotMatch(locator, filename, opts = {}) {
+        const filepath = this.getScreenshotPath(filename);
+        let expectedImg;
+        /**
+         * Load existing screenshot, or save it if it doesn't yet exist
+         */
+        try {
+            expectedImg = await context.commands.readFile(this.getScreenshotPath(filename), 'base64');
+        }
+        catch (e) {
+            // If the screenshot doesn't exist, save it and pass the test
+            await locator.screenshot();
+            console.warn(`new visual regression test: ${this.screenshotDir}/${this.screenshotFilename}`);
+            return;
+        }
+        let expected = buffer.Buffer.from(expectedImg, 'base64');
+        /**
+         * Get the screenshot
+         */
+        // type does not include the "save" option in the docs: see https://vitest.dev/guide/browser/locators#screenshot
+        let screenshotOptions = { save: false, base64: true };
+        let actualImg = await locator.screenshot(screenshotOptions);
+        let actual = buffer.Buffer.from(typeof actualImg === 'string' ? actualImg : actualImg.base64, 'base64');
+        /**
+         * Compare the two screenshots
+         */
+        let screenshotOpts = defaultsDeep(opts, this.worldConfig.screenshotOpts);
+        let matchResult = null;
+        try {
+            matchResult = await this.screenshotDiff(actual, expected, screenshotOpts);
+        }
+        catch (e) { }
+        console.log({
+            pass: matchResult?.pass,
+            diffPercentage: matchResult?.diffPercentage,
+            filename,
+            locator,
+        }.toString());
+        if (!matchResult?.pass) {
+            await context.commands.writeFile(`${filepath}.actual.png`, actual.toString('base64'), 'base64');
+            if (matchResult?.diff)
+                await context.commands.writeFile(`${filepath}.diff.png`, matchResult.diff.toString('base64'), 'base64');
+            throw new Error(`Screenshot does not match the snapshot.
+  Diff percentage: ${matchResult?.diffPercentage?.toFixed(2) ?? '100'}%
+  Max allowed: ${screenshotOpts.maxDiffPercentage}%
+  Diffs at: ${filepath}.(diff|actual).png`);
+        }
+    }
     /**
      * Waits for a certain amount of time
      * @param ms number
+     * @deprecated use `wait` method instead
      */
     async waitForTimeout(ms) {
         await new Promise(r => setTimeout(r, ms));

package/dist/VitestBrowserWorld.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"VitestBrowserWorld.cjs","sources":["../src/VitestBrowserWorld.ts"],"sourcesContent":[null],"names":["QuickPickleWorld","Before"],"mappings":"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"}
+{"version":3,"file":"VitestBrowserWorld.cjs","sources":["../src/VitestBrowserWorld.ts"],"sourcesContent":[null],"names":["VisualWorld","commands","Buffer","Before"],"mappings":"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"}

package/dist/VitestBrowserWorld.d.ts

@@ -1,33 +1,50 @@
-import { QuickPickleWorld, QuickPickleWorldInterface } from 'quickpickle';
-import type { BrowserPage, Locator, UserEvent, ScreenshotOptions } from '@vitest/browser/context';
+import type { BrowserPage, Locator, UserEvent } from '@vitest/browser/context';
 import type { TestContext } from 'vitest';
-import { InfoConstructor } from 'quickpickle/dist/world';
-export type VitestWorldConfig = {
+import { ScreenshotComparisonOptions, VisualConfigSetting, VisualWorld, VisualWorldInterface, type InfoConstructor } from 'quickpickle';
+export interface VitestWorldConfigSetting extends VisualConfigSetting {
     componentDir?: string;
-    screenshotDir?: string;
-    screenshotOptions?: Partial<ScreenshotOptions>;
+}
+export declare const defaultVitestWorldConfig: VitestWorldConfigSetting;
+export type ActionsInterface = {
+    clicks: any[];
+    doubleClicks: any[];
 };
-export declare const defaultVitestWorldConfig: VitestWorldConfig;
-export type VitestBrowserWorldInterface = QuickPickleWorldInterface & {
+export interface VitestBrowserWorldInterface extends VisualWorldInterface {
+    /**
+     * The `render` function must be provided by the World Constructor
+     * and must be tailored for the framework being used. It should render
+     * the component, and then use the parent element to set the `page` property
+     * of the World.
+     *
+     * @param name string|any The compoenent to render
+     * @param props any The properties to use when rendering the component
+     * @param renderOptions any Options to pass to the render function
+     * @returns Promise<void>
+     */
     render: (name: string | any, props?: any, renderOptions?: any) => Promise<void>;
-    renderFn: (component: any, props?: any, renderOptions?: any) => void | Promise<void>;
+    /**
+     * The `cleanup` function must be provided by the World Constructor
+     * and must be tailored for the framework being used.
+     *
+     * @returns void
+     */
     cleanup: () => Promise<void>;
-    cleanupFn: () => void | Promise<void>;
-    page: BrowserPage;
+    actions: ActionsInterface;
+    browserPage: BrowserPage;
+    page: Locator;
     userEvent: UserEvent;
-};
-export declare class VitestBrowserWorld extends QuickPickleWorld implements VitestBrowserWorldInterface {
-    renderFn: (component: any, props: any, renderOptions: any) => void;
-    cleanupFn: () => void;
-    page: BrowserPage;
+}
+export declare class VitestBrowserWorld extends VisualWorld implements VitestBrowserWorldInterface {
+    actions: ActionsInterface;
+    browserPage: BrowserPage;
     userEvent: UserEvent;
-    constructor(context: TestContext, info: InfoConstructor);
-    init(): Promise<void>;
     render(name: string | any, props?: any, renderOptions?: any): Promise<void>;
     cleanup(): Promise<void>;
-    sanitizeFilepath(filepath: string): string;
-    get screenshotDir(): string;
-    get screenshotFilename(): string;
+    _page: Locator | null;
+    constructor(context: TestContext, info: InfoConstructor);
+    init(): Promise<void>;
+    get page(): Locator;
+    set page(value: HTMLElement);
     /**
       * Gets a locator based on a certain logic
       * @example getLocator(page, 'Cancel', 'button') => page.getByRole('button', { name: 'Cancel' })
@@ -95,9 +112,16 @@ export declare class VitestBrowserWorld extends QuickPickleWorld implements Vite
       * @param toBeVisible whether the element should be visible
       */
     expectElement(locator: Locator, toBePresent?: boolean, toBeVisible?: boolean): Promise<void>;
+    screenshot(opts?: {
+        bufferOnly?: boolean;
+        name?: string;
+        locator?: Locator;
+    }): Promise<any>;
+    expectScreenshotMatch(locator: Locator, filename?: string, opts?: ScreenshotComparisonOptions): Promise<void>;
     /**
      * Waits for a certain amount of time
      * @param ms number
+     * @deprecated use `wait` method instead
      */
     waitForTimeout(ms: number): Promise<void>;
 }

package/dist/VitestBrowserWorld.mjs

@@ -1,44 +1,53 @@
-import { Before, QuickPickleWorld } from 'quickpickle';
+import { Before, VisualWorld } from 'quickpickle';
 import { defaultsDeep } from 'lodash-es';
+import { commands } from '@vitest/browser/context';
+import { Buffer } from 'buffer';
 
 const defaultVitestWorldConfig = {
     componentDir: '', // directory in which components are kept, relative to project root
     screenshotDir: 'screenshots', // directory in which to save screenshots, relative to project root (default: "screenshots")
-    screenshotOptions: {}, // options for the default screenshot comparisons
+    screenshotOpts: {
+        threshold: 0.1,
+        alpha: 0.6,
+        maxDiffPercentage: .01,
+    },
 };
-class VitestBrowserWorld extends QuickPickleWorld {
+class VitestBrowserWorld extends VisualWorld {
+    async render(name, props, renderOptions) { }
+    ;
+    async cleanup() { }
+    ;
     constructor(context, info) {
         info = defaultsDeep(info || {}, { config: { worldConfig: defaultVitestWorldConfig } });
         super(context, info);
+        this.actions = {
+            clicks: [],
+            doubleClicks: [],
+        };
         if (!info.config.worldConfig.screenshotDir && info.config.worldConfig?.screenshotOptions?.customSnapshotsDir) {
             this.info.config.worldConfig.screenshotDir = info.config.worldConfig.screenshotOptions.customSnapshotsDir;
         }
-        this.renderFn = () => { };
-        this.cleanupFn = () => { };
     }
     async init() {
         let browserContext = await import('@vitest/browser/context');
-        this.page = browserContext.page;
+        this.browserPage = browserContext.page;
         this.userEvent = browserContext.userEvent;
     }
-    async render(name, props, renderOptions) {
-        let component = typeof name === 'string'
-            ? await import(`${this.projectRoot}/${this.worldConfig.componentDir}/${name}`.replace(/\/+/g, '/') /* @vite-ignore */)
-            : name;
-        await this.renderFn(component, props, renderOptions);
-    }
-    ;
-    async cleanup() {
-        await this.cleanupFn();
-    }
-    sanitizeFilepath(filepath) {
-        return filepath.replace(/\/\/+/g, '/').replace(/\/[\.~]+\//g, '/');
-    }
-    get screenshotDir() {
-        return this.sanitizeFilepath(`${this.projectRoot}/${this.worldConfig.screenshotDir}`);
+    get page() {
+        if (!this._page)
+            throw new Error('You must render a component before running tests.');
+        return this._page;
     }
-    get screenshotFilename() {
-        return `${this.toString().replace(/^.+?Feature: /, '').replace(' ' + this.info.step, '')}.png`;
+    set page(value) {
+        while (value.parentNode !== null && value.nodeName !== 'BODY')
+            value = value.parentNode;
+        this._page = this.browserPage.elementLocator(value);
+        value.addEventListener('click', (e) => {
+            this.actions.clicks.push(e.target);
+        });
+        value.addEventListener('dblclick', (e) => {
+            this.actions.doubleClicks.push(e.target);
+        });
     }
     /**
       * Gets a locator based on a certain logic
@@ -109,6 +118,8 @@ class VitestBrowserWorld extends QuickPickleWorld {
     async scroll(locator, direction, px = 100) {
         let horiz = direction.includes('t');
         let el = await locator.element();
+        if (el.nodeName === 'BODY' && el.parentElement)
+            el = el.parentElement;
         if (horiz)
             await el.scrollBy(direction === 'right' ? px : -px, 0);
         else
@@ -157,9 +168,65 @@ class VitestBrowserWorld extends QuickPickleWorld {
         if (toBePresent === (matchingElements.length === 0))
             throw new Error(`The${toBeVisible ? '' : ' hidden'} element "${locator}" was unexpectedly ${toBePresent ? 'not present' : 'present'}.`);
     }
+    async screenshot(opts) {
+        let path;
+        if (!opts?.bufferOnly)
+            path = this.getScreenshotPath(opts?.name);
+        let locator = opts?.locator ?? this.page;
+        return locator.screenshot({ path });
+    }
+    async expectScreenshotMatch(locator, filename, opts = {}) {
+        const filepath = this.getScreenshotPath(filename);
+        let expectedImg;
+        /**
+         * Load existing screenshot, or save it if it doesn't yet exist
+         */
+        try {
+            expectedImg = await commands.readFile(this.getScreenshotPath(filename), 'base64');
+        }
+        catch (e) {
+            // If the screenshot doesn't exist, save it and pass the test
+            await locator.screenshot();
+            console.warn(`new visual regression test: ${this.screenshotDir}/${this.screenshotFilename}`);
+            return;
+        }
+        let expected = Buffer.from(expectedImg, 'base64');
+        /**
+         * Get the screenshot
+         */
+        // type does not include the "save" option in the docs: see https://vitest.dev/guide/browser/locators#screenshot
+        let screenshotOptions = { save: false, base64: true };
+        let actualImg = await locator.screenshot(screenshotOptions);
+        let actual = Buffer.from(typeof actualImg === 'string' ? actualImg : actualImg.base64, 'base64');
+        /**
+         * Compare the two screenshots
+         */
+        let screenshotOpts = defaultsDeep(opts, this.worldConfig.screenshotOpts);
+        let matchResult = null;
+        try {
+            matchResult = await this.screenshotDiff(actual, expected, screenshotOpts);
+        }
+        catch (e) { }
+        console.log({
+            pass: matchResult?.pass,
+            diffPercentage: matchResult?.diffPercentage,
+            filename,
+            locator,
+        }.toString());
+        if (!matchResult?.pass) {
+            await commands.writeFile(`${filepath}.actual.png`, actual.toString('base64'), 'base64');
+            if (matchResult?.diff)
+                await commands.writeFile(`${filepath}.diff.png`, matchResult.diff.toString('base64'), 'base64');
+            throw new Error(`Screenshot does not match the snapshot.
+  Diff percentage: ${matchResult?.diffPercentage?.toFixed(2) ?? '100'}%
+  Max allowed: ${screenshotOpts.maxDiffPercentage}%
+  Diffs at: ${filepath}.(diff|actual).png`);
+        }
+    }
     /**
      * Waits for a certain amount of time
      * @param ms number
+     * @deprecated use `wait` method instead
      */
     async waitForTimeout(ms) {
         await new Promise(r => setTimeout(r, ms));