@alwaysmeticulous/cli 2.3.2 → 2.4.0

package/dist/commands/replay/replay.command.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.replay = exports.replayCommandHandler = void 0;
+exports.replay = exports.rawReplayCommandHandler = exports.replayCommandHandler = void 0;
 const common_1 = require("@alwaysmeticulous/common");
 const promises_1 = require("fs/promises");
 const loglevel_1 = __importDefault(require("loglevel"));
@@ -13,17 +13,19 @@ const client_1 = require("../../api/client");
 const replay_api_1 = require("../../api/replay.api");
 const upload_1 = require("../../api/upload");
 const archive_1 = require("../../archive/archive");
+const common_options_1 = require("../../command-utils/common-options");
 const local_data_utils_1 = require("../../local-data/local-data.utils");
 const replay_assets_1 = require("../../local-data/replay-assets");
 const replays_1 = require("../../local-data/replays");
+const serve_assets_from_simulation_1 = require("../../local-data/serve-assets-from-simulation");
 const sessions_1 = require("../../local-data/sessions");
 const commit_sha_utils_1 = require("../../utils/commit-sha.utils");
+const config_utils_1 = require("../../utils/config.utils");
 const sentry_utils_1 = require("../../utils/sentry.utils");
 const version_utils_1 = require("../../utils/version.utils");
 const screenshot_diff_command_1 = require("../screenshot-diff/screenshot-diff.command");
