quickpickle 1.7.1 → 1.9.0

package/dist/index.esm.js

@@ -3,6 +3,9 @@ import { intersection, isFunction, isString, concat, fromPairs, escapeRegExp, de
 import parse from '@cucumber/tag-expressions';
 import * as Gherkin from '@cucumber/gherkin';
 import * as Messages from '@cucumber/messages';
+import pixelmatch from 'pixelmatch';
+import imageSize from '@coderosh/image-size';
+import { Buffer } from 'buffer';
 
 const steps = [];
 const parameterTypeRegistry = new ParameterTypeRegistry();
@@ -80,10 +83,12 @@ function normalizeTags(tags) {
     return tags.filter(Boolean).map(tag => tag.startsWith('@') ? tag : `@${tag}`);
 }
 /**
+ * Compares two lists of tags and returns the ones that are shared by both,
+ * or null if there are no shared tags.
  *
  * @param confTags string[]
  * @param testTags string[]
- * @returns boolean
+ * @returns string[]|null
  */
 function tagsMatch(confTags, testTags) {
     let tags = intersection(confTags.map(t => t.toLowerCase()), testTags.map(t => t.toLowerCase()));
@@ -610,10 +615,130 @@ class DocString extends String {
     }
 }
 
+/**
+ * Shim for node:path.normalize
+ * @param path string
+ * @returns string
+ */
+function normalize(path) {
+    // Simple path normalization
+    const isAbsolute = path.startsWith('/');
+    const parts = path.split(/[/\\]+/).filter(Boolean);
+    const normalizedParts = [];
+    for (const part of parts) {
+        if (part === '.')
+            continue;
+        if (part === '..') {
+            normalizedParts.pop();
+        }
+        else {
+            normalizedParts.push(part);
+        }
+    }
+    return (isAbsolute ? '/' : '') + normalizedParts.join('/');
+}
+/**
+ * Shim for node:path.join
+ * @param paths string[]
+ * @returns string
+ */
+function join(...paths) {
+    return normalize(paths.join('/'));
+}
+
+const DEFAULT_OPTIONS = {
+    decode: [
+        {
+            regex: /%2e/g,
+            replacement: '.'
+        },
+        {
+            regex: /%2f/g,
+            replacement: '/'
+        },
+        {
+            regex: /%5c/g,
+            replacement: '\\'
+        }
+    ],
+    parentDirectoryRegEx: /[\/\\]\.\.[\/\\]/g,
+    notAllowedRegEx: /:|\$|!|'|"|@|\+|`|\||=/g
+};
+/**
+ * Sanitizes a portion of a path to avoid Path Traversal
+ */
+function sanitize(pathstr, options = DEFAULT_OPTIONS) {
+    if (!options)
+        options = DEFAULT_OPTIONS;
+    if (typeof options !== 'object')
+        throw new Error('options must be an object');
+    if (!Array.isArray(options.decode))
+        options.decode = DEFAULT_OPTIONS.decode;
+    if (!options.parentDirectoryRegEx)
+        options.parentDirectoryRegEx = DEFAULT_OPTIONS.parentDirectoryRegEx;
+    if (!options.notAllowedRegEx)
+        options.notAllowedRegEx = DEFAULT_OPTIONS.notAllowedRegEx;
+    if (typeof pathstr !== 'string') {
+        // Stringify the path
+        pathstr = `${pathstr}`;
+    }
+    let sanitizedPath = pathstr;
+    // ################################################################################################################
+    // Decode
+    options.decode.forEach(decode => {
+        sanitizedPath = sanitizedPath.replace(decode.regex, decode.replacement);
+    });
+    // Remove not allowed characters
+    sanitizedPath = sanitizedPath.replace(options.notAllowedRegEx, '');
+    // Replace backslashes with normal slashes
+    sanitizedPath = sanitizedPath.replace(/[\\]/g, '/');
+    // Replace /../ with /
+    sanitizedPath = sanitizedPath.replace(options.parentDirectoryRegEx, '/');
+    // Remove ../ at pos 0 and /.. at end
+    sanitizedPath = sanitizedPath.replace(/^\.\.[\/\\]/g, '/');
+    sanitizedPath = sanitizedPath.replace(/[\/\\]\.\.$/g, '/');
+    // Replace double (back)slashes with a single slash
+    sanitizedPath = sanitizedPath.replace(/[\/\\]+/g, '/');
+    // Normalize path
+    sanitizedPath = normalize(sanitizedPath);
+    // Remove / or \ in the end
+    while (sanitizedPath.endsWith('/') || sanitizedPath.endsWith('\\')) {
+        sanitizedPath = sanitizedPath.slice(0, -1);
+    }
+    // Remove / or \ in the beginning
+    while (sanitizedPath.startsWith('/') || sanitizedPath.startsWith('\\')) {
+        sanitizedPath = sanitizedPath.slice(1);
+    }
+    // Validate path
+    sanitizedPath = join('', sanitizedPath);
+    // Remove not allowed characters
+    sanitizedPath = sanitizedPath.replace(options.notAllowedRegEx, '');
+    // Again change all \ to /
+    sanitizedPath = sanitizedPath.replace(/[\\]/g, '/');
+    // Replace double (back)slashes with a single slash
+    sanitizedPath = sanitizedPath.replace(/[\/\\]+/g, '/');
+    // Replace /../ with /
+    sanitizedPath = sanitizedPath.replace(options.parentDirectoryRegEx, '/');
+    // Remove ./ or / at start
+    while (sanitizedPath.startsWith('/') || sanitizedPath.startsWith('./') || sanitizedPath.endsWith('/..') || sanitizedPath.endsWith('/../') || sanitizedPath.startsWith('../') || sanitizedPath.startsWith('/../')) {
+        sanitizedPath = sanitizedPath.replace(/^\.\//g, ''); // ^./
+        sanitizedPath = sanitizedPath.replace(/^\//g, ''); // ^/
+        // Remove ../ | /../ at pos 0 and /.. | /../ at end
+        sanitizedPath = sanitizedPath.replace(/^[\/\\]\.\.[\/\\]/g, '/');
+        sanitizedPath = sanitizedPath.replace(/^\.\.[\/\\]/g, '/');
+        sanitizedPath = sanitizedPath.replace(/[\/\\]\.\.$/g, '/');
+        sanitizedPath = sanitizedPath.replace(/[\/\\]\.\.\/$/g, '/');
+    }
+    // Make sure out is not "."
+    sanitizedPath = sanitizedPath.trim() === '.' ? '' : sanitizedPath;
+    return sanitizedPath.trim();
+}
+
 class QuickPickleWorld {
     constructor(context, info) {
         this._projectRoot = '';
         this.data = {};
+        this.sanitizePath = sanitize;
         this.context = context;
         this.common = info.common;
         this.info = { ...info, errors: [] };
@@ -623,10 +748,44 @@ class QuickPickleWorld {
     get config() { return this.info.config; }
     get worldConfig() { return this.info.config.worldConfig; }
     get isComplete() { return this.info.stepIdx === this.info.steps.length; }
-    get projectRoot() { return this._projectRoot; }
+    /**
+     * 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) {
         return tagsMatch(tags, this.info.tags);
     }
+    /**
+     * 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) {
+        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) {
+        await new Promise(r => setTimeout(r, ms));
+    }
     toString() {
         let parts = [
             this.constructor.name,
@@ -644,6 +803,48 @@ function getWorldConstructor() {
 function setWorldConstructor(constructor) {
     worldConstructor = constructor;
 }
+const defaultScreenshotComparisonOptions = {
+    maxDiffPercentage: 0,
+    threshold: 0.1,
+    alpha: 0.6
+};
+class VisualWorld extends QuickPickleWorld {
+    constructor(context, info) {
+        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) {
+        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, expected, opts) {
+        // 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 };
+    }
+}
 
 const featureRegex = /\.feature(?:\.md)?$/;
 const Given = addStepDefinition;
@@ -811,5 +1012,5 @@ const quickpickle = (conf = {}) => {
     };
 };
 
-export { After, AfterAll, AfterStep, Before, BeforeAll, BeforeStep, DataTable, DocString, Given, QuickPickleWorld, Then, When, applyHooks, quickpickle as default, defaultConfig, defineParameterType, explodeTags, formatStack, getWorldConstructor, gherkinStep, normalizeTags, quickpickle, setWorldConstructor, tagsMatch };
+export { After, AfterAll, AfterStep, Before, BeforeAll, BeforeStep, DataTable, DocString, Given, QuickPickleWorld, Then, VisualWorld, When, applyHooks, quickpickle as default, defaultConfig, defaultScreenshotComparisonOptions, defineParameterType, explodeTags, formatStack, getWorldConstructor, gherkinStep, normalizeTags, quickpickle, setWorldConstructor, tagsMatch };
 //# sourceMappingURL=index.esm.js.map