@samsara-dev/appwright 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # appwright
 
+## 0.3.1
+
+### Patch Changes
+
+- eb38761: Add `device.backgroundApp()` to delegate to Appium's `mobile: backgroundApp` command.
+
+## 0.3.0
+
+### Minor Changes
+
+- 9415229: feat: add Visual Trace Service for automatic screenshot capture during test execution
+
+  - Implements automatic screenshot capture with smart defaults (only captures for failed tests)
+  - Adds screenshot deduplication using SHA-256 hashing
+  - Supports configurable screenshot limits (default: 50)
+  - Integrates with Playwright's trace configuration modes
+  - Works with both test-scoped device and worker-scoped persistentDevice fixtures
+  - Provides proper test isolation and retry support
+  - Includes comprehensive unit test coverage
+
 ## 0.2.1
 
 ### Patch Changes

package/dist/device/index.d.ts

@@ -1,13 +1,23 @@
 import type { Client as WebDriverClient } from "webdriver";
-import { AppwrightLocator, ExtractType, Platform, TimeoutOptions } from "../types";
+import { AppwrightLocator, ExtractType, Platform, TimeoutOptions, VisualTraceConfig } from "../types";
 import { z } from "zod";
 import { LLMModel } from "@empiricalrun/llm";
+import { TestInfo } from "@playwright/test";
 export declare class Device {
     private webDriverClient;
     private bundleId;
     private timeoutOpts;
     private provider;
+    private visualTraceService?;
     constructor(webDriverClient: WebDriverClient, bundleId: string | undefined, timeoutOpts: TimeoutOptions, provider: string);
+    /**
+     * Initialize Visual Trace Service for screenshot capture during test execution
+     */
+    initializeVisualTrace(testInfo: TestInfo, retryIndex: number, config?: VisualTraceConfig): void;
+    /**
+     * Take a screenshot - exposed for Visual Trace Service
+     */
+    takeScreenshot(): Promise<Buffer>;
     locator({ selector, findStrategy, textToMatch, }: {
         selector: string;
         findStrategy: string;
@@ -119,6 +129,25 @@ export declare class Device {
     getPlatform(): Platform;
     terminateApp(bundleId?: string): Promise<void>;
     activateApp(bundleId?: string): Promise<void>;
+    /**
+     * Sends the currently running app to the background.
+     *
+     * @param seconds - Number of seconds to keep app in background.
+     *                  Use -1 to background indefinitely (until manually reactivated).
+     *                  If positive number, app returns to foreground after specified seconds.
+     *
+     * @example
+     * ```js
+     * // Background for 10 seconds then auto-return
+     * await device.backgroundApp(10);
+     *
+     * // Background indefinitely (for battery tests)
+     * await device.backgroundApp(-1);
+     * await device.pause(30 * 60 * 1000); // Wait 30 minutes
+     * await device.activateApp(); // Manually bring back
+     * ```
+     */
+    backgroundApp(seconds?: number): Promise<void>;
     /**
      * Retrieves text content from the clipboard of the mobile device. This is useful
      * after a "copy to clipboard" action has been performed. This returns base64 encoded string.

package/dist/device/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/device/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/device/index.ts"],"names":[],"mappings":"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"}

package/dist/device/index.js

@@ -42,11 +42,13 @@ const utils_1 = require("../utils");
 const utils_2 = require("../providers/browserstack/utils");
 const utils_3 = require("../providers/lambdatest/utils");
 const logger_1 = require("../logger");
+const visualTrace_1 = require("../visualTrace");
 let Device = (() => {
     let _instanceExtraInitializers = [];
     let _tap_decorators;
     let _terminateApp_decorators;
     let _activateApp_decorators;
+    let _backgroundApp_decorators;
     let _getClipboardText_decorators;
     let _setMockCameraView_decorators;
     let _pause_decorators;
@@ -60,6 +62,7 @@ let Device = (() => {
             _tap_decorators = [utils_1.boxedStep];
             _terminateApp_decorators = [utils_1.boxedStep];
             _activateApp_decorators = [utils_1.boxedStep];
+            _backgroundApp_decorators = [utils_1.boxedStep];
             _getClipboardText_decorators = [utils_1.boxedStep];
             _setMockCameraView_decorators = [utils_1.boxedStep];
             _pause_decorators = [utils_1.boxedStep];
@@ -70,6 +73,7 @@ let Device = (() => {
             __esDecorate(this, null, _tap_decorators, { kind: "method", name: "tap", static: false, private: false, access: { has: obj => "tap" in obj, get: obj => obj.tap }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _terminateApp_decorators, { kind: "method", name: "terminateApp", static: false, private: false, access: { has: obj => "terminateApp" in obj, get: obj => obj.terminateApp }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _activateApp_decorators, { kind: "method", name: "activateApp", static: false, private: false, access: { has: obj => "activateApp" in obj, get: obj => obj.activateApp }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _backgroundApp_decorators, { kind: "method", name: "backgroundApp", static: false, private: false, access: { has: obj => "backgroundApp" in obj, get: obj => obj.backgroundApp }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _getClipboardText_decorators, { kind: "method", name: "getClipboardText", static: false, private: false, access: { has: obj => "getClipboardText" in obj, get: obj => obj.getClipboardText }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _setMockCameraView_decorators, { kind: "method", name: "setMockCameraView", static: false, private: false, access: { has: obj => "setMockCameraView" in obj, get: obj => obj.setMockCameraView }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _pause_decorators, { kind: "method", name: "pause", static: false, private: false, access: { has: obj => "pause" in obj, get: obj => obj.pause }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -83,14 +87,28 @@ let Device = (() => {
         bundleId;
         timeoutOpts;
         provider;
+        visualTraceService;
         constructor(webDriverClient, bundleId, timeoutOpts, provider) {
             this.webDriverClient = webDriverClient;
             this.bundleId = bundleId;
             this.timeoutOpts = timeoutOpts;
             this.provider = provider;
         }
+        /**
+         * Initialize Visual Trace Service for screenshot capture during test execution
+         */
+        initializeVisualTrace(testInfo, retryIndex, config) {
+            this.visualTraceService = (0, visualTrace_1.initializeVisualTrace)(testInfo, retryIndex, config);
+        }
+        /**
+         * Take a screenshot - exposed for Visual Trace Service
+         */
+        async takeScreenshot() {
+            const base64Screenshot = await this.webDriverClient.takeScreenshot();
+            return Buffer.from(base64Screenshot, "base64");
+        }
         locator({ selector, findStrategy, textToMatch, }) {
-            return new locator_1.Locator(this.webDriverClient, this.timeoutOpts, selector, findStrategy, textToMatch);
+            return new locator_1.Locator(this.webDriverClient, this.timeoutOpts, selector, findStrategy, textToMatch, this);
         }
         vision() {
             return new vision_1.VisionProvider(this, this.webDriverClient);
@@ -121,6 +139,11 @@ let Device = (() => {
             catch (e) {
                 logger_1.logger.error(`close:`, e);
             }
+            // Clean up visual trace service
+            if (this.visualTraceService) {
+                (0, visualTrace_1.clearVisualTraceService)();
+                this.visualTraceService = undefined;
+            }
         }
         /**
          * Tap on the screen at the given coordinates, specified as x and y. The top left corner
@@ -290,6 +313,29 @@ let Device = (() => {
                 },
             ]);
         }
+        /**
+         * Sends the currently running app to the background.
+         *
+         * @param seconds - Number of seconds to keep app in background.
+         *                  Use -1 to background indefinitely (until manually reactivated).
+         *                  If positive number, app returns to foreground after specified seconds.
+         *
+         * @example
+         * ```js
+         * // Background for 10 seconds then auto-return
+         * await device.backgroundApp(10);
+         *
+         * // Background indefinitely (for battery tests)
+         * await device.backgroundApp(-1);
+         * await device.pause(30 * 60 * 1000); // Wait 30 minutes
+         * await device.activateApp(); // Manually bring back
+         * ```
+         */
+        async backgroundApp(seconds = -1) {
+            await this.webDriverClient.executeScript("mobile: backgroundApp", [
+                seconds,
+            ]);
+        }
         /**
          * Retrieves text content from the clipboard of the mobile device. This is useful
          * after a "copy to clipboard" action has been performed. This returns base64 encoded string.

package/dist/fixture/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixture/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,aAAa,EAEd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAKnC,KAAK,iBAAiB,GAAG;IACvB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAE/B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,IAAI,uRA4Df,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM;2BACY,gBAAgB,YAAY,aAAa;;;;;;;EAUtE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/fixture/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,aAAa,EAGd,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AAKnC,KAAK,iBAAiB,GAAG;IACvB;;;OAGG;IACH,cAAc,EAAE,cAAc,CAAC;IAE/B;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACzB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,eAAO,MAAM,IAAI,uRAyEf,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,MAAM;2BACY,gBAAgB,YAAY,aAAa;;;;;;;EAUtE,CAAC"}

package/dist/fixture/index.js

@@ -21,6 +21,9 @@ exports.test = test_1.test.extend({
             type: "sessionId",
             description: deviceProvider.sessionId,
         });
+        // Initialize Visual Trace Service for screenshot capture
+        const visualTraceConfig = testInfo.project.use.visualTrace;
+        device.initializeVisualTrace(testInfo, testInfo.retry, visualTraceConfig);
         await deviceProvider.syncTestDetails?.({ name: testInfo.title });
         await use(device);
         await device.close();
@@ -46,6 +49,8 @@ exports.test = test_1.test.extend({
             }
             const providerName = project.use.device
                 ?.provider;
+            // Note: For persistentDevice, Visual Trace is initialized lazily in boxedStep
+            // when test.info() is available, ensuring it works for worker-scoped fixtures.
             const afterSession = new Date();
             const workerInfoStore = new workerInfo_1.WorkerInfoStore();
             await workerInfoStore.saveWorkerStartTime(workerIndex, sessionId, providerName, beforeSession, afterSession);

package/dist/locator/index.d.ts

@@ -6,7 +6,10 @@ export declare class Locator {
     private selector;
     private findStrategy;
     private textToMatch?;
-    constructor(webDriverClient: WebDriverClient, timeoutOpts: TimeoutOptions, selector: string, findStrategy: string, textToMatch?: (string | RegExp) | undefined);
+    private device?;
+    constructor(webDriverClient: WebDriverClient, timeoutOpts: TimeoutOptions, selector: string, findStrategy: string, textToMatch?: (string | RegExp) | undefined, device?: {
+        takeScreenshot: () => Promise<Buffer>;
+    });
     fill(value: string, options?: ActionOptions): Promise<void>;
     sendKeyStrokes(value: string, options?: ActionOptions): Promise<void>;
     isVisible(options?: ActionOptions): Promise<boolean>;

package/dist/locator/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/locator/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,eAAe,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,aAAa,EAEd,MAAM,UAAU,CAAC;AAIlB,qBAAa,OAAO;IAEhB,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,WAAW;IAEnB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IAEpB,OAAO,CAAC,WAAW,CAAC;gBANZ,eAAe,EAAE,eAAe,EAChC,WAAW,EAAE,cAAc,EAE3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EAEpB,WAAW,CAAC,GAAE,MAAM,GAAG,MAAM,aAAA;IAIjC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB3D,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCrE,SAAS,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAYpD,OAAO,CACX,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC;YAgCF,SAAS;IAiCjB,GAAG,CAAC,OAAO,CAAC,EAAE,aAAa;IAiB3B,OAAO,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBjD,MAAM,CAAC,SAAS,EAAE,eAAe;IAuBvC;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAkDrD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/locator/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,IAAI,eAAe,EAAE,MAAM,WAAW,CAAC;AAEtD,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,aAAa,EAEd,MAAM,UAAU,CAAC;AAIlB,qBAAa,OAAO;IAKhB,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,WAAW;IAEnB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,YAAY;IAEpB,OAAO,CAAC,WAAW,CAAC;IATtB,OAAO,CAAC,MAAM,CAAC,CAA4C;gBAGjD,eAAe,EAAE,eAAe,EAChC,WAAW,EAAE,cAAc,EAE3B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EAEpB,WAAW,CAAC,GAAE,MAAM,GAAG,MAAM,aAAA,EACrC,MAAM,CAAC,EAAE;QAAE,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE;IAM9C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB3D,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAqCrE,SAAS,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC;IAYpD,OAAO,CACX,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,IAAI,CAAC;YAgCF,SAAS;IAiCjB,GAAG,CAAC,OAAO,CAAC,EAAE,aAAa;IAiB3B,OAAO,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAqBjD,MAAM,CAAC,SAAS,EAAE,eAAe;IAuBvC;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAkDrD"}

package/dist/locator/index.js

@@ -69,16 +69,19 @@ let Locator = (() => {
         selector;
         findStrategy;
         textToMatch;
+        // Store reference to the device for Visual Trace Service
+        device;
         constructor(webDriverClient, timeoutOpts, 
         // Used for find elements request that is sent to Appium server
         selector, findStrategy, 
         // Used to filter elements received from Appium server
-        textToMatch) {
+        textToMatch, device) {
             this.webDriverClient = webDriverClient;
             this.timeoutOpts = timeoutOpts;
             this.selector = selector;
             this.findStrategy = findStrategy;
             this.textToMatch = textToMatch;
+            this.device = device;
         }
         async fill(value, options) {
             const isElementDisplayed = await this.isVisible(options);

package/dist/tests/device.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=device.spec.d.ts.map

package/dist/tests/device.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.spec.d.ts","sourceRoot":"","sources":["../../src/tests/device.spec.ts"],"names":[],"mappings":""}

package/dist/tests/device.spec.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const test_1 = __importDefault(require("@playwright/test"));
+const device_1 = require("../device");
+// Override Playwright's test.step/info to work in Vitest environment
+// so boxedStep decorator can execute without throwing.
+test_1.default.step = vitest_1.vi.fn(async (_name, body) => await body());
+test_1.default.info = () => undefined;
+const createDevice = (executeScript = vitest_1.vi.fn()) => {
+    //@ts-ignore - providing partial WebDriver client for testing
+    const webDriverClient = {
+        executeScript,
+    };
+    const device = new device_1.Device(webDriverClient, "com.example.app", { expectTimeout: 1_000 }, "emulator");
+    return { device, executeScript };
+};
+(0, vitest_1.describe)("Device", () => {
+    (0, vitest_1.describe)("backgroundApp", () => {
+        (0, vitest_1.test)("backgrounds indefinitely by default", async () => {
+            const { device, executeScript } = createDevice();
+            await device.backgroundApp();
+            (0, vitest_1.expect)(executeScript).toHaveBeenCalledWith("mobile: backgroundApp", [-1]);
+        });
+        (0, vitest_1.test)("backgrounds for given duration", async () => {
+            const { device, executeScript } = createDevice();
+            await device.backgroundApp(30);
+            (0, vitest_1.expect)(executeScript).toHaveBeenCalledWith("mobile: backgroundApp", [30]);
+        });
+    });
+});

package/dist/tests/visual-trace.service.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=visual-trace.service.spec.d.ts.map

package/dist/tests/visual-trace.service.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual-trace.service.spec.d.ts","sourceRoot":"","sources":["../../src/tests/visual-trace.service.spec.ts"],"names":[],"mappings":""}

package/dist/tests/visual-trace.service.spec.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vitest_1 = require("vitest");
+const service_1 = require("../visualTrace/service");
+// Mock TestInfo object
+function createMockTestInfo(options) {
+    return {
+        testId: options.testId || "test-1",
+        retry: options.retry || 0,
+        status: options.status,
+        errors: options.errors || [],
+        project: {
+            use: {
+                trace: options.trace,
+                screenshots: options.screenshots,
+            },
+        },
+        attach: vitest_1.vi.fn(),
+    };
+}
+// Mock screenshot function
+const mockTakeScreenshot = vitest_1.vi.fn(() => Promise.resolve(Buffer.from("mock-screenshot-data")));
+(0, vitest_1.describe)("VisualTraceService", () => {
+    (0, vitest_1.beforeEach)(() => {
+        (0, service_1.clearVisualTraceService)();
+        mockTakeScreenshot.mockClear();
+    });
+    (0, vitest_1.describe)("Configuration", () => {
+        (0, vitest_1.test)("should use default configuration when no config provided", () => {
+            const testInfo = createMockTestInfo({ testId: "test-1" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service["config"]).toEqual({
+                enableScreenshots: "retain-on-failure",
+                maxScreenshots: 50,
+                dedupe: true,
+            });
+        });
+        (0, vitest_1.test)("should merge provided config with defaults", () => {
+            const testInfo = createMockTestInfo({ testId: "test-1" });
+            const config = {
+                enableScreenshots: "on",
+                maxScreenshots: 10,
+            };
+            const service = new service_1.VisualTraceService(testInfo, 0, config);
+            (0, vitest_1.expect)(service["config"]).toEqual({
+                enableScreenshots: "on",
+                maxScreenshots: 10,
+                dedupe: true, // Default value
+            });
+        });
+    });
+    (0, vitest_1.describe)("shouldCaptureScreenshot", () => {
+        (0, vitest_1.test)('should return true when trace mode is "on"', () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(true);
+        });
+        (0, vitest_1.test)('should return false when trace mode is "off"', () => {
+            const testInfo = createMockTestInfo({ trace: "off" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(false);
+        });
+        (0, vitest_1.test)("should return false when screenshots are explicitly disabled", () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0, {
+                enableScreenshots: false,
+            });
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(false);
+        });
+        (0, vitest_1.test)('should return true for failed test with "retain-on-failure"', () => {
+            const testInfo = createMockTestInfo({
+                trace: "retain-on-failure",
+                status: "failed",
+            });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(true);
+        });
+        (0, vitest_1.test)('should return false for passed test with "retain-on-failure"', () => {
+            const testInfo = createMockTestInfo({
+                trace: "retain-on-failure",
+                status: "passed",
+            });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(false);
+        });
+        (0, vitest_1.test)('should return true when step fails with "retain-on-failure"', () => {
+            const testInfo = createMockTestInfo({
+                trace: "retain-on-failure",
+                status: undefined, // Status not set during execution
+            });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot(true)).toBe(true); // stepFailed = true
+        });
+        (0, vitest_1.test)('should handle object trace configuration with mode "on"', () => {
+            const testInfo = {
+                testId: "test-1",
+                retry: 0,
+                status: undefined,
+                errors: [],
+                project: {
+                    use: {
+                        trace: { mode: "on", screenshots: true },
+                    },
+                },
+                attach: vitest_1.vi.fn(),
+            };
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(true);
+        });
+        (0, vitest_1.test)("should respect screenshots: false in object trace config", () => {
+            const testInfo = {
+                testId: "test-1",
+                retry: 0,
+                status: undefined,
+                errors: [],
+                project: {
+                    use: {
+                        trace: { mode: "on", screenshots: false },
+                    },
+                },
+                attach: vitest_1.vi.fn(),
+            };
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(false);
+        });
+        (0, vitest_1.test)('should return true on retry with "on-first-retry"', () => {
+            const testInfo = createMockTestInfo({ trace: "on-first-retry" });
+            const service = new service_1.VisualTraceService(testInfo, 1);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(true);
+        });
+        (0, vitest_1.test)('should return false on initial run with "on-first-retry"', () => {
+            const testInfo = createMockTestInfo({ trace: "on-first-retry" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(false);
+        });
+        (0, vitest_1.test)('should return true on all retries with "on-all-retries"', () => {
+            const testInfo = createMockTestInfo({ trace: "on-all-retries" });
+            const service1 = new service_1.VisualTraceService(testInfo, 1);
+            const service2 = new service_1.VisualTraceService(testInfo, 2);
+            (0, vitest_1.expect)(service1.shouldCaptureScreenshot()).toBe(true);
+            (0, vitest_1.expect)(service2.shouldCaptureScreenshot()).toBe(true);
+        });
+        (0, vitest_1.test)("should return true when test has errors", () => {
+            const testInfo = createMockTestInfo({
+                trace: "retain-on-failure",
+                errors: [new Error("Test failed")],
+            });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service.shouldCaptureScreenshot()).toBe(true);
+        });
+    });
+    (0, vitest_1.describe)("captureScreenshot", () => {
+        (0, vitest_1.test)("should capture screenshot when conditions are met", async () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            await service.captureScreenshot(mockTakeScreenshot, "test-step");
+            (0, vitest_1.expect)(mockTakeScreenshot).toHaveBeenCalled();
+            (0, vitest_1.expect)(testInfo.attach).toHaveBeenCalledWith(vitest_1.expect.stringContaining("screenshot-"), vitest_1.expect.objectContaining({
+                body: vitest_1.expect.any(Buffer),
+                contentType: "image/png",
+            }));
+        });
+        (0, vitest_1.test)("should not capture screenshot when disabled", async () => {
+            const testInfo = createMockTestInfo({ trace: "off" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            await service.captureScreenshot(mockTakeScreenshot, "test-step");
+            (0, vitest_1.expect)(mockTakeScreenshot).not.toHaveBeenCalled();
+            (0, vitest_1.expect)(testInfo.attach).not.toHaveBeenCalled();
+        });
+        (0, vitest_1.test)("should include step title in filename", async () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            await service.captureScreenshot(mockTakeScreenshot, "click-submit");
+            (0, vitest_1.expect)(testInfo.attach).toHaveBeenCalledWith(vitest_1.expect.stringContaining("click_submit"), vitest_1.expect.objectContaining({
+                body: vitest_1.expect.any(Buffer),
+                contentType: "image/png",
+            }));
+        });
+        (0, vitest_1.test)("should handle screenshot capture errors gracefully", async () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            const errorTakeScreenshot = vitest_1.vi.fn(() => Promise.reject(new Error("Screenshot failed")));
+            // Mock console.warn to verify it's called
+            const consoleWarnSpy = vitest_1.vi
+                .spyOn(console, "warn")
+                .mockImplementation(() => { });
+            await service.captureScreenshot(errorTakeScreenshot, "test-step");
+            (0, vitest_1.expect)(consoleWarnSpy).toHaveBeenCalledWith(vitest_1.expect.stringContaining("Failed to capture screenshot"));
+            (0, vitest_1.expect)(testInfo.attach).not.toHaveBeenCalled();
+            consoleWarnSpy.mockRestore();
+        });
+    });
+    (0, vitest_1.describe)("Screenshot limits", () => {
+        (0, vitest_1.test)("should respect max screenshot limit", async () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0, {
+                maxScreenshots: 2,
+                dedupe: false,
+            });
+            // Capture first two screenshots
+            await service.captureScreenshot(mockTakeScreenshot, "step-1");
+            await service.captureScreenshot(mockTakeScreenshot, "step-2");
+            // Third screenshot should be skipped
+            await service.captureScreenshot(mockTakeScreenshot, "step-3");
+            (0, vitest_1.expect)(mockTakeScreenshot).toHaveBeenCalledTimes(2);
+            (0, vitest_1.expect)(service.getScreenshotCount()).toBe(2);
+        });
+        (0, vitest_1.test)("should track screenshot count correctly", async () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0, { dedupe: false });
+            (0, vitest_1.expect)(service.getScreenshotCount()).toBe(0);
+            await service.captureScreenshot(mockTakeScreenshot, "step-1");
+            (0, vitest_1.expect)(service.getScreenshotCount()).toBe(1);
+            await service.captureScreenshot(mockTakeScreenshot, "step-2");
+            (0, vitest_1.expect)(service.getScreenshotCount()).toBe(2);
+        });
+    });
+    (0, vitest_1.describe)("Deduplication", () => {
+        (0, vitest_1.test)("should skip duplicate screenshots when dedupe is enabled", async () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0, { dedupe: true });
+            // Same screenshot data
+            const sameData = Buffer.from("same-screenshot");
+            const sameTakeScreenshot = vitest_1.vi.fn(() => Promise.resolve(sameData));
+            await service.captureScreenshot(sameTakeScreenshot, "step-1");
+            await service.captureScreenshot(sameTakeScreenshot, "step-2");
+            (0, vitest_1.expect)(sameTakeScreenshot).toHaveBeenCalledTimes(2);
+            (0, vitest_1.expect)(testInfo.attach).toHaveBeenCalledTimes(1); // Only attached once
+        });
+        (0, vitest_1.test)("should capture all screenshots when dedupe is disabled", async () => {
+            const testInfo = createMockTestInfo({ trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0, { dedupe: false });
+            // Same screenshot data
+            const sameData = Buffer.from("same-screenshot");
+            const sameTakeScreenshot = vitest_1.vi.fn(() => Promise.resolve(sameData));
+            await service.captureScreenshot(sameTakeScreenshot, "step-1");
+            await service.captureScreenshot(sameTakeScreenshot, "step-2");
+            (0, vitest_1.expect)(sameTakeScreenshot).toHaveBeenCalledTimes(2);
+            (0, vitest_1.expect)(testInfo.attach).toHaveBeenCalledTimes(2); // Attached both times
+        });
+    });
+    (0, vitest_1.describe)("State management", () => {
+        (0, vitest_1.test)("should maintain separate state for different test attempts", async () => {
+            const testInfo = createMockTestInfo({ testId: "test-1", trace: "on" });
+            // First attempt
+            const service1 = new service_1.VisualTraceService(testInfo, 0);
+            await service1.captureScreenshot(mockTakeScreenshot, "step-1");
+            (0, vitest_1.expect)(service1.getScreenshotCount()).toBe(1);
+            // Second attempt (retry)
+            const service2 = new service_1.VisualTraceService(testInfo, 1);
+            (0, vitest_1.expect)(service2.getScreenshotCount()).toBe(0); // Should start fresh
+            await service2.captureScreenshot(mockTakeScreenshot, "step-1");
+            (0, vitest_1.expect)(service2.getScreenshotCount()).toBe(1);
+            // First attempt state should be preserved
+            (0, vitest_1.expect)(service1.getScreenshotCount()).toBe(1);
+        });
+        (0, vitest_1.test)("should reset state when resetState is called", () => {
+            const testInfo = createMockTestInfo({ testId: "test-1", trace: "on" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            service["getState"]().screenshotCount = 5;
+            (0, vitest_1.expect)(service.getScreenshotCount()).toBe(5);
+            service.resetState();
+            (0, vitest_1.expect)(service.getScreenshotCount()).toBe(0);
+        });
+    });
+    (0, vitest_1.describe)("Singleton management", () => {
+        (0, vitest_1.test)("should initialize and get service instance", () => {
+            const testInfo = createMockTestInfo({ testId: "test-1" });
+            const service = (0, service_1.initializeVisualTrace)(testInfo, 0);
+            (0, vitest_1.expect)(service).toBeInstanceOf(service_1.VisualTraceService);
+            const retrievedService = (0, service_1.getVisualTraceService)();
+            (0, vitest_1.expect)(retrievedService).toBe(service);
+        });
+        (0, vitest_1.test)("should clear service instance", () => {
+            const testInfo = createMockTestInfo({ testId: "test-1" });
+            (0, service_1.initializeVisualTrace)(testInfo, 0);
+            (0, vitest_1.expect)((0, service_1.getVisualTraceService)()).not.toBeNull();
+            (0, service_1.clearVisualTraceService)();
+            (0, vitest_1.expect)((0, service_1.getVisualTraceService)()).toBeNull();
+        });
+    });
+    (0, vitest_1.describe)("Configuration update", () => {
+        (0, vitest_1.test)("should update configuration at runtime", () => {
+            const testInfo = createMockTestInfo({ testId: "test-1" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            (0, vitest_1.expect)(service["config"].enableScreenshots).toBe("retain-on-failure");
+            service.updateConfig({ enableScreenshots: "on" });
+            (0, vitest_1.expect)(service["config"].enableScreenshots).toBe("on");
+        });
+        (0, vitest_1.test)("should merge partial config updates", () => {
+            const testInfo = createMockTestInfo({ testId: "test-1" });
+            const service = new service_1.VisualTraceService(testInfo, 0);
+            service.updateConfig({ maxScreenshots: 100 });
+            (0, vitest_1.expect)(service["config"].maxScreenshots).toBe(100);
+            (0, vitest_1.expect)(service["config"].dedupe).toBe(true); // Should preserve other settings
+        });
+    });
+});

package/dist/types/index.d.ts

@@ -43,6 +43,29 @@ export type AppwrightConfig = {
     appBundleId: string;
     expectTimeout: number;
 };
+/**
+ * Configuration for Visual Trace screenshot capture
+ */
+export type VisualTraceConfig = {
+    /**
+     * Controls when screenshots are captured:
+     * - true | 'on': Always capture screenshots
+     * - false | 'off': Never capture screenshots
+     * - 'retain-on-failure': Only capture screenshots when tests fail (default)
+     */
+    enableScreenshots?: boolean | "on" | "off" | "retain-on-failure";
+    /**
+     * Maximum number of screenshots to capture per test.
+     * Default: 50
+     */
+    maxScreenshots?: number;
+    /**
+     * Whether to deduplicate screenshots based on content hash.
+     * Prevents capturing identical screenshots multiple times.
+     * Default: true
+     */
+    dedupe?: boolean;
+};
 export type DeviceConfig = BrowserStackConfig | LambdaTestConfig | LocalDeviceConfig | EmulatorConfig;
 /**
  * Configuration for devices running on Browserstack.

package/dist/types/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"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"}

package/dist/utils.d.ts

@@ -1,8 +1,23 @@
+import { TestInfo } from "@playwright/test";
 export declare function boxedStep(target: Function, context: ClassMethodDecoratorContext): (this: {
-    selector: string | RegExp;
+    selector?: string | RegExp;
+    device?: {
+        takeScreenshot: () => Promise<Buffer>;
+        initializeVisualTrace?: (testInfo: any, retryIndex: number, config?: any) => void;
+    };
+    takeScreenshot?: () => Promise<Buffer>;
+    initializeVisualTrace?: (testInfo: any, retryIndex: number, config?: any) => void;
 }, ...args: any) => Promise<any>;
 export declare function validateBuildPath(buildPath: string | undefined, expectedExtension: string): void;
 export declare function getLatestBuildToolsVersions(versions: string[]): string | undefined;
 export declare function longestDeterministicGroup(pattern: RegExp): string | undefined;
 export declare function basePath(): string;
+/**
+ * Check if tracing is enabled for the current test based on Playwright's trace configuration
+ */
+export declare function isTracingEnabled(testInfo: TestInfo, retryIndex: number): boolean;
+/**
+ * Determine if screenshots should be captured based on trace mode
+ */
+export declare function shouldCaptureScreenshotsFromTrace(testInfo: TestInfo, retryIndex: number): boolean;
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA,wBAAgB,SAAS,CACvB,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,2BAA2B,UAG5B;IACJ,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B,WACQ,GAAG,kBAmBf;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,iBAAiB,EAAE,MAAM,QAoB1B;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAAE,GACjB,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuB7E;AAED,wBAAgB,QAAQ,WAEvB"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAa,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAQlD,wBAAgB,SAAS,CACvB,MAAM,EAAE,QAAQ,EAChB,OAAO,EAAE,2BAA2B,UAG5B;IACJ,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,MAAM,CAAC,EAAE;QACP,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QACtC,qBAAqB,CAAC,EAAE,CACtB,QAAQ,EAAE,GAAG,EACb,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,GAAG,KACT,IAAI,CAAC;KACX,CAAC;IACF,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACvC,qBAAqB,CAAC,EAAE,CACtB,QAAQ,EAAE,GAAG,EACb,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,GAAG,KACT,IAAI,CAAC;CACX,WACQ,GAAG,kBAwEf;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,iBAAiB,EAAE,MAAM,QAoB1B;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAAE,GACjB,MAAM,GAAG,SAAS,CAEpB;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAuB7E;AAED,wBAAgB,QAAQ,WAEvB;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CA2BT;AAED;;GAEG;AACH,wBAAgB,iCAAiC,CAC/C,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,GACjB,OAAO,CAST"}

package/dist/utils.js

@@ -8,9 +8,12 @@ exports.validateBuildPath = validateBuildPath;
 exports.getLatestBuildToolsVersions = getLatestBuildToolsVersions;
 exports.longestDeterministicGroup = longestDeterministicGroup;
 exports.basePath = basePath;
+exports.isTracingEnabled = isTracingEnabled;
+exports.shouldCaptureScreenshotsFromTrace = shouldCaptureScreenshotsFromTrace;
 const test_1 = __importDefault(require("@playwright/test"));
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+const visualTrace_1 = require("./visualTrace");
 function boxedStep(target, context) {
     return function replacementMethod(...args) {
         const path = this.selector ? `("${this.selector}")` : "";
@@ -23,7 +26,47 @@ function boxedStep(target, context) {
             : "";
         const name = `${context.name}${path}${argsString}`;
         return test_1.default.step(name, async () => {
-            return await target.call(this, ...args);
+            let result;
+            let stepFailed = false;
+            try {
+                result = await target.call(this, ...args);
+            }
+            catch (error) {
+                stepFailed = true;
+                throw error; // Re-throw to preserve test failure
+            }
+            finally {
+                // Capture screenshot even if step throws an error
+                let visualTrace = (0, visualTrace_1.getVisualTraceService)();
+                // Check if we need to reinitialize for a new test (important for persistentDevice)
+                if (test_1.default.info) {
+                    try {
+                        const testInfo = test_1.default.info();
+                        const device = this.device || this;
+                        // Initialize or reinitialize if needed
+                        if (device?.initializeVisualTrace && testInfo) {
+                            const needsInit = (0, visualTrace_1.needsVisualTraceReinitialization)(testInfo.testId, testInfo.retry);
+                            if (needsInit) {
+                                // Get visual trace config from project
+                                const visualTraceConfig = testInfo.project?.use
+                                    ?.visualTrace;
+                                device.initializeVisualTrace(testInfo, testInfo.retry, visualTraceConfig);
+                                visualTrace = (0, visualTrace_1.getVisualTraceService)();
+                            }
+                        }
+                    }
+                    catch (e) {
+                        // test.info() might not be available in some contexts
+                    }
+                }
+                // For Device methods, 'this' is the Device instance
+                // For Locator methods, 'this.device' is the Device instance
+                const takeScreenshot = this.device?.takeScreenshot || this.takeScreenshot;
+                if (visualTrace && takeScreenshot) {
+                    await visualTrace.captureScreenshot(() => takeScreenshot.call(this.device || this), context.name, stepFailed);
+                }
+            }
+            return result;
         }, { box: true });
     };
 }
@@ -64,3 +107,40 @@ function longestDeterministicGroup(pattern) {
 function basePath() {
     return path_1.default.join(process.cwd(), "playwright-report", "data", "videos-store");
 }
+/**
+ * Check if tracing is enabled for the current test based on Playwright's trace configuration
+ */
+function isTracingEnabled(testInfo, retryIndex) {
+    const traceMode = testInfo.project.use?.trace;
+    if (!traceMode || traceMode === "off") {
+        return false;
+    }
+    if (traceMode === "on") {
+        return true;
+    }
+    if (traceMode === "retain-on-failure") {
+        // Tracing is enabled if the test has failed
+        return testInfo.status !== undefined && testInfo.status !== "passed";
+    }
+    if (traceMode === "on-first-retry") {
+        // Tracing is enabled on the first retry only
+        return retryIndex === 1;
+    }
+    if (traceMode === "on-all-retries" || traceMode === "retry-with-trace") {
+        // Tracing is enabled on all retries
+        return retryIndex > 0;
+    }
+    return false;
+}
+/**
+ * Determine if screenshots should be captured based on trace mode
+ */
+function shouldCaptureScreenshotsFromTrace(testInfo, retryIndex) {
+    // Check if screenshots are explicitly disabled in project config
+    const screenshotsConfig = testInfo.project.use?.screenshot;
+    if (screenshotsConfig === "off") {
+        return false;
+    }
+    // Use trace configuration to determine screenshot behavior
+    return isTracingEnabled(testInfo, retryIndex);
+}

package/dist/visualTrace/index.d.ts

@@ -0,0 +1,3 @@
+export { VisualTraceService, initializeVisualTrace, getVisualTraceService, clearVisualTraceService, needsVisualTraceReinitialization, } from "./service";
+export type { VisualTraceState } from "./service";
+//# sourceMappingURL=index.d.ts.map

package/dist/visualTrace/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/visualTrace/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,uBAAuB,EACvB,gCAAgC,GACjC,MAAM,WAAW,CAAC;AAEnB,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC"}

package/dist/visualTrace/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.needsVisualTraceReinitialization = exports.clearVisualTraceService = exports.getVisualTraceService = exports.initializeVisualTrace = exports.VisualTraceService = void 0;
+var service_1 = require("./service");
+Object.defineProperty(exports, "VisualTraceService", { enumerable: true, get: function () { return service_1.VisualTraceService; } });
+Object.defineProperty(exports, "initializeVisualTrace", { enumerable: true, get: function () { return service_1.initializeVisualTrace; } });
+Object.defineProperty(exports, "getVisualTraceService", { enumerable: true, get: function () { return service_1.getVisualTraceService; } });
+Object.defineProperty(exports, "clearVisualTraceService", { enumerable: true, get: function () { return service_1.clearVisualTraceService; } });
+Object.defineProperty(exports, "needsVisualTraceReinitialization", { enumerable: true, get: function () { return service_1.needsVisualTraceReinitialization; } });

package/dist/visualTrace/service.d.ts

@@ -0,0 +1,75 @@
+import { TestInfo } from "@playwright/test";
+import { VisualTraceConfig } from "../types";
+export interface VisualTraceState {
+    screenshotCount: number;
+    dedupeHashes: Set<string>;
+}
+export declare class VisualTraceService {
+    private states;
+    private testInfo;
+    readonly retryIndex: number;
+    private config;
+    readonly testId: string;
+    constructor(testInfo: TestInfo, retryIndex: number, config?: VisualTraceConfig);
+    /**
+     * Get or create state for the current test attempt
+     */
+    private getState;
+    /**
+     * Check if screenshots should be captured based on trace mode and test status
+     */
+    shouldCaptureScreenshot(stepFailed?: boolean): boolean;
+    /**
+     * Check our own config mode for screenshot capture
+     */
+    private checkConfigMode;
+    /**
+     * Check if the current test is failing
+     */
+    private isTestFailing;
+    /**
+     * Calculate hash for screenshot deduplication
+     */
+    private calculateHash;
+    /**
+     * Check if we've reached the screenshot limit
+     */
+    private hasReachedLimit;
+    /**
+     * Check if screenshot is a duplicate
+     */
+    private isDuplicate;
+    /**
+     * Capture and attach a screenshot to the test
+     */
+    captureScreenshot(takeScreenshot: () => Promise<Buffer>, stepTitle?: string, stepFailed?: boolean): Promise<void>;
+    /**
+     * Reset state for a test (useful for cleanup)
+     */
+    resetState(): void;
+    /**
+     * Get current screenshot count for the test
+     */
+    getScreenshotCount(): number;
+    /**
+     * Update configuration at runtime
+     */
+    updateConfig(config: Partial<VisualTraceConfig>): void;
+}
+/**
+ * Initialize the Visual Trace Service for a test
+ */
+export declare function initializeVisualTrace(testInfo: TestInfo, retryIndex: number, config?: VisualTraceConfig): VisualTraceService;
+/**
+ * Get the current Visual Trace Service instance
+ */
+export declare function getVisualTraceService(): VisualTraceService | null;
+/**
+ * Check if the Visual Trace Service needs reinitialization for a different test
+ */
+export declare function needsVisualTraceReinitialization(testId: string, retryIndex: number): boolean;
+/**
+ * Clear the Visual Trace Service instance
+ */
+export declare function clearVisualTraceService(): void;
+//# sourceMappingURL=service.d.ts.map

package/dist/visualTrace/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/visualTrace/service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC3B;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,QAAQ,CAAW;IAC3B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,OAAO,CAAC,MAAM,CAAoB;IAClC,SAAgB,MAAM,EAAE,MAAM,CAAC;gBAG7B,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,iBAAiB;IAc5B;;OAEG;IACH,OAAO,CAAC,QAAQ;IAahB;;OAEG;IACH,uBAAuB,CAAC,UAAU,GAAE,OAAe,GAAG,OAAO;IA6D7D;;OAEG;IACH,OAAO,CAAC,eAAe;IAevB;;OAEG;IACH,OAAO,CAAC,aAAa;IAgBrB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAQvB;;OAEG;IACH,OAAO,CAAC,WAAW;IAgBnB;;OAEG;IACG,iBAAiB,CACrB,cAAc,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,EACrC,SAAS,CAAC,EAAE,MAAM,EAClB,UAAU,GAAE,OAAe,GAC1B,OAAO,CAAC,IAAI,CAAC;IA0ChB;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;OAEG;IACH,kBAAkB,IAAI,MAAM;IAK5B;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,IAAI;CAGvD;AAKD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,iBAAiB,GACzB,kBAAkB,CAGpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,IAAI,CAEjE;AAED;;GAEG;AACH,wBAAgB,gCAAgC,CAC9C,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,GACjB,OAAO,CAST;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI,IAAI,CAK9C"}

package/dist/visualTrace/service.js

@@ -0,0 +1,249 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VisualTraceService = void 0;
+exports.initializeVisualTrace = initializeVisualTrace;
+exports.getVisualTraceService = getVisualTraceService;
+exports.needsVisualTraceReinitialization = needsVisualTraceReinitialization;
+exports.clearVisualTraceService = clearVisualTraceService;
+const crypto_1 = __importDefault(require("crypto"));
+class VisualTraceService {
+    states = new Map();
+    testInfo;
+    retryIndex;
+    config;
+    testId;
+    constructor(testInfo, retryIndex, config) {
+        this.testInfo = testInfo;
+        this.retryIndex = retryIndex;
+        this.testId = testInfo.testId;
+        // Default configuration: only capture on failure
+        this.config = {
+            enableScreenshots: config?.enableScreenshots ?? "retain-on-failure",
+            maxScreenshots: config?.maxScreenshots ?? 50,
+            dedupe: config?.dedupe ?? true,
+        };
+    }
+    /**
+     * Get or create state for the current test attempt
+     */
+    getState() {
+        const key = `${this.testInfo.testId}#${this.retryIndex}`;
+        if (!this.states.has(key)) {
+            this.states.set(key, {
+                screenshotCount: 0,
+                dedupeHashes: new Set(),
+            });
+        }
+        return this.states.get(key);
+    }
+    /**
+     * Check if screenshots should be captured based on trace mode and test status
+     */
+    shouldCaptureScreenshot(stepFailed = false) {
+        // Check if screenshots are explicitly disabled
+        if (this.config.enableScreenshots === false ||
+            this.config.enableScreenshots === "off") {
+            return false;
+        }
+        // Get trace configuration from Playwright
+        const traceConfig = this.testInfo.project.use?.trace;
+        // If no trace mode is set, use our config
+        if (!traceConfig) {
+            return this.checkConfigMode(stepFailed);
+        }
+        // Handle both string and object trace configurations
+        let traceMode;
+        if (typeof traceConfig === "string") {
+            traceMode = traceConfig;
+        }
+        else if (typeof traceConfig === "object" && traceConfig.mode) {
+            // Handle object configuration like { mode: 'on', screenshots: true }
+            traceMode = traceConfig.mode;
+            // If screenshots are explicitly disabled in trace config, respect that
+            if (traceConfig.screenshots === false) {
+                return false;
+            }
+        }
+        else {
+            // Unknown format, fall back to our config
+            return this.checkConfigMode(stepFailed);
+        }
+        // Map Playwright trace modes to screenshot behavior
+        switch (traceMode) {
+            case "on":
+                return true;
+            case "retain-on-failure":
+                // Capture if step failed, test already failed, or we're in a retry
+                return stepFailed || this.isTestFailing() || this.retryIndex > 0;
+            case "on-first-retry":
+                // Only capture on first retry
+                return this.retryIndex === 1;
+            case "on-all-retries":
+                // Capture on all retries
+                return this.retryIndex > 0;
+            case "retry-with-trace":
+                return this.retryIndex > 0;
+            case "off":
+                return false;
+            default:
+                return this.checkConfigMode(stepFailed);
+        }
+    }
+    /**
+     * Check our own config mode for screenshot capture
+     */
+    checkConfigMode(stepFailed = false) {
+        const mode = this.config.enableScreenshots;
+        if (mode === true || mode === "on") {
+            return true;
+        }
+        if (mode === "retain-on-failure") {
+            // Capture if step failed or test is already failing
+            return stepFailed || this.isTestFailing();
+        }
+        return false;
+    }
+    /**
+     * Check if the current test is failing
+     */
+    isTestFailing() {
+        // Check test status (will be 'failed', 'timedOut', etc. for failures)
+        if (this.testInfo.status && this.testInfo.status !== "passed") {
+            return true;
+        }
+        // Check if there are any errors
+        if (this.testInfo.errors && this.testInfo.errors.length > 0) {
+            return true;
+        }
+        // During test execution, we might not have status yet
+        // This will be handled by the retry detection
+        return false;
+    }
+    /**
+     * Calculate hash for screenshot deduplication
+     */
+    calculateHash(data) {
+        return crypto_1.default.createHash("sha256").update(data).digest("hex");
+    }
+    /**
+     * Check if we've reached the screenshot limit
+     */
+    hasReachedLimit() {
+        const state = this.getState();
+        return !!(this.config.maxScreenshots &&
+            state.screenshotCount >= this.config.maxScreenshots);
+    }
+    /**
+     * Check if screenshot is a duplicate
+     */
+    isDuplicate(data) {
+        if (!this.config.dedupe) {
+            return false;
+        }
+        const state = this.getState();
+        const hash = this.calculateHash(data);
+        if (state.dedupeHashes.has(hash)) {
+            return true;
+        }
+        state.dedupeHashes.add(hash);
+        return false;
+    }
+    /**
+     * Capture and attach a screenshot to the test
+     */
+    async captureScreenshot(takeScreenshot, stepTitle, stepFailed = false) {
+        // Check if we should capture screenshots
+        if (!this.shouldCaptureScreenshot(stepFailed)) {
+            return;
+        }
+        // Check if we've reached the screenshot limit
+        if (this.hasReachedLimit()) {
+            return;
+        }
+        try {
+            // Take the screenshot
+            const screenshotData = await takeScreenshot();
+            // Check if this is a duplicate screenshot
+            if (this.isDuplicate(screenshotData)) {
+                return;
+            }
+            // Update state
+            const state = this.getState();
+            state.screenshotCount++;
+            // Generate filename with step title if provided
+            const timestamp = Date.now();
+            const stepSuffix = stepTitle
+                ? `-${stepTitle.replace(/[^a-zA-Z0-9]/g, "_")}`
+                : "";
+            const filename = `screenshot-${timestamp}${stepSuffix}.png`;
+            // Attach to test
+            await this.testInfo.attach(filename, {
+                body: screenshotData,
+                contentType: "image/png",
+            });
+        }
+        catch (error) {
+            // Log error but don't fail the test
+            console.warn(`Failed to capture screenshot: ${error}`);
+        }
+    }
+    /**
+     * Reset state for a test (useful for cleanup)
+     */
+    resetState() {
+        const key = `${this.testInfo.testId}#${this.retryIndex}`;
+        this.states.delete(key);
+    }
+    /**
+     * Get current screenshot count for the test
+     */
+    getScreenshotCount() {
+        const state = this.getState();
+        return state.screenshotCount;
+    }
+    /**
+     * Update configuration at runtime
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+}
+exports.VisualTraceService = VisualTraceService;
+// Singleton instance management
+let serviceInstance = null;
+/**
+ * Initialize the Visual Trace Service for a test
+ */
+function initializeVisualTrace(testInfo, retryIndex, config) {
+    serviceInstance = new VisualTraceService(testInfo, retryIndex, config);
+    return serviceInstance;
+}
+/**
+ * Get the current Visual Trace Service instance
+ */
+function getVisualTraceService() {
+    return serviceInstance;
+}
+/**
+ * Check if the Visual Trace Service needs reinitialization for a different test
+ */
+function needsVisualTraceReinitialization(testId, retryIndex) {
+    if (!serviceInstance) {
+        return true;
+    }
+    // Reinitialize if it's a different test or retry
+    return (serviceInstance.testId !== testId ||
+        serviceInstance.retryIndex !== retryIndex);
+}
+/**
+ * Clear the Visual Trace Service instance
+ */
+function clearVisualTraceService() {
+    if (serviceInstance) {
+        serviceInstance.resetState();
+        serviceInstance = null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samsara-dev/appwright",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"