-const config_utils_1 = require("../../utils/config.utils");
-const serve_assets_from_simulation_1 = require("../../local-data/serve-assets-from-simulation");
-const replayCommandHandler = async ({ apiToken, commitSha: commitSha_, sessionId, appUrl, simulationIdForAssets, headless, devTools, bypassCSP, screenshot, screenshotSelector, baseSimulationId: baseReplayId_, diffThreshold, diffPixelThreshold, save, exitOnMismatch, padTime, shiftTime, networkStubbing, moveBeforeClick, cookies, cookiesFile, accelerate, }) => {
+const command_utils_1 = require("../../command-utils/command-utils");
+const replayCommandHandler = async ({ replayTarget, executionOptions, screenshottingOptions, apiToken, sessionId, commitSha: commitSha_, save, exitOnMismatch, baseSimulationId: baseReplayId_, cookiesFile, }) => {
     const logger = loglevel_1.default.getLogger(common_1.METICULOUS_LOGGER_NAME);
     const client = (0, client_1.createClient)({ apiToken });
     // 1. Check session files
@@ -34,9 +36,7 @@ const replayCommandHandler = async ({ apiToken, commitSha: commitSha_, sessionId
     logger.debug(`Commit: ${commitSha}`);
     const meticulousSha = await (0, version_utils_1.getMeticulousVersion)();
     // 3. If simulationIdForAssets specified then download assets & spin up local server
-    const server = simulationIdForAssets
-        ? await (0, serve_assets_from_simulation_1.serveAssetsFromSimulation)(client, simulationIdForAssets)
-        : undefined;
+    const { appUrl, closeServer } = await serveOrGetAppUrl(client, replayTarget);
     // 4. Load replay assets
     const browserUserInteractions = await (0, replay_assets_1.fetchAsset)("replay/v2/snippet-user-interactions.bundle.js");
     const browserPlayback = await (0, replay_assets_1.fetchAsset)("replay/v2/snippet-playback.bundle.js");
@@ -65,16 +65,14 @@ const replayCommandHandler = async ({ apiToken, commitSha: commitSha_, sessionId
     const tempDir = await (0, promises_1.mkdtemp)((0, path_1.join)((0, common_1.getMeticulousLocalDataDir)(), "replays", tempDirName));
     // 6. Create and save replay parameters
     const replayEventsParams = {
-        appUrl: server ? server.url : appUrl || "",
+        appUrl,
+        replayExecutionOptions: executionOptions,
         browser: null,
         outputDir: tempDir,
         session,
         sessionData,
         recordingId: "manual-replay",
         meticulousSha: "meticulousSha",
-        headless: headless || false,
-        devTools: devTools || false,
-        bypassCSP: bypassCSP || false,
         dependencies: {
             browserUserInteractions: {
                 key: "browserUserInteractions",
@@ -101,21 +99,14 @@ const replayCommandHandler = async ({ apiToken, commitSha: commitSha_, sessionId
                 location: nodeUserInteractions,
             },
         },
-        padTime,
-        shiftTime,
-        screenshot: screenshot,
-        screenshotSelector: screenshotSelector || "",
-        networkStubbing,
-        moveBeforeClick: moveBeforeClick || false,
-        cookies: cookies || null,
-        cookiesFile: cookiesFile || "",
-        accelerate,
+        screenshottingOptions,
+        cookiesFile: cookiesFile,
     };
     await (0, promises_1.writeFile)((0, path_1.join)(tempDir, "replayEventsParams.json"), JSON.stringify(replayEventsParams));
     // 7. Perform replay
     const startTime = luxon_1.DateTime.utc();
     await replayEvents(replayEventsParams);
-    server === null || server === void 0 ? void 0 : server.closeServer();
+    closeServer === null || closeServer === void 0 ? void 0 : closeServer();
     const endTime = luxon_1.DateTime.utc();
     logger.info(`Simulation time: ${endTime.diff(startTime).as("seconds")} seconds`);
     logger.info("Sending simulation results to Meticulous");
@@ -155,26 +146,25 @@ const replayCommandHandler = async ({ apiToken, commitSha: commitSha_, sessionId
     logger.info("=======");
     // 12. Diff against base replay screenshot if one is provided
     const baseReplayId = baseReplayId_ || "";
-    if (screenshot && baseReplayId) {
-        logger.info(`Diffing final state screenshot against replay ${baseReplayId}`);
+    if (screenshottingOptions.enabled && baseReplayId) {
+        logger.info(`Diffing screenshots against replay ${baseReplayId}`);
         await (0, replays_1.getOrFetchReplay)(client, baseReplayId);
         await (0, replays_1.getOrFetchReplayArchive)(client, baseReplayId);
-        const baseScreenshot = await (0, replays_1.readReplayScreenshot)(baseReplayId);
-        const headScreenshot = await (0, replays_1.readLocalReplayScreenshot)(tempDir);
+        const baseReplayScreenshotsDir = (0, replays_1.getScreenshotsDir)((0, replays_1.getReplayDir)(baseReplayId));
+        const headReplayScreenshotsDir = (0, replays_1.getScreenshotsDir)(tempDir);
         await (0, screenshot_diff_command_1.diffScreenshots)({
             client,
             baseReplayId,
             headReplayId: replay.id,
-            baseScreenshot,
-            headScreenshot,
-            threshold: diffThreshold,
-            pixelThreshold: diffPixelThreshold,
+            baseScreenshotsDir: baseReplayScreenshotsDir,
+            headScreenshotsDir: headReplayScreenshotsDir,
+            diffOptions: screenshottingOptions.diffOptions,
             exitOnMismatch: !!exitOnMismatch,
         });
     }
     // 13. Add test case to meticulous.json if --save option is passed
     if (save) {
-        if (!screenshot) {
+        if (!screenshottingOptions.enabled) {
             logger.error("Warning: saving a new test case without screenshot enabled.");
         }
         await (0, config_utils_1.addTestCase)({
@@ -187,20 +177,75 @@ const replayCommandHandler = async ({ apiToken, commitSha: commitSha_, sessionId
     return replay;
 };
 exports.replayCommandHandler = replayCommandHandler;
-const handler = async (options) => {
-    await (0, exports.replayCommandHandler)({ ...options, exitOnMismatch: true });
+const serveOrGetAppUrl = async (client, replayTarget) => {
+    if (replayTarget.type === "snapshotted-assets") {
+        const server = await (0, serve_assets_from_simulation_1.serveAssetsFromSimulation)(client, replayTarget.simulationIdForAssets);
+        return {
+            appUrl: server.url,
+            closeServer: server.closeServer,
+        };
+    }
+    if (replayTarget.type === "url") {
+        return { appUrl: replayTarget.appUrl };
+    }
+    if (replayTarget.type === "original-recorded-url") {
+        return {};
+    }
+    return unknownReplayTargetType(replayTarget);
+};
+const unknownReplayTargetType = (replayTarget) => {
+    throw new Error(`Unknown type of replay target: ${JSON.stringify(replayTarget)}`);
+};
+const rawReplayCommandHandler = ({ apiToken, commitSha, sessionId, appUrl, simulationIdForAssets, headless, devTools, bypassCSP, screenshot, screenshotSelector, baseSimulationId, diffThreshold, diffPixelThreshold, save, padTime, shiftTime, networkStubbing, moveBeforeClick, cookiesFile, accelerate, maxDurationMs, maxEventCount, }) => {
+    const executionOptions = {
+        headless,
+        devTools,
+        bypassCSP,
+        padTime,
+        shiftTime,
+        networkStubbing,
+        accelerate,
+        moveBeforeClick,
+        maxDurationMs: maxDurationMs !== null && maxDurationMs !== void 0 ? maxDurationMs : undefined,
+        maxEventCount: maxEventCount !== null && maxEventCount !== void 0 ? maxEventCount : undefined,
+    };
+    const screenshottingOptions = screenshot
+        ? {
+            enabled: true,
+            screenshotSelector: screenshotSelector !== null && screenshotSelector !== void 0 ? screenshotSelector : undefined,
+            diffOptions: { diffPixelThreshold, diffThreshold },
+        }
+        : { enabled: false };
+    return (0, exports.replayCommandHandler)({
+        replayTarget: getReplayTarget({ appUrl, simulationIdForAssets }),
+        executionOptions,
+        screenshottingOptions,
+        apiToken,
+        commitSha,
+        cookiesFile,
+        sessionId,
+        baseSimulationId,
+        save,
+        exitOnMismatch: true,
+    });
+};
+exports.rawReplayCommandHandler = rawReplayCommandHandler;
+const getReplayTarget = ({ appUrl, simulationIdForAssets, }) => {
+    if (simulationIdForAssets) {
+        return { type: "snapshotted-assets", simulationIdForAssets };
+    }
+    if (appUrl) {
+        return { type: "url", appUrl };
+    }
+    return { type: "original-recorded-url" };
 };
 exports.replay = {
     command: "simulate",
     aliases: ["replay"],
     describe: "Simulate (replay) a recorded session",
     builder: {
-        apiToken: {
-            string: true,
-        },
-        commitSha: {
-            string: true,
-        },
+        apiToken: common_options_1.OPTIONS.apiToken,
+        commitSha: common_options_1.OPTIONS.commitSha,
         sessionId: {
             string: true,
             demandOption: true,
@@ -214,18 +259,6 @@ exports.replay = {
             conflicts: "appUrl",
             description: "If present will run the session against a local server serving up previously snapshotted assets (HTML, JS, CSS etc.) from the specified prior simulation, instead of against a URL. An alternative to specifying an app URL.",
         },
-        headless: {
-            boolean: true,
-            description: "Start browser in headless mode",
-        },
-        devTools: {
-            boolean: true,
-            description: "Open Chrome Dev Tools",
-        },
-        bypassCSP: {
-            boolean: true,
-            description: "Enables bypass CSP in the browser",
-        },
         screenshot: {
             boolean: true,
             description: "Take a screenshot at the end of simulation",
@@ -240,46 +273,31 @@ exports.replay = {
             description: "Base simulation id to diff the final state screenshot against",
             alias: "baseReplayId",
         },
-        diffThreshold: {
-            number: true,
-            description: "Acceptable maximum proportion of changed pixels, between 0 and 1. If this proportion is exceeded then the test will fail.",
-        },
-        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.",
-        },
         save: {
             boolean: true,
             description: "Adds the simulation to the list of test cases in meticulous.json",
         },
-        padTime: {
-            boolean: true,
-            description: "Pad simulation 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 simulation",
-            default: true,
-        },
         moveBeforeClick: {
             boolean: true,
             description: "Simulate mouse movement before clicking",
+            default: false,
         },
         cookiesFile: {
             string: true,
             description: "Path to cookies to inject before simulation",
         },
-        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,
+        ...common_options_1.COMMON_REPLAY_OPTIONS,
+        ...common_options_1.SCREENSHOT_DIFF_OPTIONS,
+        maxDurationMs: {
+            number: true,
+            description: "Maximum duration (in milliseconds) the simulation will run",
+        },
+        maxEventCount: {
+            number: true,
+            description: "Maximum number of events the simulation will run",
         },
     },
-    handler: (0, sentry_utils_1.wrapHandler)(handler),
+    handler: (0, sentry_utils_1.wrapHandler)((0, command_utils_1.handleNulls)(async (options) => {
+        await (0, exports.rawReplayCommandHandler)(options);
+    })),
 };

package/dist/commands/run-all-tests/run-all-tests.command.d.ts

@@ -1,24 +1,17 @@
+import { ReplayExecutionOptions } from "@alwaysmeticulous/common";
 import { CommandModule } from "yargs";
-interface Options {
-    apiToken?: string | null | undefined;
-    commitSha?: string | null | undefined;
-    appUrl?: string | null | undefined;
-    useAssetsSnapshottedInBaseSimulation?: boolean | null | undefined;
-    headless?: boolean | null | undefined;
-    devTools?: boolean | null | undefined;
-    bypassCSP?: boolean | null | undefined;
-    diffThreshold?: number | null | undefined;
-    diffPixelThreshold?: number | null | undefined;
-    padTime: boolean;
-    shiftTime: boolean;
-    networkStubbing: boolean;
-    githubSummary?: boolean | null | undefined;
-    parallelize?: boolean | null | undefined;
-    parallelTasks?: number | null | undefined;
+import { ScreenshotDiffOptions } from "../../command-utils/common-types";
+interface Options extends ScreenshotDiffOptions, ReplayExecutionOptions {
+    apiToken?: string;
+    commitSha?: string;
+    appUrl?: string;
+    useAssetsSnapshottedInBaseSimulation: boolean;
+    githubSummary?: boolean;
+    parallelize?: boolean;
+    parallelTasks?: number | null;
     deflake: boolean;
     useCache: boolean;
-    testsFile?: string | null | undefined;
-    accelerate: boolean;
+    testsFile?: string;
 }
 export declare const runAllTests: CommandModule<unknown, Options>;
 export {};

package/dist/commands/run-all-tests/run-all-tests.command.js

@@ -8,6 +8,7 @@ const common_1 = require("@alwaysmeticulous/common");
 const loglevel_1 = __importDefault(require("loglevel"));
 const client_1 = require("../../api/client");
 const test_run_api_1 = require("../../api/test-run.api");
+const common_options_1 = require("../../command-utils/common-options");
 const config_1 = require("../../config/config");
 const deflake_tests_handler_1 = require("../../deflake-tests/deflake-tests.handler");
 const parallel_tests_handler_1 = require("../../parallel-tests/parallel-tests.handler");
@@ -17,7 +18,25 @@ const github_summary_utils_1 = require("../../utils/github-summary.utils");
 const run_all_tests_utils_1 = require("../../utils/run-all-tests.utils");
 const sentry_utils_1 = require("../../utils/sentry.utils");
 const version_utils_1 = require("../../utils/version.utils");
+const command_utils_1 = require("../../command-utils/command-utils");
 const handler = async ({ apiToken, commitSha: commitSha_, appUrl, useAssetsSnapshottedInBaseSimulation, headless, devTools, bypassCSP, diffThreshold, diffPixelThreshold, padTime, shiftTime, networkStubbing, githubSummary, parallelize, parallelTasks, deflake, useCache, testsFile, accelerate, }) => {
+    const executionOptions = {
+        headless,
+        devTools,
+        bypassCSP,
+        padTime,
+        shiftTime,
+        networkStubbing,
+        accelerate,
+        moveBeforeClick: false,
+        maxDurationMs: undefined,
+        maxEventCount: undefined, // we don't expose this option
+    };
+    const screenshottingOptions = {
+        enabled: true,
+        screenshotSelector: undefined,
+        diffOptions: { diffPixelThreshold, diffThreshold },
+    };
     const logger = loglevel_1.default.getLogger(common_1.METICULOUS_LOGGER_NAME);
     const client = (0, client_1.createClient)({ apiToken });
     const config = await (0, config_1.readConfig)(testsFile || undefined);
@@ -47,51 +66,33 @@ const handler = async ({ apiToken, commitSha: commitSha_, appUrl, useAssetsSnaps
                 config,
                 client,
                 testRun,
+                executionOptions,
+                screenshottingOptions,
                 apiToken,
                 commitSha,
                 appUrl,
                 useAssetsSnapshottedInBaseSimulation,
-                headless,
-                devTools,
-                bypassCSP,
-                diffThreshold,
-                diffPixelThreshold,
-                padTime,
-                shiftTime,
-                networkStubbing,
-                parallelTasks,
+                parallelTasks: parallelTasks !== null && parallelTasks !== void 0 ? parallelTasks : undefined,
                 deflake,
                 cachedTestRunResults,
-                accelerate,
             });
             return results;
         }
         const results = [...cachedTestRunResults];
         const testsToRun = (0, run_all_tests_utils_1.getTestsToRun)({ testCases, cachedTestRunResults });
         for (const testCase of testsToRun) {
-            const { sessionId, baseReplayId, options } = testCase;
             const result = await (0, deflake_tests_handler_1.deflakeReplayCommandHandler)({
-                testCase: testCase,
-                deflake: deflake || false,
+                replayTarget: (0, config_utils_1.getReplayTargetForTestCase)({
+                    useAssetsSnapshottedInBaseSimulation,
+                    appUrl,
+                    testCase,
+                }),
+                executionOptions,
+                screenshottingOptions,
+                testCase,
                 apiToken,
                 commitSha,
-                sessionId,
-                appUrl,
-                headless,
-                devTools,
-                bypassCSP,
-                screenshot: true,
-                baseSimulationId: baseReplayId,
-                diffThreshold,
-                diffPixelThreshold,
-                save: false,
-                exitOnMismatch: false,
-                padTime,
-                shiftTime,
-                networkStubbing,
-                simulationIdForAssets: (0, config_utils_1.getSimulationIdForAssets)(testCase, useAssetsSnapshottedInBaseSimulation),
-                accelerate,
-                ...options,
+                deflake: deflake !== null && deflake !== void 0 ? deflake : false,
             });
             results.push(result);
             await (0, test_run_api_1.putTestRunResults)({
@@ -130,14 +131,11 @@ exports.runAllTests = {
     command: "run-all-tests",
     describe: "Run all replay test cases",
     builder: {
-        apiToken: {
-            string: true,
-        },
-        commitSha: {
-            string: true,
-        },
+        apiToken: common_options_1.OPTIONS.apiToken,
+        commitSha: common_options_1.OPTIONS.commitSha,
         appUrl: {
             string: true,
+            description: "The URL to execute the tests against. If left absent here and in the test cases file, then will use the URL the test was originally recorded against.",
         },
         useAssetsSnapshottedInBaseSimulation: {
             boolean: true,
@@ -145,46 +143,12 @@ exports.runAllTests = {
                 " from the base simulation/replay the test is comparing against. The sessions will then be replayed against those local urls." +
                 " This is an alternative to specifying an appUrl.",
             conflicts: "appUrl",
-        },
-        headless: {
-            boolean: true,
-            description: "Start browser in headless mode",
-        },
-        devTools: {
-            boolean: true,
-            description: "Open Chrome Dev Tools",
-        },
-        bypassCSP: {
-            boolean: true,
-            description: "Enables bypass CSP in the browser",
-        },
-        diffThreshold: {
-            number: true,
-            description: "Acceptable maximum proportion of changed pixels, between 0 and 1. If this proportion is exceeded then the test will fail.",
-        },
-        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: false,
         },
         githubSummary: {
             boolean: true,
             description: "Outputs a summary page for GitHub actions",
         },
-        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,
-        },
         parallelize: {
             boolean: true,
             description: "Run tests in parallel",
@@ -214,11 +178,8 @@ exports.runAllTests = {
             description: "The path to the meticulous.json file containing the list of tests you want to run." +
                 " If not set a search will be performed to find a meticulous.json file in the current directory or the nearest parent directory.",
         },
-        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,
-        },
+        ...common_options_1.COMMON_REPLAY_OPTIONS,
+        ...common_options_1.SCREENSHOT_DIFF_OPTIONS,
     },
-    handler: (0, sentry_utils_1.wrapHandler)(handler),
+    handler: (0, sentry_utils_1.wrapHandler)((0, command_utils_1.handleNulls)(handler)),
 };

package/dist/commands/screenshot-diff/screenshot-diff.command.d.ts

@@ -1,36 +1,43 @@
 import { AxiosInstance } from "axios";
-import { PNG } from "pngjs";
 import { CommandModule } from "yargs";
+import { ScreenshotDiffOptions } from "../../command-utils/common-types";
+import { CompareImageResult } from "../../image/diff.utils";
 export declare class DiffError extends Error {
     readonly extras?: {
         baseReplayId: string;
         headReplayId: string;
         threshold: number;
-        value: number;
+        value?: number;
     } | undefined;
     constructor(message: string, extras?: {
         baseReplayId: string;
         headReplayId: string;
         threshold: number;
-        value: number;
+        value?: number;
     } | undefined);
 }
+declare type ComparisonOutcome = "pass" | "fail";
+export interface ScreenshotDiffResult {
+    baseScreenshotFile: string;
+    headScreenshotFile: string;
+    outcome: ComparisonOutcome;
+    comparisonResult: CompareImageResult;
+}
 export declare const diffScreenshots: (options: {
     client: AxiosInstance;
     baseReplayId: string;
     headReplayId: string;
-    baseScreenshot: PNG;
-    headScreenshot: PNG;
-    threshold: number | null | undefined;
-    pixelThreshold: number | null | undefined;
+    baseScreenshotsDir: string;
+    headScreenshotsDir: string;
+    diffOptions: ScreenshotDiffOptions;
     exitOnMismatch: boolean;
-}) => Promise<void>;
+}) => Promise<ScreenshotDiffResult[]>;
 interface Options {
     apiToken?: string | null | undefined;
     baseSimulationId: string;
     headSimulationId: string;
-    threshold?: number | null | undefined;
-    pixelThreshold?: number | null | undefined;
+    threshold: number;
+    pixelThreshold: number;
 }
 export declare const screenshotDiff: CommandModule<unknown, Options>;
 export {};