feat: added VisualWorld base class

Author: dnotes

.changeset/wise-chairs-judge.md

@@ -0,0 +1,12 @@
+---
+"quickpickle": minor
+---
+
+Added new VisualWorld base class and interface
+
+* the VisualWorld class provides some basic functionality related to screenshots,
+  so that any descendant classes will not have to do things like parse their own
+  screenshot filenames or implement their own image diff solution.
+
+* the VisualWorldInterface defines a set of helper methods to be implemented by
+  descendant classes.

packages/main/package.json

@@ -42,10 +42,13 @@
     "test": "vitest --run"
   },
   "dependencies": {
+    "@a11y-tools/aria-roles": "^1.0.0",
+    "@coderosh/image-size": "^2.0.1",
     "@cucumber/cucumber-expressions": "^18.0.1",
     "@cucumber/gherkin": "^32.1.0",
     "@cucumber/messages": "^27.2.0",
     "@cucumber/tag-expressions": "^6.1.2",
+    "buffer": "^6.0.3",
     "lodash": "^4.17.21",
     "lodash-es": "^4.17.21"
   },
@@ -58,12 +61,11 @@
     "@types/lodash": "^4.17.16",
     "@types/lodash-es": "^4.17.12",
     "@types/node": "^22.15.17",
-    "@vitest/browser": "^3.1.3",
     "playwright": "^1.52.0",
     "rollup": "^4.40.2",
     "typescript": "^5.8.3",
     "vite": "^6.3.5",
