@quickpickle/vitest-browser 0.0.3 → 0.2.0

package/src/VitestBrowserWorld.ts

@@ -2,37 +2,69 @@ import { Before, QuickPickleWorld, QuickPickleWorldInterface } from 'quickpickle
 import type { BrowserPage, Locator, UserEvent, ScreenshotOptions } from '@vitest/browser/context'
 import { defaultsDeep } from 'lodash-es'
 import type { TestContext } from 'vitest';
-import { InfoConstructor } from 'quickpickle/dist/world';
+import { ScreenshotComparisonOptions, VisualConfigSetting, VisualWorld, VisualWorldInterface, type InfoConstructor } from 'quickpickle';
+import { commands } from '@vitest/browser/context';
+import { Buffer } from 'buffer'
+
 
 /// <reference types="@vitest/browser/providers/playwright" />
 
-export type VitestWorldConfig = {
+export interface VitestWorldConfigSetting extends VisualConfigSetting {
   componentDir?:        string;
-  screenshotDir?:       string;
-  screenshotOptions?:   Partial<ScreenshotOptions>;
 }
 
-export const defaultVitestWorldConfig:VitestWorldConfig = {
+export const defaultVitestWorldConfig:VitestWorldConfigSetting = {
   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: {               // options for the default screenshot comparisons
+    threshold: 0.1,
+    alpha: 0.6,
+    maxDiffPercentage: .01,
+  },
+}
+
+export type ActionsInterface = {
+  clicks: any[];
+  doubleClicks: any[];
 }
 
-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;
-  userEvent: UserEvent
+  actions: ActionsInterface
+  browserPage: BrowserPage;
+  page: Locator;
+  userEvent: UserEvent;
 }
 
-export class VitestBrowserWorld extends QuickPickleWorld implements VitestBrowserWorldInterface {
+export class VitestBrowserWorld extends VisualWorld implements VitestBrowserWorldInterface {
 
-  renderFn: (component:any, props:any, renderOptions:any)=>void;
-  cleanupFn: ()=>void;
-  page!: BrowserPage;
+  actions:ActionsInterface = {
+    clicks: [],
+    doubleClicks: [],
+  };
+  browserPage!: BrowserPage;
   userEvent!: UserEvent;
+  async render(name:string|any,props?:any,renderOptions?:any){};
+  async cleanup(){};
+  _page!:Locator|null;
 
   constructor(context:TestContext, info:InfoConstructor) {
     info = defaultsDeep(info || {}, { config: { worldConfig: defaultVitestWorldConfig } } )
@@ -40,40 +72,30 @@ export class VitestBrowserWorld extends QuickPickleWorld implements VitestBrowse
     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:string|any, props?:any, renderOptions?:any) {
-    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:string) {
-    return filepath.replace(/\/\/+/g, '/').replace(/\/[\.~]+\//g, '/')
+  get page():Locator {
+    if (!this._page) throw new Error('You must render a component before running tests.')
+    return this._page
   }
 
-  get screenshotDir() {
-    return this.sanitizeFilepath(`${this.projectRoot}/${this.worldConfig.screenshotDir}`)
+  set page(value:HTMLElement) {
+    while (value.parentNode !== null && value.nodeName !== 'BODY') value = value.parentNode as HTMLBodyElement
+    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)
+    })
   }
 
-  get screenshotFilename() {
-    return `${this.toString().replace(/^.+?Feature: /, '').replace(' ' + this.info.step, '')}.png`
-  }
-
-
   /**
     * Gets a locator based on a certain logic
     * @example getLocator(page, 'Cancel', 'button') => page.getByRole('button', { name: 'Cancel' })
@@ -138,6 +160,7 @@ export class VitestBrowserWorld extends QuickPickleWorld implements VitestBrowse
   async scroll(locator:Locator, direction:"up"|"down"|"left"|"right", 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 await el.scrollBy(0, direction === 'down' ? px : -px)
   }
@@ -186,9 +209,75 @@ export class VitestBrowserWorld extends QuickPickleWorld implements VitestBrowse
     if (toBePresent === (matchingElements.length === 0)) throw new Error(`The${toBeVisible ? '' : ' hidden'} element "${locator}" was unexpectedly ${toBePresent ? 'not present' : 'present'}.`)
   }
 
+  async screenshot(opts?:{
+    bufferOnly?:boolean
+    name?:string
+    locator?:Locator
+  }):Promise<any> {
+    let path
+    if (!opts?.bufferOnly) path = this.getScreenshotPath(opts?.name)
+    let locator = opts?.locator ?? this.page
+    return locator.screenshot({ path })
+  }
+
+  async expectScreenshotMatch(locator:Locator, filename?:string, opts:ScreenshotComparisonOptions={}) {
+
+    const filepath = this.getScreenshotPath(filename)
+    let expectedImg:string
+
+    /**
+     * 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 } as ScreenshotOptions
+    let actualImg = await locator.screenshot(screenshotOptions) as string|{ base64:string }
+    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:number) {
     await new Promise(r => setTimeout(r, ms))

package/src/actions.steps.ts

@@ -148,15 +148,23 @@ When('I uncheck (the ){string}( checkbox)( box)', async function (world:VitestBr
 // })
 
 When('I wait (for ){int}ms', async function (world:VitestBrowserWorld, num) {
-  await world.waitForTimeout(num)
+  await world.wait(num)
 })
 When('I wait (for ){float} second(s)', async function (world:VitestBrowserWorld, num) {
-  await world.waitForTimeout(num * 1000)
+  await world.wait(num * 1000)
 })
 
 // ================
 // Scrolling
 
+When('I scroll down/up/left/right', async function (world:VitestBrowserWorld) {
+  let direction = world.info.step?.match(/(down|up|left|right)$/)![0] as 'down'|'up'|'left'|'right'
+  await world.scroll(world.page, direction)
+})
+When('I scroll down/up/left/right {int}(px)( pixels)', async function (world:VitestBrowserWorld, num) {
+  let direction = world.info.step?.match(/(down|up|left|right)(?= \d)/)![0] as 'down'|'up'|'left'|'right'
+  await world.scroll(world.page, direction, num)
+})
 When('I scroll (the ){string} {word} down/up/left/right', async function (world:VitestBrowserWorld, identifier:string, role:string) {
   let locator = world.getLocator(world.page, identifier, role)
   let direction = world.info.step?.match(/(down|up|left|right)$/)![0] as 'down'|'up'|'left'|'right'
@@ -167,3 +175,21 @@ When('I scroll (the ){string} {word} down/up/left/right {int}(px)( pixels)', asy
   let direction = world.info.step?.match(/(down|up|left|right)(?= \d)/)![0] as 'down'|'up'|'left'|'right'
   await world.scroll(locator, direction, num)
 })
+
+// ================
+// Screenshots
+
+Then('(I )take (a )screenshot', async function (world:VitestBrowserWorld) {
+  await world.screenshot()
+})
+Then('(I )take (a )screenshot named {string}', async function (world:VitestBrowserWorld, name:string) {
+  await world.screenshot({ name })
+})
+Then('(I )take (a )screenshot of the {string} {word}', async function (world:VitestBrowserWorld, identifier:string, role:string) {
+  let locator = world.getLocator(world.page, identifier, role)
+  await world.screenshot({ locator })
+})
+Then('(I )take (a )screenshot of the {string} {word} named {string}', async function (world:VitestBrowserWorld, identifier:string, role:string, name:string) {
+  let locator = world.getLocator(world.page, identifier, role)
+  await world.screenshot({ locator, name })
+})

package/src/frameworks/ReactBrowserWorld.ts

@@ -3,6 +3,17 @@ import { render, cleanup } from 'vitest-browser-react'
 import type { TestContext } from "vitest";
 import type { InfoConstructor } from "quickpickle/dist/world";
 import React from 'react';
+import { defaultsDeep } from 'lodash-es'
+
+export const defaultReactOptions = {
+  /**
+   * The default extension to use when rendering components
+   * (if none is provided in the step)
+   */
+  defaultComponentExtension: 'tsx',
+}
+
+export type ReactWorldConfigSetting = Partial<typeof defaultReactOptions>
 
 export class ReactBrowserWorld extends VitestBrowserWorld {
 
@@ -10,19 +21,18 @@ export class ReactBrowserWorld extends VitestBrowserWorld {
   cleanupFn = cleanup
 
   constructor(context:TestContext, info:InfoConstructor) {
+    info.config.worldConfig = defaultsDeep(info.config.worldConfig, defaultReactOptions)
     super(context, info)
   }
 
-    // override VitestBrowserWorld.render
-  async render(name: string | any, props?: any, renderOptions?: any) {
-    let Component: any;
-
+  async render(name:string|any, props?:any, renderOptions?:any) {
+    let Component:any;
+    // Set the default extension if not provided
+    if (typeof name === 'string' && !name.match(/\.[jt]sx?$/))
+      name += '.' + this.worldConfig.defaultComponentExtension;
     if (typeof name === 'string') {
       // dynamic import returns the module object
-      const mod = await import(
-        `${this.projectRoot}/${this.worldConfig.componentDir}/${name}`.replace(/\/+/g,'/')
-        /* @vite-ignore */
-      );
+      let mod = await import(`${this.fullPath(`${this.worldConfig.componentDir}/${name}`)}` /* @vite-ignore */ )
       // try .default first, then fall back to any other export
       Component = mod.default ?? Object.values(mod)[0];
       if (!Component) {
@@ -35,7 +45,10 @@ export class ReactBrowserWorld extends VitestBrowserWorld {
     }
 
     // now call reactRender with the actual component
-    await this.renderFn(React.createElement(Component, props), renderOptions);
+    let result = await render(React.createElement(Component, props), renderOptions);
+    this.page = result.container;
   }
 
+  async cleanup() { await cleanup(); }
+
 }

package/src/frameworks/SvelteBrowserWorld.ts

@@ -5,11 +5,19 @@ import { InfoConstructor } from "quickpickle/dist/world";
 
 export class SvelteBrowserWorld extends VitestBrowserWorld {
 
-  renderFn = render
-  cleanupFn = cleanup
-
   constructor(context:TestContext, info:InfoConstructor) {
     super(context, info)
   }
 
+  async render(name:string|any, props?:any, renderOptions?:any) {
+    if (typeof name === 'string' && !name.match(/\.svelte$/)) name += '.svelte'
+    let component = typeof name === 'string'
+      ? await import(`${this.fullPath(`${this.worldConfig.componentDir}/${name}`)}` /* @vite-ignore */ )
+      : name
+    let result = await render(component, props, renderOptions)
+    this.page = result.container
+  };
+
+  async cleanup() { await cleanup(); }
+
 }

package/src/frameworks/VueBrowserWorld.ts

@@ -5,19 +5,20 @@ import type { InfoConstructor } from "quickpickle/dist/world";
 
 export class VueBrowserWorld extends VitestBrowserWorld {
 
-  renderFn = render
-  cleanupFn = cleanup
-
   constructor(context:TestContext, info:InfoConstructor) {
     super(context, info)
   }
 
   async render(name:string|any, props?:any, renderOptions?:any) {
+    if (typeof name === 'string' && !name.match(/\.vue$/)) name += '.vue'
     let mod = typeof name === 'string'
-      ? await import(`${this.projectRoot}/${this.worldConfig.componentDir}/${name}`.replace(/\/+/g, '/') /* @vite-ignore */ )
+      ? await import(`${this.fullPath(`${this.worldConfig.componentDir}/${name}`)}` /* @vite-ignore */ )
       : name;
     let component = mod.default ?? mod;
-    await this.renderFn(component, { props, ...renderOptions })
+    let result = await render(component, { props, ...renderOptions })
+    this.page = result.container
   };
 
+  async cleanup() { await cleanup(); }
+
 }

package/src/outcomes.steps.ts

@@ -1,9 +1,33 @@
 import { Then } from "quickpickle";
 import type { VitestBrowserWorld } from "./VitestBrowserWorld";
 import { expect } from 'vitest'
+import { BrowserPage, Locator } from "@vitest/browser/context";
 
 /// <reference types="@vitest/browser/providers/playwright" />
 
+expect.extend({
+  async toBeInTheViewport(locator:Locator) {
+    let frame = await locator.element()
+    while (frame.parentElement && frame.tagName !== 'HTML') {
+      frame = frame.parentElement
+    }
+    const viewport = await frame.getBoundingClientRect();
+    const rect = await locator.element().getBoundingClientRect();
+    if (rect) {
+      const inViewport = (rect.right > 0 && rect.bottom > 0 && rect.top < viewport.height && rect.left < viewport.width);
+      return {
+        message: () => `expected ${locator.toString()} to be in viewport`,
+        pass: inViewport,
+      };
+    } else {
+      return {
+        message: () => `could not get bounding box for ${locator.toString()}`,
+        pass: false,
+      };
+    }
+  }
+})
+
 // ================
 // Text on page
 
@@ -39,6 +63,21 @@ Then('I should not/NOT see a/an/the {string} (element )with (the )(text ){string
   await world.expectElement(locator, false)
 })
 
+// ================
+// Actions
+Then('{string} should have been clicked/doubleclicked/dblclicked', async function (world:VitestBrowserWorld, text) {
+  let single = world.info.step?.match(/ clicked$/)
+  if (single) expect(world.actions.clicks.find((el) => (el && el?.textContent === text))).not.toBeNull()
+  else expect(world.actions.doubleClicks.find((el) => (el && el?.textContent === text))).not.toBeNull()
+})
+
+Then('(the ){string} {word} should have been clicked/doubleclicked/dblclicked', async function (world:VitestBrowserWorld, identifier, role) {
+  let single = world.info.step?.match(/ clicked$/)
+  let element = world.getLocator(world.page, identifier, role)
+  if (single) expect(world.actions.clicks.find((el) => (el === element))).not.toBeNull()
+  else expect(world.actions.doubleClicks.find((el) => (el === element))).not.toBeNull()
+})
+
 // ================
 // Element state
 Then('a/an/the {string} {word} should be visible/hidden/invisible', async function (world:VitestBrowserWorld, identifier, role) {
@@ -116,6 +155,25 @@ Then('a/an/the {string} (element )with (the )(text ){string} should be unfocused
   await expect(locator).not.toHaveFocus()
 })
 
+Then('a/an/the {string} {word} should be in(side) (of )the viewport', async function (world:VitestBrowserWorld, identifier, role) {
+  let locator = await world.getLocator(world.page, identifier, role)
+  // @ts-ignore
+  await expect(locator).toBeInTheViewport()
+})
+Then('a/an/the {string} {word} should be out(side) (of )the viewport', async function (world:VitestBrowserWorld, identifier, role) {
+  let locator = await world.getLocator(world.page, identifier, role)
+  // @ts-ignore
+  expect(locator).not.toBeInTheViewport()
+})
+// Then('a/an/the {string} (element )with (the )(text ){string} should be in(side) (of )the viewport', async function (world:VitestBrowserWorld, identifier, text) {
+//   let locator = await world.getLocator(world.page, identifier, 'element', text)
+//   await isInViewport(world, locator)
+// })
+// Then('a/an/the {string} (element )with (the )(text ){string} should be out(side) (of )the viewport', async function (world:VitestBrowserWorld, identifier, text) {
+//   let locator = await world.getLocator(world.page, identifier, 'element', text)
+//   await isInViewport(world, locator)
+// })
+
 // Values
 Then('a/an/the (value of ){string} should contain/include/be/equal {string}', async function (world:VitestBrowserWorld, identifier, expected) {
   let exact = world.info.step?.match(/ should (?:be|equal) ['"]/) ? true : false
@@ -155,36 +213,35 @@ Then('a/an/the (value of )(the ){string} {word} should not/NOT contain/include/b
   }
 })
 
+Then('a/an/the (value of ){string} should be/equal {int}', async function (world:VitestBrowserWorld, identifier, expected) {
+  let locator = await world.getLocator(world.page, identifier, 'input')
+  await expect(locator).toHaveValue(expected)
+})
+Then('a/an/the (value of )(the ){string} {word} should be/equal {int}', async function (world:VitestBrowserWorld, identifier, role, expected) {
+  let locator = await world.getLocator(world.page, identifier, role)
+  await expect(locator).toHaveValue(expected)
+})
+Then('a/an/the (value of )(the ){string} should not/NOT be/equal {int}', async function (world:VitestBrowserWorld, identifier, expected) {
+  let locator = await world.getLocator(world.page, identifier, 'input')
+  await expect(locator).not.toHaveValue(expected)
+})
+Then('a/an/the (value of )(the ){string} {word} should not/NOT be/equal {int}', async function (world:VitestBrowserWorld, identifier, role, expected) {
+  let locator = await world.getLocator(world.page, identifier, role)
+  await expect(locator).not.toHaveValue(expected)
+})
+
 // Visual regression testing
 Then('(the )screenshot/snapshot should match', async function (world:VitestBrowserWorld) {
-  await expect(world.page).toMatchImageSnapshot({
-    ...world.worldConfig.screenshotOptions,
-    customSnapshotsDir: world.screenshotDir,
-    customSnapshotIdentifier: world.screenshotFilename,
-  })
+  await world.expectScreenshotMatch(world.page)
 })
 Then('(the )screenshot/snapshot {string} should match', async function (world:VitestBrowserWorld, name:string) {
-  let explodedTags = world.info.explodedIdx ? `_(${world.info.tags.join(',')})` : ''
-  await expect(world.page).toMatchImageSnapshot({
-    ...world.worldConfig.screenshotOptions,
-    customSnapshotsDir: world.screenshotDir,
-    customSnapshotIdentifier: `${name}${explodedTags}`,
-  })
+  await world.expectScreenshotMatch(world.page, name)
 })
 Then('(the )screenshot/snapshot of the {string} {word} should match', async function (world:VitestBrowserWorld, identifier, role) {
   let locator = await world.getLocator(world.page, identifier, role)
-  await expect(locator).toMatchImageSnapshot({
-    ...world.worldConfig.screenshotOptions,
-    customSnapshotsDir: world.screenshotDir,
-    customSnapshotIdentifier: world.screenshotFilename,
-  })
+  await world.expectScreenshotMatch(locator)
 })
 Then('(the )screenshot/snapshot {string} of the {string} {word} should match', async function (world:VitestBrowserWorld, name, identifier, role) {
   let locator = await world.getLocator(world.page, identifier, role)
-  let explodedTags = world.info.explodedIdx ? `_(${world.info.tags.join(',')})` : ''
-  await expect(locator).toMatchImageSnapshot({
-    ...world.worldConfig.screenshotOptions,
-    customSnapshotsDir: world.screenshotDir,
-    customSnapshotIdentifier: `${name}${explodedTags}`,
-  })
+  await world.expectScreenshotMatch(locator, name)
 })