@samsara-dev/appwright 0.5.1 → 0.6.1

package/AGENTS.md

@@ -0,0 +1,53 @@
+# Appwright Agent Guide
+
+## 1. Project Snapshot
+- **Repo type:** Single-package TypeScript library (no workspaces)
+- **Stack:** Node.js ≥20, TypeScript, Playwright fixtures, Vitest, ESLint (`@empiricalrun`)
+- **Docs:** Each major directory ships its own `AGENTS.md`; nearest file wins
+
+## 2. Root Setup Commands
+```bash
+npm ci                # install dependencies (use npm install for incremental updates)
+npm run lint          # ESLint with @empiricalrun rules
+npm run build         # tsc --build (typecheck + emit to dist/)
+npm test -- --run     # Vitest single pass (avoids interactive watch mode)
+npm run changeset     # prepare release notes when changes ship
+```
+
+## 3. Universal Conventions
+- Share a short plan with maintainers **before editing** (hard requirement)
+- Author new code in `src/**`; never modify generated `dist/**`
+- Rely on `src/logger.ts` instead of raw `console` (exceptions stream subprocess output only)
+- Follow Conventional Commits (`feat:`, `fix:`, `chore:`) and branch from `main`
+- Keep APIs backward compatible; prefer additive options over breaking changes
+- Always generate a Changeset that captures the user-facing impact of the feature you worked on
+
+## 4. Security & Secrets
+- Never commit API keys, BrowserStack creds, or AWS secrets; load via environment variables
+- BrowserStack needs `BROWSERSTACK_USERNAME` / `BROWSERSTACK_ACCESS_KEY`
+- Remote build downloads require AWS credentials (`AWS_REGION` plus standard SDK env vars)
+- Avoid storing PII or test artifacts in the repo; use external storage for logs/videos
+
+## 5. JIT Index (what to open, not what to paste)
+
+### Package Structure
+- Core library: `src/` → [see src/AGENTS.md](src/AGENTS.md)
+- Device runtime: `src/device/` → [see src/device/AGENTS.md](src/device/AGENTS.md)
+- Providers (BrowserStack, LambdaTest, emulator, local): `src/providers/` → [see src/providers/AGENTS.md](src/providers/AGENTS.md)
+- Vision utilities: `src/vision/` → [see src/vision/AGENTS.md](src/vision/AGENTS.md)
+- Visual trace capture: `src/visualTrace/` → [see src/visualTrace/AGENTS.md](src/visualTrace/AGENTS.md)
+- Test suite: `src/tests/` → [see src/tests/AGENTS.md](src/tests/AGENTS.md)
+- Example consumer app: `example/` → [see example/AGENTS.md](example/AGENTS.md)
+
+### Quick Find Commands
+- Locate a public export: `rg -n "export .*" src/index.ts src/types` (fallback: `grep -rn "export .*" src/index.ts src/types`)
+- Discover provider hooks: `rg -n "DeviceProvider" src/providers` (fallback: `grep -rn "DeviceProvider" src/providers`)
+- Inspect Playwright fixtures: `rg -n "extend<TestLevelFixtures" src/fixture` (fallback: `grep -rn "extend<TestLevelFixtures" src/fixture`)
+- Track vision helpers: `rg -n "AppwrightVision" src/vision` (fallback: `grep -rn "AppwrightVision" src/vision`)
+- Find targeted tests: `rg -n "\\.spec\\.ts" src/tests` (fallback: `grep -rn "\.spec\.ts" src/tests`)
+
+## 6. Definition of Done
+- `npm run lint && npm run build && npm test -- --run` must all pass locally
+- Add a Changeset entry for user-facing changes
+- Ensure documentation in relevant `AGENTS.md` files reflects the update
+- Confirm the plan was shared and acknowledged before merging

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # appwright
 
+## 0.6.1
+
+### Patch Changes
+
+- 40979ac: - add BrowserStack S3 buildPath support with local download helper and coverage
+  - restructure hierarchical AGENTS.md guidance and reminders for contributors
+
+## 0.6.0
+
+### Minor Changes
+
+- 98c9650: Expose `Device.getTimeouts()` along with a lightweight window helper for better session introspection.
+
 ## 0.5.1
 
 ### Patch Changes

package/dist/device/index.d.ts

