@alwaysmeticulous/cli 2.41.0 → 2.42.1

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

@@ -97,7 +97,7 @@ export declare const SCREENSHOT_DIFF_OPTIONS: {
     };
 };
 /**
- * Options that are passed onto replayEvents, that are shared by the replay, run-all-tests, and create-test commands
+ * Options that are passed onto launchBrowserAndReplay, that are shared by the replay, run-all-tests, and create-test commands
  */
 export declare const COMMON_REPLAY_OPTIONS: {
     headless: {

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

@@ -98,7 +98,7 @@ exports.SCREENSHOT_DIFF_OPTIONS = {
     storyboard: exports.OPTIONS.storyboard,
 };
 /**
- * Options that are passed onto replayEvents, that are shared by the replay, run-all-tests, and create-test commands
+ * Options that are passed onto launchBrowserAndReplay, that are shared by the replay, run-all-tests, and create-test commands
  */
 exports.COMMON_REPLAY_OPTIONS = {
     headless: exports.OPTIONS.headless,

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

@@ -1,13 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.replayCommand = exports.getReplayTarget = exports.rawReplayCommandHandler = void 0;
+const common_1 = require("@alwaysmeticulous/common");
 const replay_orchestrator_1 = require("@alwaysmeticulous/replay-orchestrator");
 const command_builder_1 = require("../../command-utils/command-builder");
 const common_options_1 = require("../../command-utils/common-options");
+const out_of_date_client_error_1 = require("../../utils/out-of-date-client-error");
+const replay_debugger_ui_1 = require("./utils/replay-debugger.ui");
 const rawReplayCommandHandler = async ({ apiToken, commitSha, sessionId, appUrl, simulationIdForAssets, headless, devTools, bypassCSP, screenshot, baseReplayId, diffThreshold, diffPixelThreshold, shiftTime, networkStubbing, moveBeforeClick, cookiesFile, disableRemoteFonts, noSandbox, skipPauses, maxDurationMs, maxEventCount, storyboard, essentialFeaturesOnly, debugger: enableStepThroughDebugger, }) => {
     if (!screenshot && storyboard) {
         throw new Error("Cannot take storyboard screenshots without taking end state screenshots. Please set '--screenshot' to true, or '--storyboard' to false.");
     }
+    if (headless && enableStepThroughDebugger) {
+        throw new Error("Cannot run with both --debugger flag and --headless flag at the same time.");
+    }
     const executionOptions = {
         headless,
         devTools,
@@ -41,23 +47,51 @@ const rawReplayCommandHandler = async ({ apiToken, commitSha, sessionId, appUrl,
                 },
         }
         : { enabled: false };
-    const { replay } = await (0, replay_orchestrator_1.replayAndStoreResults)({
-        replayTarget: (0, exports.getReplayTarget)({
-            appUrl: appUrl !== null && appUrl !== void 0 ? appUrl : null,
-            simulationIdForAssets: simulationIdForAssets !== null && simulationIdForAssets !== void 0 ? simulationIdForAssets : null,
-        }),
-        executionOptions,
-        screenshottingOptions,
-        apiToken,
-        commitSha,
-        cookiesFile,
-        sessionId,
-        generatedBy: generatedByOption,
-        testRunId: null,
-        debugger: enableStepThroughDebugger,
-        suppressScreenshotDiffLogging: false,
-    });
-    return replay;
+    const getOnBeforeUserEventCallback = (0, common_1.defer)();
+    const getOnClosePageCallback = (0, common_1.defer)();
+    try {
+        const replayExecution = await (0, replay_orchestrator_1.replayAndStoreResults)({
+            replayTarget: (0, exports.getReplayTarget)({
+                appUrl: appUrl !== null && appUrl !== void 0 ? appUrl : null,
+                simulationIdForAssets: simulationIdForAssets !== null && simulationIdForAssets !== void 0 ? simulationIdForAssets : null,
+            }),
+            executionOptions,
+            screenshottingOptions,
+            apiToken,
+            commitSha,
+            cookiesFile,
+            sessionId,
+            generatedBy: generatedByOption,
+            testRunId: null,
+            suppressScreenshotDiffLogging: false,
+            ...(enableStepThroughDebugger
+                ? {
+                    onBeforeUserEvent: async (options) => (await getOnBeforeUserEventCallback.promise)(options),
+                    onClosePage: async () => (await getOnClosePageCallback.promise)(),
+                }
+                : {}),
+            maxSemanticVersionSupported: 1,
+        });
+        if (enableStepThroughDebugger) {
+            const stepThroughDebuggerUI = await (0, replay_debugger_ui_1.openStepThroughDebuggerUI)({
+                onLogEventTarget: replayExecution.logEventTarget,
+                onCloseReplayedPage: replayExecution.closePage,
+                replayableEvents: replayExecution.eventsBeingReplayed,
+            });
+            getOnBeforeUserEventCallback.resolve(stepThroughDebuggerUI.onBeforeUserEvent);
+            getOnClosePageCallback.resolve(stepThroughDebuggerUI.close);
+        }
+        const { replay } = await replayExecution.finalResult;
+        return replay;
+    }
+    catch (error) {
+        if ((0, out_of_date_client_error_1.isOutOfDateClientError)(error)) {
+            throw new out_of_date_client_error_1.OutOfDateCLIError();
+        }
+        else {
+            throw error;
+        }
+    }
 };
 exports.rawReplayCommandHandler = rawReplayCommandHandler;
 const getReplayTarget = ({ appUrl, simulationIdForAssets, }) => {

package/dist/commands/replay/utils/replay-debugger.ui.d.ts

@@ -0,0 +1,23 @@
+import { ReplayableEvent } from "@alwaysmeticulous/api";
+import { BeforeUserEventOptions, BeforeUserEventResult } from "@alwaysmeticulous/sdk-bundles-api";
+import { Page } from "puppeteer";
+export interface ReplayDebuggerState {
+    events: ReplayableEvent[];
+    index: number;
+    loading: boolean;
+}
+export interface ReplayDebuggerUIOptions {
+    onCloseReplayedPage: () => void;
+    onLogEventTarget: (event: ReplayableEvent) => Promise<void>;
+    replayableEvents: ReplayableEvent[];
+}
+export interface ReplayDebuggerUI {
+    page: Page;
+}
+type OnBeforeUserEventCallback = (options: BeforeUserEventOptions) => Promise<BeforeUserEventResult>;
+export interface StepThroughDebuggerUI {
+    onBeforeUserEvent: OnBeforeUserEventCallback;
+    close: () => Promise<void>;
+}
+export declare const openStepThroughDebuggerUI: ({ onCloseReplayedPage, onLogEventTarget, replayableEvents, }: ReplayDebuggerUIOptions) => Promise<StepThroughDebuggerUI>;
+export {};

package/dist/commands/replay/utils/replay-debugger.ui.js

@@ -0,0 +1,113 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.openStepThroughDebuggerUI = void 0;
+const common_1 = require("@alwaysmeticulous/common");
+const replay_debugger_ui_1 = require("@alwaysmeticulous/replay-debugger-ui");
+const loglevel_1 = __importDefault(require("loglevel"));
+const puppeteer_1 = require("puppeteer");
+// openStepThroughDebuggerUI returns a OnBeforeUserEventCallback, which the replay code
+// calls before each next event, and blocks on the returned promise. We use this to pause
+// the execution until the user OKs it to continue to a certain event.
+const openStepThroughDebuggerUI = async ({ onCloseReplayedPage, onLogEventTarget, replayableEvents, }) => {
+    const logger = loglevel_1.default.getLogger(common_1.METICULOUS_LOGGER_NAME);
+    // Start the UI server
+    const uiServer = await (0, replay_debugger_ui_1.startUIServer)();
+    // Launch the browser
+    const browser = await (0, puppeteer_1.launch)({
+        args: [`--window-size=600,1000`],
+        headless: false,
+    });
+    // Create page for the debugger UI
+    const debuggerPage = (await browser.pages())[0];
+    debuggerPage.setViewport({
+        width: 0,
+        height: 0,
+    });
+    /**
+     * The index the page is in the process of advancing to. Equal to the current index
+     * if the page has already replayed all the so-far-requested user events.
+     */
+    let targetIndex = 0;
+    let state = {
+        events: replayableEvents,
+        index: 0,
+        loading: false,
+    };
+    const setState = async (newState) => {
+        state = { ...state, ...newState };
+        await debuggerPage.evaluate((state) => {
+            window.__meticulous__replayDebuggerSetState(state);
+        }, state);
+    };
+    const onReady = async () => {
+        await setState(state);
+    };
+    let advanceToEvent = null;
+    const onBeforeUserEvent = async ({ userEventIndex, }) => {
+        await setState({
+            loading: userEventIndex < targetIndex,
+            index: Math.max(0, Math.min(state.events.length - 1, userEventIndex)),
+        });
+        if (state.index < targetIndex) {
+            advanceToEvent = null;
+            return { nextEventIndexToPauseBefore: targetIndex }; // keep going
+        }
+        return new Promise((resolve) => {
+            advanceToEvent = resolve;
+        });
+    };
+    const onPlayNextEvent = async () => {
+        targetIndex = state.index + 1;
+        await setState({ loading: true });
+        advanceToEvent === null || advanceToEvent === void 0 ? void 0 : advanceToEvent({ nextEventIndexToPauseBefore: targetIndex });
+    };
+    const onAdvanceToIndex = async (newTargetIndex) => {
+        if (newTargetIndex <= state.index) {
+            return; // Do nothing
+        }
+        targetIndex = newTargetIndex;
+        await setState({ loading: true });
+        advanceToEvent === null || advanceToEvent === void 0 ? void 0 : advanceToEvent({ nextEventIndexToPauseBefore: targetIndex });
+    };
+    // This function is called by the UI itself
+    await debuggerPage.exposeFunction("__meticulous__replayDebuggerDispatchEvent", (eventType, data) => {
+        if (eventType === "ready") {
+            return onReady();
+        }
+        if (eventType === "check-next-target") {
+            if (state.index >= replayableEvents.length) {
+                logger.info("End of replay!");
+                return;
+            }
+            const nextEvent = state.events[state.index];
+            return onLogEventTarget(nextEvent);
+        }
+        if (eventType === "play-next-event") {
+            return onPlayNextEvent();
+        }
+        if (eventType === "set-index") {
+            return onAdvanceToIndex(data.index || 0);
+        }
+        logger.info(`[debugger-ui] Warning: received unknown event "${eventType}"`);
+    });
+    logger.info(`[debugger-ui] Navigating to ${uiServer.url}...`);
+    const res = await debuggerPage.goto(uiServer.url, {
+        waitUntil: "domcontentloaded",
+    });
+    const status = res && res.status();
+    if (status !== 200) {
+        throw new Error(`Expected a 200 status when going to the initial URL of the site. Got a ${status} instead.`);
+    }
+    logger.info(`[debugger-ui] Navigated to ${uiServer.url}`);
+    debuggerPage.on("close", () => {
+        uiServer.close();
+    });
+    debuggerPage.on("close", () => {
+        onCloseReplayedPage();
+    });
+    return { onBeforeUserEvent, close: () => debuggerPage.close() };
+};
+exports.openStepThroughDebuggerUI = openStepThroughDebuggerUI;

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

@@ -7,6 +7,7 @@ const replay_orchestrator_1 = require("@alwaysmeticulous/replay-orchestrator");
 const test_run_api_1 = require("../../api/test-run.api");
 const command_builder_1 = require("../../command-utils/command-builder");
 const common_options_1 = require("../../command-utils/common-options");
+const out_of_date_client_error_1 = require("../../utils/out-of-date-client-error");
 const handler = async ({ apiToken, commitSha: commitSha_, baseCommitSha, appUrl, headless, devTools, bypassCSP, diffThreshold, diffPixelThreshold, shiftTime, networkStubbing, githubSummary, parallelize, parallelTasks: parrelelTasks_, maxRetriesOnFailure, rerunTestsNTimes, useCache, testsFile, disableRemoteFonts, noSandbox, skipPauses, moveBeforeClick, maxDurationMs, maxEventCount, storyboard, essentialFeaturesOnly, baseTestRunId, }) => {
     const executionOptions = {
         headless,
@@ -36,23 +37,34 @@ const handler = async ({ apiToken, commitSha: commitSha_, baseCommitSha, appUrl,
     const cachedTestRunResults = useCache
         ? await (0, test_run_api_1.getCachedTestRunResults)({ client, commitSha })
         : [];
-    const { testRun } = await (0, replay_orchestrator_1.executeTestRun)({
-        testsFile: testsFile !== null && testsFile !== void 0 ? testsFile : null,
-        executionOptions,
-        screenshottingOptions,
-        apiToken: apiToken !== null && apiToken !== void 0 ? apiToken : null,
-        commitSha,
-        baseCommitSha: baseCommitSha !== null && baseCommitSha !== void 0 ? baseCommitSha : null,
-        baseTestRunId: baseTestRunId !== null && baseTestRunId !== void 0 ? baseTestRunId : null,
-        appUrl: appUrl !== null && appUrl !== void 0 ? appUrl : null,
-        parallelTasks: parrelelTasks !== null && parrelelTasks !== void 0 ? parrelelTasks : null,
-        maxRetriesOnFailure,
-        rerunTestsNTimes,
-        cachedTestRunResults,
-        githubSummary,
-    });
-    if (testRun.status === "Failure") {
-        process.exit(1);
+    try {
+        const { testRun } = await (0, replay_orchestrator_1.executeTestRun)({
+            testsFile: testsFile !== null && testsFile !== void 0 ? testsFile : null,
+            executionOptions,
+            screenshottingOptions,
+            apiToken: apiToken !== null && apiToken !== void 0 ? apiToken : null,
+            commitSha,
+            baseCommitSha: baseCommitSha !== null && baseCommitSha !== void 0 ? baseCommitSha : null,
+            baseTestRunId: baseTestRunId !== null && baseTestRunId !== void 0 ? baseTestRunId : null,
+            appUrl: appUrl !== null && appUrl !== void 0 ? appUrl : null,
+            parallelTasks: parrelelTasks !== null && parrelelTasks !== void 0 ? parrelelTasks : null,
+            maxRetriesOnFailure,
+            rerunTestsNTimes,
+            cachedTestRunResults,
+            githubSummary,
+            maxSemanticVersionSupported: 1,
+        });
+        if (testRun.status === "Failure") {
+            process.exit(1);
+        }
+    }
+    catch (error) {
+        if ((0, out_of_date_client_error_1.isOutOfDateClientError)(error)) {
+            throw new out_of_date_client_error_1.OutOfDateCLIError();
+        }
+        else {
+            throw error;
+        }
     }
 };
 exports.runAllTestsCommand = (0, command_builder_1.buildCommand)("run-all-tests")

package/dist/utils/out-of-date-client-error.d.ts

@@ -0,0 +1,5 @@
+import { OutOfDateClientError } from "@alwaysmeticulous/sdk-bundles-api";
+export declare const isOutOfDateClientError: (error: unknown) => error is OutOfDateClientError;
+export declare class OutOfDateCLIError extends Error {
+    constructor();
+}

package/dist/utils/out-of-date-client-error.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OutOfDateCLIError = exports.isOutOfDateClientError = void 0;
+const isOutOfDateClientError = (error) => {
+    return error.name === "OutOfDateClient";
+};
+exports.isOutOfDateClientError = isOutOfDateClientError;
+class OutOfDateCLIError extends Error {
+    constructor() {
+        super("The version of @alwaysmeticulous/cli you are using is out of date. Please update to the latest version, using npm or yarn, and try again.");
+        this.name = "OutOfDateCLI";
+    }
+}
+exports.OutOfDateCLIError = OutOfDateCLIError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/cli",
-  "version": "2.41.0",
+  "version": "2.42.1",
   "description": "The Meticulous CLI",
   "license": "ISC",
   "main": "dist/index.js",
@@ -27,17 +27,19 @@
     "depcheck": "depcheck --ignore-patterns=dist"
   },
   "dependencies": {
-    "@alwaysmeticulous/api": "^2.41.0",
-    "@alwaysmeticulous/client": "^2.41.0",
-    "@alwaysmeticulous/common": "^2.41.0",
-    "@alwaysmeticulous/downloading-helpers": "^2.41.0",
-    "@alwaysmeticulous/record": "^2.41.0",
-    "@alwaysmeticulous/replay-orchestrator": "^2.41.0",
-    "@alwaysmeticulous/sdk-bundles-api": "^2.41.0",
+    "@alwaysmeticulous/api": "^2.42.0",
+    "@alwaysmeticulous/client": "^2.42.0",
+    "@alwaysmeticulous/common": "^2.42.0",
+    "@alwaysmeticulous/downloading-helpers": "^2.42.0",
+    "@alwaysmeticulous/record": "^2.42.0",
+    "@alwaysmeticulous/replay-debugger-ui": "^2.42.0",
+    "@alwaysmeticulous/replay-orchestrator": "^2.42.1",
+    "@alwaysmeticulous/sdk-bundles-api": "^2.42.1",
     "@alwaysmeticulous/sentry": "^2.40.0",
     "@sentry/node": "^7.36.0",
     "axios": "^1.2.6",
     "loglevel": "^1.8.0",
+    "puppeteer": "^19.7.5",
     "yargs": "^17.5.1"
   },
   "devDependencies": {
@@ -77,5 +79,5 @@
     "coverageDirectory": "../coverage",
     "testEnvironment": "node"
   },
-  "gitHead": "778895a7cd6a010538e338f9b2da225e71c53f48"
+  "gitHead": "6c08f6e79f34f7efdc2ebd0e8e4e09baffeb8f04"
 }