@alwaysmeticulous/cli 2.41.0 → 2.42.0

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,18 @@
 "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 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,7 +46,9 @@ const rawReplayCommandHandler = async ({ apiToken, commitSha, sessionId, appUrl,
                 },
         }
         : { enabled: false };
-    const { replay } = await (0, replay_orchestrator_1.replayAndStoreResults)({
+    const getOnBeforeUserEventCallback = (0, common_1.defer)();
+    const getOnClosePageCallback = (0, common_1.defer)();
+    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,
@@ -54,9 +61,24 @@ const rawReplayCommandHandler = async ({ apiToken, commitSha, sessionId, appUrl,
         sessionId,
         generatedBy: generatedByOption,
         testRunId: null,
-        debugger: enableStepThroughDebugger,
         suppressScreenshotDiffLogging: false,
+        ...(enableStepThroughDebugger
+            ? {
+                onBeforeUserEvent: async (options) => (await getOnBeforeUserEventCallback.promise)(options),
+                onClosePage: async () => (await getOnClosePageCallback.promise)(),
+            }
+            : {}),
     });
+    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;
 };
 exports.rawReplayCommandHandler = rawReplayCommandHandler;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alwaysmeticulous/cli",
-  "version": "2.41.0",
+  "version": "2.42.0",
   "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.0",
+    "@alwaysmeticulous/sdk-bundles-api": "^2.42.0",
     "@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": "65e2410a784642674ea6c8203d5b9f8a303c33ea"
 }