@@ -3,6 +3,9 @@ import { AppwrightLocator, DeviceProvider, ExtractType, IosAppSettings, IosPermi
 import { z } from "zod";
 import { LLMModel } from "@empiricalrun/llm";
 import { TestInfo } from "@playwright/test";
+type DeviceTimeouts = Partial<Record<string, number>> & {
+    command?: number;
+};
 export declare class Device {
     private webDriverClient;
     private bundleId;
@@ -188,6 +191,19 @@ export declare class Device {
     setMockCameraView(imagePath: string): Promise<void>;
     pause(): Promise<void>;
     waitForTimeout(timeout: number): Promise<void>;
+    /**
+     * Get the current timeout settings for the WebDriver session.
+     */
+    getTimeouts(): Promise<DeviceTimeouts>;
+    /**
+     * Get the current window rectangle dimensions.
+     */
+    getWindowRect(): Promise<{
+        width: number;
+        height: number;
+        x: number;
+        y: number;
+    }>;
     /**
      * Get a screenshot of the current screen as a base64 encoded string.
      */
@@ -249,4 +265,5 @@ export declare class Device {
      */
     private assertIOSBrowserStack;
 }
+export {};
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/device/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,IAAI,eAAe,EAAE,MAAM,WAAW,CAAC;AAE3D,OAAO,EACL,gBAAgB,EAChB,cAAc,EACd,WAAW,EACX,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,cAAc,EACd,iBAAiB,EAClB,MAAM,UAAU,CAAC;AAKlB,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAO7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5C,qBAAa,MAAM;IAOf,OAAO,CAAC,eAAe;IACvB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,QAAQ;IATlB,OAAO,CAAC,kBAAkB,CAAC,CAAqB;IAChD,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,mBAAmB,CAAC,CAAS;gBAG3B,eAAe,EAAE,eAAe,EAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,WAAW,EAAE,cAAc,EAC3B,QAAQ,EAAE,MAAM,EACxB,cAAc,CAAC,EAAE,cAAc;IAKjC,oBAAoB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI;IAIpD,0BAA0B,IAAI,IAAI;IAI5B,yBAAyB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAO5D,qBAAqB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB/D,OAAO,CAAC,oBAAoB;IAO5B,OAAO,CAAC,aAAa;IAIrB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,aAAa;YAQP,QAAQ;IAetB;;OAEG;IACH,qBAAqB,CACnB,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,iBAAiB,GACzB,IAAI;IAQP;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAKvC,OAAO,CAAC,EACN,QAAQ,EACR,YAAY,EACZ,WAAW,GACZ,EAAE;QACD,QAAQ,EAAE,MAAM,CAAC;QACjB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;KAC/B,GAAG,gBAAgB;IAWpB,OAAO,CAAC,MAAM;IAId,IAAI;sBAEQ,MAAM,YACJ;YACR,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,SAAS,CAAC,EAAE;gBACV,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;aACjB,CAAC;SACH,KACA,OAAO,CAAC;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;gBAItB,CAAC,SAAS,CAAC,CAAC,OAAO,UACvB,MAAM,YACJ;YACR,cAAc,CAAC,EAAE,CAAC,CAAC;YACnB,KAAK,CAAC,EAAE,QAAQ,CAAC;YACjB,UAAU,CAAC,EAAE,MAAM,CAAC;YACpB,SAAS,CAAC,EAAE;gBACV,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;aACjB,CAAC;SACH,KACA,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;MAG1B;IAEF;;;;;;;OAOG;IACG,KAAK;IAiBX;;;;;;;;;;;OAWG;IAEG,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAoB5C;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CACP,IAAI,EAAE,MAAM,GAAG,MAAM,EACrB,EAAE,KAAa,EAAE,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAC1C,gBAAgB;IAsCnB;;;;;;;;;;;;OAYG;IACH,OAAO,CACL,IAAI,EAAE,MAAM,EACZ,EAAE,KAAa,EAAE,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO,GAC1C,gBAAgB;IAiBnB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,gBAAgB;IAI3C;;;;;;;;;OASG;IACH,WAAW,IAAI,QAAQ;IAMjB,YAAY,CAAC,QAAQ,CAAC,EAAE,MAAM;IAc9B,WAAW,CAAC,QAAQ,CAAC,EAAE,MAAM;IAanC;;;;;;;;;;;;;;;;;OAiBG;IAEG,aAAa,CAAC,OAAO,GAAE,MAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQxD;;;;;;;;;;OAUG;IAEG,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAqBzC;;;;;;;;;;;OAWG;IAEG,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnD,KAAK;IAmBL,cAAc,CAAC,OAAO,EAAE,MAAM;IAIpC;;OAEG;IAEG,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC;IAInC;;;;;;;;;;OAUG;IAEG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAU7B;;;OAGG;IAEG,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBlD;;;;;;;;;;;;;;;;;OAiBG;IAEU,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnE;;;;;;;;;;;;;OAaG;IAEU,wBAAwB,CACnC,QAAQ,EAAE,qBAAqB,GAC9B,OAAO,CAAC,IAAI,CAAC;IAIhB;;;OAGG;IACH,OAAO,CAAC,qBAAqB;CAe9B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/device/index.ts"],"names":[],"mappings":"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"}

package/dist/device/index.js

@@ -53,6 +53,8 @@ let Device = (() => {
     let _setMockCameraView_decorators;
     let _pause_decorators;
     let _waitForTimeout_decorators;
+    let _getTimeouts_decorators;
+    let _getWindowRect_decorators;
     let _screenshot_decorators;
     let _scroll_decorators;
     let _sendKeyStrokes_decorators;
@@ -69,6 +71,8 @@ let Device = (() => {
             _setMockCameraView_decorators = [utils_1.boxedStep];
             _pause_decorators = [utils_1.boxedStep];
             _waitForTimeout_decorators = [utils_1.boxedStep];
+            _getTimeouts_decorators = [utils_1.boxedStep];
+            _getWindowRect_decorators = [utils_1.boxedStep];
             _screenshot_decorators = [utils_1.boxedStep];
             _scroll_decorators = [utils_1.boxedStep];
             _sendKeyStrokes_decorators = [utils_1.boxedStep];
@@ -82,6 +86,8 @@ let Device = (() => {
             __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);
             __esDecorate(this, null, _waitForTimeout_decorators, { kind: "method", name: "waitForTimeout", static: false, private: false, access: { has: obj => "waitForTimeout" in obj, get: obj => obj.waitForTimeout }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getTimeouts_decorators, { kind: "method", name: "getTimeouts", static: false, private: false, access: { has: obj => "getTimeouts" in obj, get: obj => obj.getTimeouts }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _getWindowRect_decorators, { kind: "method", name: "getWindowRect", static: false, private: false, access: { has: obj => "getWindowRect" in obj, get: obj => obj.getWindowRect }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _screenshot_decorators, { kind: "method", name: "screenshot", static: false, private: false, access: { has: obj => "screenshot" in obj, get: obj => obj.screenshot }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _scroll_decorators, { kind: "method", name: "scroll", static: false, private: false, access: { has: obj => "scroll" in obj, get: obj => obj.scroll }, metadata: _metadata }, null, _instanceExtraInitializers);
             __esDecorate(this, null, _sendKeyStrokes_decorators, { kind: "method", name: "sendKeyStrokes", static: false, private: false, access: { has: obj => "sendKeyStrokes" in obj, get: obj => obj.sendKeyStrokes }, metadata: _metadata }, null, _instanceExtraInitializers);
@@ -501,6 +507,18 @@ let Device = (() => {
         async waitForTimeout(timeout) {
             await new Promise((resolve) => setTimeout(resolve, timeout));
         }
+        /**
+         * Get the current timeout settings for the WebDriver session.
+         */
+        async getTimeouts() {
+            return (await this.webDriverClient.getTimeouts());
+        }
+        /**
+         * Get the current window rectangle dimensions.
+         */
+        async getWindowRect() {
+            return await this.webDriverClient.getWindowRect();
+        }
         /**
          * Get a screenshot of the current screen as a base64 encoded string.
          */

package/dist/providers/browserstack/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/browserstack/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,eAAe,EACf,cAAc,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAqDtC,qBAAa,0BAA2B,YAAW,cAAc;IAC/D,OAAO,CAAC,cAAc,CAAC,CAA6B;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,OAAO,CAA+B;gBAG5C,OAAO,EAAE,WAAW,CAAC,eAAe,CAAC,EACrC,WAAW,EAAE,MAAM,GAAG,SAAS;IAU3B,WAAW;IAwDX,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAMlC,OAAO,CAAC,cAAc;YASR,YAAY;YAiBZ,iBAAiB;YAKjB,yBAAyB;WAK1B,aAAa,CACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAuFlD,eAAe,CAAC,OAAO,EAAE;QAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf;IA2BD,OAAO,CAAC,YAAY;CAuFrB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/browserstack/index.ts"],"names":[],"mappings":"AAIA,OAAO,EACL,eAAe,EACf,cAAc,EAGf,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAsDtC,qBAAa,0BAA2B,YAAW,cAAc;IAC/D,OAAO,CAAC,cAAc,CAAC,CAA6B;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,OAAO,CAA+B;gBAG5C,OAAO,EAAE,WAAW,CAAC,eAAe,CAAC,EACrC,WAAW,EAAE,MAAM,GAAG,SAAS;IAU3B,WAAW;IA0EX,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAMlC,OAAO,CAAC,cAAc;YASR,YAAY;YAiBZ,iBAAiB;YAKjB,yBAAyB;WAK1B,aAAa,CACxB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAuFlD,eAAe,CAAC,OAAO,EAAE;QAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf;IA2BD,OAAO,CAAC,YAAY;CAuFrB"}

package/dist/providers/browserstack/index.js

@@ -11,6 +11,7 @@ const path_1 = __importDefault(require("path"));
 const types_1 = require("../../types");
 const device_1 = require("../../device");
 const logger_1 = require("../../logger");
+const s3_1 = require("./s3");
 const API_BASE_URL = "https://api-cloud.browserstack.com/app-automate";
 const envVarKeyForBuild = (projectName) => `BROWSERSTACK_APP_URL_${projectName.toUpperCase()}`;
 function getAuthHeader() {
@@ -50,45 +51,59 @@ class BrowserStackDeviceProvider {
             throw new Error("BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY are required environment variables for this device provider.");
         }
         const buildPath = this.project.use.buildPath;
-        const isHttpUrl = buildPath.startsWith("http");
+        const isS3Url = (0, s3_1.isS3Uri)(buildPath);
+        const isHttpUrl = !isS3Url && buildPath.startsWith("http");
         const isBrowserStackUrl = buildPath.startsWith("bs://");
         let appUrl = undefined;
-        if (isBrowserStackUrl) {
-            appUrl = buildPath;
-        }
-        else {
-            // Upload the file to BrowserStack and get the appUrl
-            let body;
-            let headers = {
-                Authorization: getAuthHeader(),
-            };
-            if (isHttpUrl) {
-                body = new URLSearchParams({
-                    url: buildPath,
-                });
+        let downloadedArtifact;
+        try {
+            if (isBrowserStackUrl) {
+                appUrl = buildPath;
             }
             else {
-                if (!fs_1.default.existsSync(buildPath)) {
-                    throw new Error(`Build file not found: ${buildPath}`);
+                // Upload the file to BrowserStack and get the appUrl
+                let body;
+                let headers = {
+                    Authorization: getAuthHeader(),
+                };
+                let uploadSource = buildPath;
+                if (isS3Url) {
+                    logger_1.logger.log(`Downloading build from S3: ${buildPath}`);
+                    downloadedArtifact = await (0, s3_1.downloadS3Artifact)(buildPath);
+                    uploadSource = downloadedArtifact.filePath;
+                }
+                if (isHttpUrl) {
+                    body = new URLSearchParams({
+                        url: buildPath,
+                    });
+                }
+                else {
+                    if (!fs_1.default.existsSync(uploadSource)) {
+                        throw new Error(`Build file not found: ${uploadSource}`);
+                    }
+                    const form = new form_data_1.default();
+                    form.append("file", fs_1.default.createReadStream(uploadSource));
+                    headers = { ...headers, ...form.getHeaders() };
+                    body = form;
+                }
+                const fetch = (await import("node-fetch")).default;
+                logger_1.logger.log(`Uploading build to BrowserStack: ${uploadSource}`);
+                const response = await fetch(`${API_BASE_URL}/upload`, {
+                    method: "POST",
+                    headers,
+                    body,
+                });
+                const data = await response.json();
+                appUrl = data.app_url;
+                if (!appUrl) {
+                    logger_1.logger.error("Uploading the build failed:", data);
+                    throw new Error(`Failed to upload build to BrowserStack: ${JSON.stringify(data)}`);
                 }
-                const form = new form_data_1.default();
-                form.append("file", fs_1.default.createReadStream(buildPath));
-                headers = { ...headers, ...form.getHeaders() };
-                body = form;
-            }
-            const fetch = (await import("node-fetch")).default;
-            logger_1.logger.log(`Uploading: ${buildPath}`);
-            const response = await fetch(`${API_BASE_URL}/upload`, {
-                method: "POST",
-                headers,
-                body,
-            });
-            const data = await response.json();
-            appUrl = data.app_url;
-            if (!appUrl) {
-                logger_1.logger.error("Uploading the build failed:", data);
             }
         }
+        finally {
+            await downloadedArtifact?.cleanup();
+        }
         process.env[envVarKeyForBuild(this.project.name)] = appUrl;
     }
     async getDevice() {

package/dist/providers/browserstack/s3.d.ts

@@ -0,0 +1,11 @@
+export type DownloadedS3Artifact = {
+    filePath: string;
+    cleanup: () => Promise<void>;
+};
+export declare function isS3Uri(value: string): boolean;
+export declare function parseS3Uri(uri: string): {
+    bucket: string;
+    key: string;
+};
+export declare function downloadS3Artifact(uri: string): Promise<DownloadedS3Artifact>;
+//# sourceMappingURL=s3.d.ts.map

package/dist/providers/browserstack/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../../src/providers/browserstack/s3.ts"],"names":[],"mappings":"AAeA,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AAEF,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE9C;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAoBvE;AAgDD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,oBAAoB,CAAC,CA8B/B"}

package/dist/providers/browserstack/s3.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isS3Uri = isS3Uri;
+exports.parseS3Uri = parseS3Uri;
+exports.downloadS3Artifact = downloadS3Artifact;
+const fs_1 = __importDefault(require("fs"));
+const promises_1 = __importDefault(require("fs/promises"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const promises_2 = require("stream/promises");
+const stream_1 = require("stream");
+const client_s3_1 = require("@aws-sdk/client-s3");
+const S3_SCHEME = "s3://";
+const TEMP_PREFIX = "appwright-s3-";
+function isS3Uri(value) {
+    return value.startsWith(S3_SCHEME);
+}
+function parseS3Uri(uri) {
+    if (!isS3Uri(uri)) {
+        throw new Error(`Invalid S3 URI: ${uri}`);
+    }
+    const remainder = uri.slice(S3_SCHEME.length);
+    const firstSlash = remainder.indexOf("/");
+    if (firstSlash === -1) {
+        throw new Error(`S3 URI must be in the format s3://bucket/key. Received: ${uri}`);
+    }
+    const bucket = remainder.slice(0, firstSlash);
+    const key = remainder.slice(firstSlash + 1);
+    if (!bucket || !key) {
+        throw new Error(`S3 URI must include both bucket and key: ${uri}`);
+    }
+    return {
+        bucket,
+        key: decodeURIComponent(key),
+    };
+}
+async function writeBodyToFile(body, destination) {
+    if (!body) {
+        throw new Error("Received empty S3 object body");
+    }
+    if (body instanceof stream_1.Readable) {
+        await (0, promises_2.pipeline)(body, fs_1.default.createWriteStream(destination));
+        return;
+    }
+    if (typeof body.transformToByteArray === "function") {
+        const bytes = await body.transformToByteArray();
+        await promises_1.default.writeFile(destination, Buffer.from(bytes));
+        return;
+    }
+    if (typeof body.arrayBuffer === "function") {
+        const buffer = Buffer.from(await body.arrayBuffer());
+        await promises_1.default.writeFile(destination, buffer);
+        return;
+    }
+    if (Symbol.asyncIterator in Object(body)) {
+        const chunks = [];
+        const iterable = body;
+        for await (const chunk of iterable) {
+            if (typeof chunk === "string") {
+                chunks.push(Buffer.from(chunk));
+            }
+            else if (chunk instanceof Uint8Array) {
+                chunks.push(Buffer.from(chunk));
+            }
+            else {
+                chunks.push(Buffer.from(String(chunk)));
+            }
+        }
+        await promises_1.default.writeFile(destination, Buffer.concat(chunks));
+        return;
+    }
+    throw new Error("Unsupported S3 response body type");
+}
+async function downloadS3Artifact(uri) {
+    const { bucket, key } = parseS3Uri(uri);
+    const region = process.env.AWS_REGION ?? process.env.AWS_DEFAULT_REGION;
+    if (!region) {
+        throw new Error("Set AWS_REGION or AWS_DEFAULT_REGION to download builds from S3.");
+    }
+    const client = new client_s3_1.S3Client({ region });
+    const command = new client_s3_1.GetObjectCommand({ Bucket: bucket, Key: key });
+    const response = await client.send(command);
+    const tmpDir = await promises_1.default.mkdtemp(path_1.default.join(os_1.default.tmpdir(), TEMP_PREFIX));
+    const fileName = key.split("/").filter(Boolean).pop() ?? "artifact";
+    const destination = path_1.default.join(tmpDir, fileName);
+    try {
+        await writeBodyToFile(response.Body, destination);
+    }
+    catch (error) {
+        await promises_1.default.rm(tmpDir, { recursive: true, force: true });
+        throw error;
+    }
+    return {
+        filePath: destination,
+        cleanup: async () => {
+            await promises_1.default.rm(tmpDir, { recursive: true, force: true });
+        },
+    };
+}

package/dist/tests/browserstack.s3.spec.d.ts

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

package/dist/tests/browserstack.s3.spec.d.ts.map

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

package/dist/tests/browserstack.s3.spec.js

@@ -0,0 +1,78 @@
+"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 stream_1 = require("stream");
+const promises_1 = __importDefault(require("fs/promises"));
+const sendMock = vitest_1.vi.fn();
+const capturedConfigs = [];
+vitest_1.vi.mock("@aws-sdk/client-s3", () => {
+    class MockS3Client {
+        constructor(options) {
+            capturedConfigs.push(options);
+        }
+        send = sendMock;
+    }
+    class MockGetObjectCommand {
+        input;
+        constructor(input) {
+            this.input = input;
+        }
+    }
+    return {
+        S3Client: MockS3Client,
+        GetObjectCommand: MockGetObjectCommand,
+        __esModule: true,
+    };
+});
+let browserstackS3;
+(0, vitest_1.beforeAll)(async () => {
+    browserstackS3 = await import("../providers/browserstack/s3.js");
+});
+(0, vitest_1.afterEach)(async () => {
+    sendMock.mockReset();
+    capturedConfigs.length = 0;
+    delete process.env.AWS_REGION;
+    delete process.env.AWS_DEFAULT_REGION;
+});
+(0, vitest_1.describe)("browserstack S3 helpers", () => {
+    (0, vitest_1.test)("parseS3Uri extracts bucket and decoded key", () => {
+        const result = browserstackS3.parseS3Uri("s3://my-bucket/builds/app%20v2.ipa");
+        (0, vitest_1.expect)(result).toEqual({
+            bucket: "my-bucket",
+            key: "builds/app v2.ipa",
+        });
+    });
+    (0, vitest_1.test)("downloadS3Artifact saves file locally and cleans up", async () => {
+        process.env.AWS_REGION = "us-west-2";
+        sendMock.mockResolvedValueOnce({
+            Body: stream_1.Readable.from(["test-binary"]),
+        });
+        const artifact = await browserstackS3.downloadS3Artifact("s3://test-bucket/apps/mobile.apk");
+        const fileContents = await promises_1.default.readFile(artifact.filePath, "utf-8");
+        (0, vitest_1.expect)(fileContents).toBe("test-binary");
+        (0, vitest_1.expect)(sendMock).toHaveBeenCalledTimes(1);
+        (0, vitest_1.expect)(sendMock.mock.calls[0]?.[0]).toMatchObject({
+            input: { Bucket: "test-bucket", Key: "apps/mobile.apk" },
+        });
+        (0, vitest_1.expect)(capturedConfigs[0]).toMatchObject({ region: "us-west-2" });
+        await artifact.cleanup();
+        await (0, vitest_1.expect)(promises_1.default.stat(artifact.filePath)).rejects.toMatchObject({
+            code: "ENOENT",
+        });
+    });
+    (0, vitest_1.test)("downloadS3Artifact throws when region is missing", async () => {
+        sendMock.mockResolvedValueOnce({
+            Body: stream_1.Readable.from(["unused"]),
+        });
+        await (0, vitest_1.expect)(browserstackS3.downloadS3Artifact("s3://bucket/key")).rejects.toThrow(/AWS_REGION/);
+        (0, vitest_1.expect)(sendMock).not.toHaveBeenCalled();
+    });
+    (0, vitest_1.test)("isS3Uri differentiates schemes", () => {
+        (0, vitest_1.expect)(browserstackS3.isS3Uri("s3://bucket/key")).toBe(true);
+        (0, vitest_1.expect)(browserstackS3.isS3Uri("https://example.com/app.apk")).toBe(false);
+        (0, vitest_1.expect)(browserstackS3.isS3Uri("bs://sample-app")).toBe(false);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@samsara-dev/appwright",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -36,6 +36,7 @@
   "license": "Apache-2.0",
   "description": "E2E mobile app testing done right, with the Playwright test runner",
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.932.0",
     "@empiricalrun/llm": "^0.9.25",
     "@ffmpeg-installer/ffmpeg": "^1.1.0",
     "@playwright/test": "^1.56.1",