feat: adds VisualWorld interfaces and class

Author: dnotes

.changeset/small-experts-stick.md

@@ -0,0 +1,9 @@
+---
+"@quickpickle/playwright": minor
+"quickpickle": minor
+---
+
+This release adds new interfaces and world constructor class for a "VisualWorld"
+to QuickPickle main library. All visual testing libraries (Playwright, Vitest Browser)
+should implement the VisualWorldInterface, and may extend the VisualWorld class,
+which encapsulates helpful functionality for screenshots.

packages/main/src/index.ts

@@ -27,6 +27,7 @@ export {
   VisualDiffResult,
   defaultScreenshotComparisonOptions,
   InfoConstructor,
+  AriaRoleExtended,
 } from './world';
 export { DocString, DataTable }
 export { explodeTags, tagsMatch, normalizeTags, applyHooks }

packages/main/src/shims/png.ts

@@ -0,0 +1,42 @@
+// PNG shim that works in both browser and Node.js environments
+// Uses dynamic imports instead of require()
+
+// Define the PNG constructor type
+interface PNGConstructor {
+  new (options?: { width?: number; height?: number }): PNGInstance;
+  sync: {
+    read(data: Buffer): PNGInstance;
+    write(png: PNGInstance): Buffer;
+  };
+}
+
+interface PNGInstance {
+  width: number;
+  height: number;
+  data: Buffer;
+}
+
+// Check if we're in a browser environment
+const isBrowser = typeof window !== 'undefined' && typeof document !== 'undefined';
+
+// Create a promise that resolves to the PNG constructor
+let pngPromise: Promise<PNGConstructor>;
+
+if (isBrowser) {
+  // Browser environment - use browser build
+  pngPromise = import('pngjs/browser').then(mod => mod.PNG);
+} else {
+  // Node.js environment - use main build
+  pngPromise = import('pngjs').then(mod => mod.PNG);
+}
+
+// Cache the PNG constructor once loaded
+let cachedPNG: PNGConstructor | null = null;
+
+export async function getPNG(): Promise<PNGConstructor> {
+  if (!cachedPNG) {
+    cachedPNG = await pngPromise;
+  }
+  return cachedPNG;
+}
+

packages/main/src/world.ts

@@ -4,9 +4,10 @@ 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'
+export type AriaRoleExtended = AriaRole|'element'|'input'
 import { Buffer } from 'buffer'
