quickpickle 1.7.1 → 1.9.0

package/dist/world.d.ts

@@ -1,5 +1,10 @@
 import type { TestContext } from 'vitest';
 import type { QuickPickleConfig } from '.';
+import sanitize from './shims/path-sanitizer';
+import { type PixelmatchOptions } from 'pixelmatch';
+import type { AriaRole } from '@a11y-tools/aria-roles';
+export type AriaRoleExtended = AriaRole & 'element' | 'input';
+import { Buffer } from 'buffer';
 interface Common {
     info: {
         feature: string;
@@ -29,9 +34,11 @@ export interface QuickPickleWorldInterface {
         [key: string]: any;
     };
     common: Common;
-    projectRoot: string;
     init: () => Promise<void>;
     tagsMatch(tags: string[]): string[] | null;
+    sanitizePath: typeof sanitize;
+    fullPath(path: string): string;
+    wait(ms: number): Promise<void>;
 }
 export type InfoConstructor = Omit<QuickPickleWorldInterface['info'], 'errors'> & {
     common: Common;
@@ -42,6 +49,7 @@ export declare class QuickPickleWorld implements QuickPickleWorldInterface {
     common: QuickPickleWorldInterface['common'];
     context: TestContext;
     data: {};
+    sanitizePath: typeof sanitize;
     constructor(context: TestContext, info: InfoConstructor);
     init(): Promise<void>;
     get config(): QuickPickleConfig;
@@ -49,11 +57,192 @@ export declare class QuickPickleWorld implements QuickPickleWorldInterface {
         [key: string]: any;
     }>;
     get isComplete(): boolean;
-    get projectRoot(): string;
+    /**
+     * Checks the tags of the Scenario against a provided list of tags,
+     * and returns the shared tags, with the "@" prefix character.
+     *
+     * @param tags tags to check
+     * @returns string[]|null
+     */
     tagsMatch(tags: string[]): string[] | null;
+    /**
+     * Given a provided path-like string, returns a full path that:
+     *
+     * 1. contains no invalid characters.
+     * 2. is a subdirectory of the project root.
+     *
+     * This is intended for security when retrieving and saving files;
+     * it does not slugify filenames or check for a file's existence.
+     *
+     * @param path string the path to sanitize
+     * @return string the sanitized path, including the project root
+     */
+    fullPath(path: string): string;
+    /**
+     * 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
+     */
+    wait(ms: number): Promise<void>;
     toString(): string;
 }
 export type WorldConstructor = new (context: TestContext, info: InfoConstructor) => QuickPickleWorldInterface;
 export declare function getWorldConstructor(): WorldConstructor;
 export declare function setWorldConstructor(constructor: WorldConstructor): void;
+export type VisualDiffResult = {
+    pass: boolean;
+    diff: Buffer;
+    diffPercentage: number;
+};
+export type ScreenshotComparisonOptions = any & Partial<PixelmatchOptions> & {
+    maxDiffPercentage?: number;
+};
+export declare const defaultScreenshotComparisonOptions: ScreenshotComparisonOptions;
+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 declare class VisualWorld extends QuickPickleWorld implements StubVisualWorldInterface {
+    constructor(context: TestContext, info: InfoConstructor);
+    init(): Promise<void>;
+    get screenshotDir(): string;
+    get screenshotFilename(): string;
+    get screenshotPath(): string;
+    getScreenshotPath(name?: string): string;
+    screenshotDiff(actual: Buffer, expected: Buffer, opts: any): Promise<VisualDiffResult>;
+}
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quickpickle",
-  "version": "1.7.1",
+  "version": "1.9.0",
   "description": "Plugin for Vitest to run tests written in Gherkin Syntax.",
   "keywords": [
     "BDD",
@@ -34,18 +34,14 @@
   "files": [
     "dist"
   ],
-  "scripts": {
-    "build": "rollup -c && FORMAT=cjs rollup -c",
-    "type-check": "tsc --noEmit",
-    "test:watch": "vitest",
-    "test": "vitest --run"
-  },
   "dependencies": {
-    "@cucumber/cucumber": "^11.2.0",
+    "@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 +54,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"
@@ -71,5 +66,12 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/dnotes/quickpickle.git"
+  },
+  "scripts": {
+    "build": "rollup -c && FORMAT=cjs rollup -c",
+    "download:path-sanitizer": "scripts/path-sanitizer.sh",
+    "type-check": "tsc --noEmit",
+    "test:watch": "vitest",
+    "test": "vitest --run"
   }
-}
+}