@alwaysmeticulous/cli 2.3.4 → 2.4.0

package/dist/command-utils/command-utils.d.ts

@@ -0,0 +1,9 @@
+declare type UndefinedToNullOrUndefined<T extends object> = {
+    [K in keyof T]: undefined extends T[K] ? T[K] | null : T[K];
+};
+/**
+ * yargs normally passes through undefineds, but passes through nulls for
+ * numbers which fail to parse. We convert everything to undefined to standardize.
+ */
+export declare const handleNulls: <T extends object>(handler: (args: T) => Promise<void>) => (args: UndefinedToNullOrUndefined<T>) => Promise<void>;
+export {};

package/dist/command-utils/command-utils.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.handleNulls = void 0;
+/**
+ * yargs normally passes through undefineds, but passes through nulls for
+ * numbers which fail to parse. We convert everything to undefined to standardize.
+ */
+const handleNulls = (handler) => {
+    return (args) => {
+        const keys = Object.keys(args);
+        const newArgs = keys.reduce((partialArgs, key) => ({
+            ...partialArgs,
+            [key]: args[key] === null ? undefined : args[key],
+        }), {});
+        return handler(newArgs);
+    };
+};
+exports.handleNulls = handleNulls;

package/dist/command-utils/common-options.d.ts

@@ -0,0 +1,110 @@
+export declare const OPTIONS: {
+    apiToken: {
+        string: boolean;
+    };
+    commitSha: {
+        string: boolean;
+    };
+    headless: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    devTools: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    bypassCSP: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    padTime: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    shiftTime: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    networkStubbing: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    accelerate: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    moveBeforeClick: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    diffThreshold: {
+        number: boolean;
+        description: string;
+        default: number;
+    };
+    diffPixelThreshold: {
+        number: boolean;
+        description: string;
+        default: number;
+    };
+};
+export declare const SCREENSHOT_DIFF_OPTIONS: {
+    diffThreshold: {
+        number: boolean;
+        description: string;
+        default: number;
+    };
+    diffPixelThreshold: {
+        number: boolean;
+        description: string;
+        default: number;
+    };
+};
+/**
+ * Options that are passed onto replayEvents, that are shared by the replay, run-all-tests, and create-test commands
+ */
+export declare const COMMON_REPLAY_OPTIONS: {
+    headless: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    devTools: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    bypassCSP: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    padTime: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    shiftTime: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    networkStubbing: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+    accelerate: {
+        boolean: boolean;
+        description: string;
+        default: boolean;
+    };
+};

package/dist/command-utils/common-options.js

@@ -0,0 +1,87 @@
+"use strict";
+// We keep all options that are used by multiple commands in one file.
+// This ensures the defaults and descriptions stay in sync. Where we do want
+// a different default or description we override it, like:
+//
+//  headless: {
+//    ...COMMON_REPLAY_OPTIONS.headless,
+//    default: true,
+//  },
+//
+// This then makes the difference in behaviour explicit
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMON_REPLAY_OPTIONS = exports.SCREENSHOT_DIFF_OPTIONS = exports.OPTIONS = void 0;
+exports.OPTIONS = {
+    apiToken: {
+        string: true,
+    },
+    commitSha: {
+        string: true,
+    },
+    headless: {
+        boolean: true,
+        description: "Start browser in headless mode",
+        default: false,
+    },
+    devTools: {
+        boolean: true,
+        description: "Open Chrome Dev Tools",
+        default: false,
+    },
+    bypassCSP: {
+        boolean: true,
+        description: "Enables bypass CSP in the browser (danger: this could mean you tests hit your production backend)",
+        default: false,
+    },
+    padTime: {
+        boolean: true,
+        description: "Pad replay time according to recording duration. Please note this option will be ignored if running with the '--accelerate' option.",
+        default: true,
+    },
+    shiftTime: {
+        boolean: true,
+        description: "Shift time during simulation to be set as the recording time",
+        default: true,
+    },
+    networkStubbing: {
+        boolean: true,
+        description: "Stub network requests during replay",
+        default: true,
+    },
+    accelerate: {
+        boolean: true,
+        description: "Fast forward through any pauses to replay as fast as possible. Warning: this option is experimental and may be deprecated",
+        default: false,
+    },
+    moveBeforeClick: {
+        boolean: true,
+        description: "Simulate mouse movement before clicking",
+        default: false,
+    },
+    diffThreshold: {
+        number: true,
+        description: "Acceptable maximum proportion of changed pixels, between 0 and 1. If this proportion is exceeded then the test will fail.",
+        default: 0.01,
+    },
+    diffPixelThreshold: {
+        number: true,
+        description: "A number between 0 and 1. Color/brightness differences in individual pixels will be ignored if the difference is less than this threshold. A value of 1.0 would accept any difference in color, while a value of 0.0 would accept no difference in color.",
+        default: 0.01,
+    },
+};
+exports.SCREENSHOT_DIFF_OPTIONS = {
+    diffThreshold: exports.OPTIONS.diffThreshold,
+    diffPixelThreshold: exports.OPTIONS.diffPixelThreshold,
+};
+/**
+ * Options that are passed onto replayEvents, that are shared by the replay, run-all-tests, and create-test commands
+ */
+exports.COMMON_REPLAY_OPTIONS = {
+    headless: exports.OPTIONS.headless,
+    devTools: exports.OPTIONS.devTools,
+    bypassCSP: exports.OPTIONS.bypassCSP,
+    padTime: exports.OPTIONS.padTime,
+    shiftTime: exports.OPTIONS.shiftTime,
+    networkStubbing: exports.OPTIONS.networkStubbing,
+    accelerate: exports.OPTIONS.accelerate,
+};