-import { PNG } from 'pngjs/browser'
+import { getPNG } from './shims/png.js'
+import { defaultsDeep } from 'lodash-es';
 
 interface Common {
   info: {
@@ -168,6 +169,11 @@ interface StubVisualWorldInterface extends QuickPickleWorldInterface {
    */
   screenshotPath:string
 
+  /**
+   * The options for the default screenshot comparisons.
+   */
+  screenshotOptions:Partial<ScreenshotComparisonOptions>
+
   /**
    * 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
@@ -290,6 +296,8 @@ export interface VisualWorldInterface extends StubVisualWorldInterface {
    */
   expectScreenshotMatch(locator:any, screenshotName:string, options?:any):Promise<void>
 
+  screenshotOptions:Partial<ScreenshotComparisonOptions>
+
 }
 
 
@@ -313,6 +321,10 @@ export class VisualWorld extends QuickPickleWorld implements StubVisualWorldInte
     return this.fullPath(`${this.screenshotDir}/${this.screenshotFilename}`)
   }
 
+  get screenshotOptions() {
+    return defaultsDeep((this.worldConfig.screenshotOptions || {}), (this.worldConfig.screenshotOpts || {}), defaultScreenshotComparisonOptions)
+  }
+
   getScreenshotPath(name?:string) {
     if (!name) return this.screenshotPath
     let explodedTags = this.info.explodedIdx ? `_(${this.info.tags.join(',')})` : ''
@@ -321,6 +333,9 @@ export class VisualWorld extends QuickPickleWorld implements StubVisualWorldInte
 
   async screenshotDiff(actual:Buffer, expected:Buffer, opts:any): Promise<VisualDiffResult> {
 
+    // Get the PNG constructor using the shim
+    const PNG = await getPNG()
+
     // Parse PNG images to get raw pixel data
     const actualPng = PNG.sync.read(actual)
     const expectedPng = PNG.sync.read(expected)

packages/playwright/src/PlaywrightWorld.ts

@@ -1,9 +1,10 @@
 import { chromium, firefox, Locator, webkit, type Browser, type BrowserContext, type Page } from 'playwright';
-import { normalizeTags, QuickPickleWorld, QuickPickleWorldInterface } from 'quickpickle';
+import { normalizeTags, VisualWorld, VisualWorldInterface, ScreenshotComparisonOptions, AriaRoleExtended } from 'quickpickle';
 import { After } from 'quickpickle';
 import type { TestContext } from 'vitest';
 import { defaultsDeep } from 'lodash-es'
 import { InfoConstructor } from 'quickpickle/dist/world';
+import { Buffer } from 'buffer';
 
 import { expect } from '@playwright/test';
 import { ScreenshotSetting } from './snapshotMatcher';
@@ -56,7 +57,7 @@ export type PlaywrightWorldConfig = typeof defaultPlaywrightWorldConfig & {
   browserSizes: Record<string,string>
 }
 
-export class PlaywrightWorld extends QuickPickleWorld {
+export class PlaywrightWorld extends VisualWorld implements VisualWorldInterface {
   browser!: Browser
   browserContext!: BrowserContext
   page!: Page
@@ -161,25 +162,6 @@ export class PlaywrightWorld extends QuickPickleWorld {
     return this.worldConfig
   }
 
-  get screenshotDir() {
-    return this.sanitizePath(this.worldConfig.screenshotDir)
-  }
-
-  get screenshotPath() {
-    return this.fullPath(`${this.worldConfig.screenshotDir}/${this.screenshotFilename}`)
-  }
-
-  get screenshotFilename() {
-    return `${this.toString().replace(/^.+?Feature: /, 'Feature: ').replace(' ' + this.info.step, '')}.png`
-  }
-
-  /**
-   * @deprecated Use `screenshotPath` instead
-   */
-  get fullScreenshotPath() {
-    return this.screenshotPath
-  }
-
   /**
     * Gets a locator based on a certain logic
     * @example getLocator(page, 'Cancel', 'button') => page.getByRole('button', { name: 'Cancel' })
@@ -192,7 +174,7 @@ export class PlaywrightWorld extends QuickPickleWorld {
     * @param text Optional text to match inside the locator
     * @returns Promise<void>
     */
-  getLocator(el:Locator|Page, identifier:string, role:string|'element'|'input', text:string|null=null) {
+  getLocator(el:Locator|Page, identifier:string, role:AriaRoleExtended, text:string|null=null) {
     let locator:Locator
     if (role === 'element') locator = el.locator(identifier)
     else if (role === 'input') locator = el.getByLabel(identifier).or(el.getByPlaceholder(identifier))
@@ -240,7 +222,7 @@ export class PlaywrightWorld extends QuickPickleWorld {
     * @param px The number of pixels to scroll (defaults to 100)
     * @returns Promise<void>
     */
-  async scroll(direction:"up"|"down"|"left"|"right", px = 100) {
+  async scroll(locator:Locator|Page, direction:"up"|"down"|"left"|"right", px = 100) {
     let horiz = direction.includes('t')
     if (horiz) await this.page.mouse.wheel(direction === 'right' ? px : -px, 0)
     else await this.page.mouse.wheel(0, direction === 'down' ? px : -px)
@@ -322,14 +304,15 @@ export class PlaywrightWorld extends QuickPickleWorld {
     }
   }
 
-  async screenshot(opts?:{
-    name?:string
-    locator?:Locator
-  }) {
+  async screenshot(opts?:{name?:string,locator?:any}):Promise<Buffer> {
     let explodedTags = this.info.explodedIdx ? `_(${this.info.tags.join(',')})` : ''
     let path = opts?.name ? this.fullPath(`${this.screenshotDir}/${opts.name}${explodedTags}.png`) : this.screenshotPath
     let locator = opts?.locator ?? this.page
-    return await locator.screenshot({ path, ...this.worldConfig.screenshotOpts })
+    return await locator.screenshot({ path, ...this.screenshotOptions })
+  }
+
+  async expectScreenshotMatch(locator:Locator|Page, screenshotName:string, options?:Partial<ScreenshotComparisonOptions>):Promise<void> {
+    await expect(locator).toMatchScreenshot(screenshotName, defaultsDeep(options || {}, this.screenshotOptions))
   }
 
 }

packages/playwright/src/actions.steps.ts

@@ -105,7 +105,7 @@ When('I enter/fill (in )the following( fields):', async function (world:Playwrig
       value = role
       role = 'input'
     }
-    let locator = world.getLocator(world.page, identifier, role)
+    let locator = world.getLocator(world.page, identifier, role as any)
     await world.setValue(locator, value)
   }
 })
@@ -145,11 +145,11 @@ When('I wait (for ){float} second(s)', async function (world:PlaywrightWorld, nu
 
 When('I scroll down/up/left/right', async function (world:PlaywrightWorld) {
   let direction = world.info.step?.match(/(down|up|left|right)$/)![0] as 'down'|'up'|'left'|'right'
-  await world.scroll(direction)
+  await world.scroll(world.page, direction)
 })
 When('I scroll down/up/left/right {int}(px)( pixels)', async function (world:PlaywrightWorld, num) {
   let direction = world.info.step?.match(/(down|up|left|right)(?= \d)/)![0] as 'down'|'up'|'left'|'right'
-  await world.scroll(direction, num)
+  await world.scroll(world.page, direction, num)
 })
 
 // ================
@@ -162,11 +162,11 @@ Then('(I )take (a )screenshot named {string}', async function (world:PlaywrightW
   await world.screenshot({ name })
 })
 Then('(I )take (a )screenshot of the {string} {word}', async function (world:PlaywrightWorld, identifier:string, role:string) {
-  let locator = world.getLocator(world.page, identifier, role)
+  let locator = world.getLocator(world.page, identifier, role as any)
   await world.screenshot({ locator })
 })
 Then('(I )take (a )screenshot of the {string} {word} named {string}', async function (world:PlaywrightWorld, identifier:string, role:string, name:string) {
-  let locator = world.getLocator(world.page, identifier, role)
+  let locator = world.getLocator(world.page, identifier, role as any)
   await world.screenshot({ locator, name })
 })