-    "vitest": "^3.1.3"
+    "vitest": "^3.1.4"
   },
   "peerDependencies": {
     "vitest": "^1.0.0 || >=2.0.0"

packages/main/rollup.config.js

@@ -32,6 +32,9 @@ export default {
     }),
   ],
   external: [
+    '@coderosh/image-size',
+    /^buffer/,
+    'pixelmatch',
     '@cucumber/cucumber-expressions',
     '@cucumber/gherkin',
     '@cucumber/messages',

packages/main/src/index.ts

@@ -15,7 +15,19 @@ import { DataTable } from './models/DataTable';
 import { DocString } from './models/DocString';
 import { normalizeTags, tagsMatch } from './tags';
 
-export { setWorldConstructor, getWorldConstructor, QuickPickleWorld, QuickPickleWorldInterface } from './world';
+export {
+  setWorldConstructor,
+  getWorldConstructor,
+  QuickPickleWorld,
+  QuickPickleWorldInterface,
+  ScreenshotComparisonOptions,
+  VisualConfigSetting,
+  VisualWorld,
+  VisualWorldInterface,
+  VisualDiffResult,
+  defaultScreenshotComparisonOptions,
+  InfoConstructor,
+} from './world';
 export { DocString, DataTable }
 export { explodeTags, tagsMatch, normalizeTags, applyHooks }
 export { defineParameterType } from './steps'

packages/main/src/world.ts

@@ -2,6 +2,11 @@ import type { TestContext } from 'vitest'
 import { tagsMatch } from './tags'
 import type { QuickPickleConfig } from '.'
 import sanitize from './shims/path-sanitizer'
+import pixelmatch, { type PixelmatchOptions } from 'pixelmatch';
+import type { AriaRole } from '@a11y-tools/aria-roles';
+export type AriaRoleExtended = AriaRole & 'element'|'input'
+import imageSize from '@coderosh/image-size'
+import { Buffer } from 'buffer'
 
 interface Common {
   info: {
@@ -35,6 +40,8 @@ export interface QuickPickleWorldInterface {
   tagsMatch(tags: string[]): string[]|null  // function to check if the Scenario tags match the given tags
   sanitizePath:typeof sanitize              // function to sanitize a path string, from npm package "path-sanitizer" (shims)
   fullPath(path:string):string              // function to ensure that a filepath is valid and a subdirectory of the project root
+  wait(ms:number):Promise<void>             // function to wait for a given time
+
 }
 
 export type InfoConstructor = Omit<QuickPickleWorldInterface['info'], 'errors'> & { common:Common }
@@ -81,6 +88,20 @@ export class QuickPickleWorld implements QuickPickleWorldInterface {
     return `${this._projectRoot}/${this.sanitizePath(path)}`
   }
 
+  /**
+   * A helper function for when you really just need to wait.
+   *
+   * @deprecated Waiting for arbitrary amounts of time makes your tests flaky! There are
+   * usually better ways to wait for something to happen, and this functionality will be
+   * removed from the API as soon we're sure nobody will **EVER** want to use it again.
+   * (That may be a long time.)
+   *
+   * @param ms milliseconds to wait
+   */
+  async wait(ms:number) {
+    await new Promise(r => setTimeout(r, ms))
+  }
+
   toString() {
     let parts = [
       this.constructor.name,
@@ -105,4 +126,226 @@ export function getWorldConstructor() {
 
 export function setWorldConstructor(constructor: WorldConstructor) {
   worldConstructor = constructor
+}
+
+export type VisualDiffResult = {
+  pass: boolean,
+  diff: Buffer,
+  diffPercentage: number,
+}
+
+export type ScreenshotComparisonOptions = any & Partial<PixelmatchOptions> & {
+  maxDiffPercentage?: number
+}
+
+export const defaultScreenshotComparisonOptions:ScreenshotComparisonOptions = {
+  maxDiffPercentage: 0,
+  threshold: 0.1,
+  alpha: 0.6
+}
+
+export interface VisualConfigSetting {
+  screenshotDir?: string,
+  screenshotOpts?: Partial<ScreenshotComparisonOptions>
+}
+
+interface StubVisualWorldInterface extends QuickPickleWorldInterface {
+
+  /**
+   * The directory where screenshots are saved, relative to the project root.
+   */
+  screenshotDir:string
+
+  /**
+   * The filename for a screenshot based on the current Scenario.
+   */
+  screenshotFilename:string
+
+  /**
+   * The full path to a screenshot file, from the root of the file system,
+   * based on the current Scenario.
+   */
+  screenshotPath:string
+
+  /**
+   * The full path to a screenshot file, from the root of the file system,
+   * based on the custom name provided, and including information on any
+   * exploded tags as necessary.
+   *
+   * @param name
+   */
+  getScreenshotPath(name?:string):string
+
+  /**
+   * A helper function to compare two screenshots, for visual regression testing.
+   * If the screenshots do not match, the difference should be returned as a Buffer.
+   */
+  screenshotDiff(actual:Buffer, expected:Buffer, options?:any):Promise<VisualDiffResult>
+
+}
+
+export interface VisualWorldInterface extends StubVisualWorldInterface {
+
+  /**
+   * A helper method for getting an element, which should work across different testing libraries.
+   * The "Locator" interface used should be whatever is compatible with the testing library
+   * being integrated by your World Constructor. This is intended as an 80% solution for
+   * behavioral tests, so that a single step definition can get an element based on a variety
+   * of factors, e.g. (in Playwright syntax):
+   *
+   * @example getLocator(page, 'Cancel', 'button') => page.getByRole('button', { name: 'Cancel' })
+   * @example getLocator(page, 'Search', 'input') => page.getByLabel('Search').or(page.getByPlaceholder('Search'))
+   * @example getLocator(page, 'ul.fourteen-points li', 'element', 'Open covenants of peace') => page.locator('ul.fourteen-points li').filter({ hasText: 'Open covenants of peace' })
+   *
+   * @param locator Locator
+   * The container inside which to search for the required element.
+   * @param identifier string
+   * A string that identifies the element to be found. For ARIA roles this is the "name" attribute,
+   * for role="input" it is the label or placeholder, and for role="element" it is the CSS selector.
+   * @param role string
+   * An ARIA role, or "input" to get an input by label or placeholder, or "element" to get an element by css selector.
+   * @param text string
+   * A string that the element must contain.
+   */
+  getLocator(locator:any, identifier:string, role:AriaRoleExtended, text?:string|null):any
+
+  /**
+   * Sets a value on a form element based on its type (select, checkbox/radio, or other input).
+   * The "Locator" interface used should be whatever is compatible with the testing library
+   * being integrated by your World Constructor. This is intended as an 80% solution for
+   * behavioral tests, so that a single step definition can get an element based on a variety
+   * of factors, e.g.:
+   *
+   * @example setValue(<SelectInput>, "Option 1, Option 2") => Selects multiple options in a select element
+   * @example setValue(<RadioInput>, "true") => Checks a checkbox/radio item
+   * @example setValue(<CheckboxInput>, "false") => Unchecks a checkbox item
+   * @example setValue(<TextInput>, "Some text") => Fills a text input with "Some text"
+   * @example setValue(<NumberInput>, 5) => Sets a number input to the number 5
+   *
+   * @param locator Locator
+   * The Locator for the form element
+   * @param value string|any
+   * The value to set can be string or other value type
+   */
+  setValue(locator:any, value:string|any):Promise<void>
+
+  /**
+   * Scrolls an element by a number of pixels in a given direction.
+   *
+   * @param locator Locator
+   * The locator that should be scrolled
+   * @param direction "up"|"down"|"left"|"right"
+   * The direction to scroll, i.e. "up", "down", "left", "right"
+   * @param px
+   * A number of pixels to scroll
+   */
+  scroll(locator:any, direction:string, px:number):Promise<void>
+
+  /**
+   * A helper method for parsing text on a page or in an element.
+   * Can be used to check for the presence OR absence of visible OR hidden text.
+   *
+   * Examples:
+   * @example expectText(locator, 'text', true, true) // expect that a locator with the text is visible (and there may be hidden ones)
+   * @example expectText(locator, 'text', false, true) // expect that NO locator with the text is visible (but there may be hidden ones)
+   * @example expectText(locator, 'text', true, false) // expect that a HIDDEN locator with the text IS FOUND on the page (but there may be visible ones)
+   * @example expectText(locator, 'text', false, false) // expect that NO hidden locator with the text is found on the page (but there may be visible ones)
+   *
+   * @param locator the locator to check
+   * @param text the text to be found
+   * @param toBePresent whether a locator with the text should be present
+   * @param toBeVisible whether the locator with the text should be visible
+   * @returns void
+   */
+  expectText(locator:any, text:string, toBePresent:boolean, toBeVisible:boolean):Promise<void>;
+
+  /**
+   * A helper function for parsing elements on a page or in an element.
+   * Can be used to check for the presence OR absence of visible OR hidden elements.
+   * Examples:
+   * @example expectElement(locator, true) // expect that an element is visible (and there may be hidden ones)
+   * @example expectElement(locator, false) // expect that NO element is visible (but there may be hidden ones)
+   * @example expectElement(locator, true, false) // expect that a HIDDEN element IS FOUND on the page (but there may be visible ones)
+   * @example expectElement(locator, false, false) // expect that NO hidden element is found on the page (but there may be visible ones)
+   *
+   * @param locator the locator to check
+   * @param toBePresent whether an element should be present
+   * @param toBeVisible whether the element should be visible
+   */
+  expectElement(locator:any, toBePresent:boolean, toBeVisible:boolean):Promise<void>;
+
+  /**
+   * A helper function to get a screenshot of the current page or an element.
+   * Depending on the implementation, it may also save a screenshot to disk.
+   */
+  screenshot(opts?:{name?:string,locator?:any}):Promise<Buffer>
+
+  /**
+   * A helper function to test whether two screenshots match. The "Locator" interface used
+   * should be whatever is compatible with the testing library being integrated by your World Constructor.
+   *
+   * @param locator the locator to check
+   * @param screenshotName the name of the screenshot to compare against
+   */
+  expectScreenshotMatch(locator:any, screenshotName:string, options?:any):Promise<void>
+
+}
+
+
+export class VisualWorld extends QuickPickleWorld implements StubVisualWorldInterface {
+
+  constructor(context:TestContext, info:InfoConstructor) {
+    super(context,info)
+  }
+
+  async init() {}
+
+  get screenshotDir() {
+    return this.sanitizePath(this.worldConfig.screenshotDir)
+  }
+
+  get screenshotFilename() {
+    return `${this.toString().replace(/^.+?Feature: /, 'Feature: ').replace(' ' + this.info.step, '')}.png`
+  }
+
+  get screenshotPath() {
+    return this.fullPath(`${this.screenshotDir}/${this.screenshotFilename}`)
+  }
+
+  getScreenshotPath(name?:string) {
+    if (!name) return this.screenshotPath
+    let explodedTags = this.info.explodedIdx ? `_(${this.info.tags.join(',')})` : ''
+    return this.fullPath(`${this.screenshotDir}/${name}${explodedTags}.png`)
+  }
+
+  async screenshotDiff(actual:Buffer, expected:Buffer, opts:any): Promise<VisualDiffResult> {
+
+    // Convert Buffer to ArrayBuffer if needed
+    const actualBuffer = actual instanceof Buffer ?
+      actual.buffer.slice(actual.byteOffset, actual.byteOffset + actual.byteLength) :
+      actual;
+
+    const expectedBuffer = expected instanceof Buffer ?
+      expected.buffer.slice(expected.byteOffset, expected.byteOffset + expected.byteLength) :
+      expected;
+
+    const { width, height } = await imageSize(actualBuffer);
+    const diff = Buffer.from([])
+
+    const mismatchedPixels = pixelmatch(
+      new Uint8Array(actualBuffer),
+      new Uint8Array(expectedBuffer),
+      diff,
+      width,
+      height,
+      opts
+    );
+
+    const totalPixels = width * height;
+    const diffPercentage = (mismatchedPixels / totalPixels) * 100;
+    const pass = diffPercentage <= opts.maxDiffPercentage;
+
+    return { pass, diff, diffPercentage };
+  }
+
 }