package/dist/command-utils/common-types.d.ts

@@ -0,0 +1,20 @@
+import { ScreenshottingEnabledOptions } from "@alwaysmeticulous/common";
+/**
+ * Options for taking a screenshot and comparing it against a previous screenshot
+ */
+export declare type ScreenshotAssertionsOptions = {
+    enabled: false;
+} | ScreenshotAssertionsEnabledOptions;
+export interface ScreenshotAssertionsEnabledOptions extends ScreenshottingEnabledOptions {
+    diffOptions: ScreenshotDiffOptions;
+}
+export interface ScreenshotDiffOptions {
+    /**
+     * Acceptable maximum proportion of changed pixels, between 0 and 1.
+     */
+    diffThreshold: number;
+    /**
+     * A number between 0 and 1. Color/brightness differences in individual pixels will be ignored if the difference is less than this threshold. A value of 1.0 would accept any difference in color, while a value of 0.0 would accept no difference in color.
+     */
+    diffPixelThreshold: number;
+}

package/dist/command-utils/common-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/create-test/create-test.command.d.ts

@@ -1,7 +1,7 @@
 import { CommandModule } from "yargs";
 import { RecordCommandHandlerOptions } from "../record/record.command";
-import { ReplayCommandHandlerOptions } from "../replay/replay.command";
-interface Options extends RecordCommandHandlerOptions, ReplayCommandHandlerOptions {
+import { RawReplayCommandHandlerOptions } from "../replay/replay.command";
+interface Options extends Omit<RecordCommandHandlerOptions, "devTools" | "bypassCSP">, RawReplayCommandHandlerOptions {
 }
 export declare const createTest: CommandModule<unknown, Options>;
 export {};

package/dist/commands/create-test/create-test.command.js

@@ -5,13 +5,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createTest = void 0;
 const common_1 = require("@alwaysmeticulous/common");
-const loglevel_1 = __importDefault(require("loglevel"));
 const chalk_1 = __importDefault(require("chalk"));
 const inquirer_1 = __importDefault(require("inquirer"));
+const loglevel_1 = __importDefault(require("loglevel"));
+const common_options_1 = require("../../command-utils/common-options");
+const config_utils_1 = require("../../utils/config.utils");
 const sentry_utils_1 = require("../../utils/sentry.utils");
 const record_command_1 = require("../record/record.command");
 const replay_command_1 = require("../replay/replay.command");
-const config_utils_1 = require("../../utils/config.utils");
 const handleTestCreation = async (replay, sessionId) => {
     const logger = loglevel_1.default.getLogger(common_1.METICULOUS_LOGGER_NAME);
     const validationResponse = await inquirer_1.default.prompt([
@@ -102,8 +103,19 @@ headless, screenshotSelector, padTime, shiftTime, networkStubbing, moveBeforeCli
         moveBeforeClick,
         cookiesFile,
         accelerate,
+        save: false,
+        // We replay against the original recorded URL
+        appUrl: undefined,
+        simulationIdForAssets: undefined,
+        // We don't try comparing to the original screenshot, so just set these to their defaults
+        baseSimulationId: undefined,
+        diffThreshold: common_options_1.OPTIONS.diffThreshold.default,
+        diffPixelThreshold: common_options_1.OPTIONS.diffPixelThreshold.default,
+        // We don't expose these options
+        maxDurationMs: undefined,
+        maxEventCount: undefined,
     };
-    const replay = await (0, replay_command_1.replayCommandHandler)(replayOptions);
+    const replay = await (0, replay_command_1.rawReplayCommandHandler)(replayOptions);
     await handleTestCreation(replay, lastSessionId);
 };
 exports.createTest = {
@@ -111,21 +123,8 @@ exports.createTest = {
     describe: "Create a new test",
     builder: {
         // Common options
-        apiToken: {
-            string: true,
-            demandOption: true,
-        },
-        commitSha: {
-            string: true,
-        },
-        devTools: {
-            boolean: true,
-            description: "Open Chrome Dev Tools",
-        },
-        bypassCSP: {
-            boolean: true,
-            description: "Enables bypass CSP in the browser",
-        },
+        apiToken: common_options_1.OPTIONS.apiToken,
+        commitSha: common_options_1.OPTIONS.commitSha,
         // Record options
         width: {
             number: true,
@@ -147,30 +146,10 @@ exports.createTest = {
             description: "Enable verbose logging",
         },
         // Replay options
-        headless: {
-            boolean: true,
-            description: "Start browser in headless mode",
-            default: true,
-        },
         screenshotSelector: {
             string: true,
             description: "Query selector to screenshot a specific DOM element instead of the whole page",
         },
-        padTime: {
-            boolean: true,
-            description: "Pad simulation time according to recording duration",
-            default: true,
-        },
-        shiftTime: {
-            boolean: true,
-            description: "Shift time during simulation to be set as the recording time",
-            default: true,
-        },
-        networkStubbing: {
-            boolean: true,
-            description: "Stub network requests during simulation",
-            default: true,
-        },
         moveBeforeClick: {
             boolean: true,
             description: "Simulate mouse movement before clicking",
@@ -179,10 +158,14 @@ exports.createTest = {
             string: true,
             description: "Path to cookies to inject before simulation",
         },
+        ...common_options_1.COMMON_REPLAY_OPTIONS,
+        headless: {
+            ...common_options_1.COMMON_REPLAY_OPTIONS.headless,
+            default: true,
+        },
         accelerate: {
-            boolean: true,
+            ...common_options_1.COMMON_REPLAY_OPTIONS.accelerate,
             description: "Fast forward through any pauses to replay as fast as possible when replaying for the first time to create the test. Warning: this option is experimental and may be deprecated",
-            default: false,
         },
     },
     handler: (0, sentry_utils_1.wrapHandler)(handler),

package/dist/commands/record/record.command.d.ts

@@ -1,14 +1,14 @@
 import { CommandModule } from "yargs";
 export interface RecordCommandHandlerOptions {
-    apiToken?: string | null | undefined;
-    commitSha?: string | null | undefined;
-    devTools?: boolean | null | undefined;
-    bypassCSP?: boolean | null | undefined;
-    width?: number | null | undefined;
-    height?: number | null | undefined;
-    uploadIntervalMs?: number | null | undefined;
-    incognito?: boolean | null | undefined;
-    trace?: boolean | null | undefined;
+    apiToken: string | undefined;
+    commitSha: string | undefined;
+    devTools: boolean | undefined;
+    bypassCSP: boolean | undefined;
+    width: number | undefined;
+    height: number | undefined;
+    uploadIntervalMs: number | undefined;
+    incognito: boolean | undefined;
+    trace: boolean | undefined;
     onDetectedSession?: (sessionId: string) => void;
 }
 export declare const recordCommandHandler: (options: RecordCommandHandlerOptions) => Promise<void>;

package/dist/commands/record/record.command.js

@@ -10,6 +10,7 @@ const path_1 = require("path");
 const client_1 = require("../../api/client");
 const project_api_1 = require("../../api/project.api");
 const session_api_1 = require("../../api/session.api");
+const command_utils_1 = require("../../command-utils/command-utils");
 const replay_assets_1 = require("../../local-data/replay-assets");
 const commit_sha_utils_1 = require("../../utils/commit-sha.utils");
 const sentry_utils_1 = require("../../utils/sentry.utils");
@@ -138,5 +139,5 @@ exports.record = {
             description: "Enable verbose logging",
         },
     },
-    handler: (0, sentry_utils_1.wrapHandler)(exports.recordCommandHandler),
+    handler: (0, sentry_utils_1.wrapHandler)((0, command_utils_1.handleNulls)(exports.recordCommandHandler)),
 };

package/dist/commands/replay/replay.command.d.ts

@@ -1,30 +1,28 @@
 import { Replay } from "@alwaysmeticulous/common";
+import { ReplayExecutionOptions, ReplayTarget } from "@alwaysmeticulous/common/dist/types/replay.types";
 import { CommandModule } from "yargs";
-export interface ReplayCommandHandlerOptions {
-    apiToken?: string | null | undefined;
-    commitSha?: string | null | undefined;
-    sessionId: string;
-    appUrl?: string | null | undefined;
-    simulationIdForAssets?: string | null | undefined;
-    headless?: boolean | null | undefined;
-    devTools?: boolean | null | undefined;
-    bypassCSP?: boolean | null | undefined;
+import { ScreenshotDiffOptions, ScreenshotAssertionsOptions } from "../../command-utils/common-types";
+export interface ReplayOptions extends AdditionalReplayOptions {
+    replayTarget: ReplayTarget;
+    executionOptions: ReplayExecutionOptions;
+    screenshottingOptions: ScreenshotAssertionsOptions;
+    exitOnMismatch: boolean;
+}
+export declare const replayCommandHandler: ({ replayTarget, executionOptions, screenshottingOptions, apiToken, sessionId, commitSha: commitSha_, save, exitOnMismatch, baseSimulationId: baseReplayId_, cookiesFile, }: ReplayOptions) => Promise<Replay>;
+export interface RawReplayCommandHandlerOptions extends ScreenshotDiffOptions, ReplayExecutionOptions, AdditionalReplayOptions {
     screenshot: boolean;
-    screenshotSelector?: string | null | undefined;
-    baseSimulationId?: string | null | undefined;
-    diffThreshold?: number | null | undefined;
-    diffPixelThreshold?: number | null | undefined;
-    save?: boolean | null | undefined;
-    exitOnMismatch?: boolean | null | undefined;
-    padTime: boolean;
-    shiftTime: boolean;
-    networkStubbing: boolean;
-    moveBeforeClick?: boolean | null | undefined;
-    cookies?: Record<string, any>[];
-    cookiesFile?: string | null | undefined;
-    accelerate: boolean;
-    maxDurationMs?: number | null | undefined;
-    maxEventCount?: number | null | undefined;
+    appUrl: string | undefined;
+    simulationIdForAssets: string | undefined;
+    screenshotSelector: string | undefined;
+}
+interface AdditionalReplayOptions {
+    apiToken: string | undefined;
+    commitSha: string | undefined;
+    sessionId: string;
+    save: boolean | undefined;
+    baseSimulationId: string | undefined;
+    cookiesFile: string | undefined;
 }
-export declare const replayCommandHandler: (options: ReplayCommandHandlerOptions) => Promise<Replay>;
-export declare const replay: CommandModule<unknown, ReplayCommandHandlerOptions>;
+export declare const rawReplayCommandHandler: ({ apiToken, commitSha, sessionId, appUrl, simulationIdForAssets, headless, devTools, bypassCSP, screenshot, screenshotSelector, baseSimulationId, diffThreshold, diffPixelThreshold, save, padTime, shiftTime, networkStubbing, moveBeforeClick, cookiesFile, accelerate, maxDurationMs, maxEventCount, }: RawReplayCommandHandlerOptions) => Promise<Replay>;
+export declare const replay: CommandModule<unknown, RawReplayCommandHandlerOptions>;
+export {};