diff --git a/.changeset/browserstack-provider-plugin.md b/.changeset/browserstack-provider-plugin.md new file mode 100644 index 0000000000..9d5cd75dc2 --- /dev/null +++ b/.changeset/browserstack-provider-plugin.md @@ -0,0 +1,5 @@ +--- +'agent-device': minor +--- + +Extract BrowserStack out of the bundled WebDriver provider into the new `@agent-device/browserstack` plugin package. Install it with `agent-device plugins add @agent-device/browserstack`, then close your sessions and run `agent-device daemon stop --state-dir ` for your daemon before reconnecting. Commands for a saved BrowserStack connection keep working while the plugin is installed; without it, `connect browserstack` explains how to install the plugin. diff --git a/.fallowrc.json b/.fallowrc.json index 7df7e8b253..3e0f1195ed 100644 --- a/.fallowrc.json +++ b/.fallowrc.json @@ -5,6 +5,8 @@ "tools/depgraph-view/app.js", "scripts/check-provider-plugin.mjs", "scripts/check-affected/command.ts", + "packages/provider-browserstack/test/package-smoke.mjs", + "packages/provider-browserstack/tsdown.config.ts", "packages/provider-testmu/test/package-smoke.mjs", "packages/maestro/test/package-artifact.test.mjs", "packages/maestro/test/packed-clickability.mjs", @@ -110,9 +112,9 @@ // @agent-device/provider-limrun owns the source import, while the published // root build externalizes @limrun/api and retains runtime imports in packed chunks. "@limrun/api", - // @agent-device/testmu imports agent-device type-only, and its tsconfig maps those specifiers - // through this workspace link to core source so typecheck needs no build; Fallow then credits - // the source files rather than the package. + // @agent-device/browserstack and @agent-device/testmu import agent-device type-only, and their + // tsconfigs map those specifiers through this workspace link to core source so typecheck needs + // no build; Fallow then credits the source files rather than the package. "agent-device", // Nothing in the root imports the TV plugins or the tv-cdp package they bundle, but layering // requires the root manifest to declare every workspace package. diff --git a/README.md b/README.md index 17c0c4a8f7..bd167f98c0 100644 --- a/README.md +++ b/README.md @@ -151,7 +151,7 @@ The same session and evidence model works at every step: the agent explores the | --- | --- | --- | | Local | Trying commands and debugging apps on simulators, emulators, physical devices, macOS, and Linux. | Follow the Quick Start. | | CI/CD | Automated pull request and merge validation with replay scripts and captured artifacts. | Try the [EAS workflow template](https://github.com/callstackincubator/eas-agent-device/blob/main/.eas/workflows/agent-qa-mobile.yml). | -| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://agent-device.dev/docs/remote-proxy), connect a [device cloud](https://agent-device.dev/docs/device-clouds) (BrowserStack, AWS Device Farm, TestMu AI, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. | +| Cloud / remote | Linux runners, managed devices, and remote jobs. | Set up a [remote proxy](https://agent-device.dev/docs/remote-proxy), connect a [device cloud](https://agent-device.dev/docs/device-clouds) (BrowserStack and TestMu AI through `agent-device plugins add`, AWS Device Farm, Limrun), or [contact Callstack](mailto:hello@callstack.com) for team QA. | ## How it works diff --git a/docs/agents/code-ownership.md b/docs/agents/code-ownership.md index 30674c687c..f446a0cbb5 100644 --- a/docs/agents/code-ownership.md +++ b/docs/agents/code-ownership.md @@ -6,6 +6,7 @@ Before you edit a module with many callers, run `pnpm depgraph affected `. | Question | Owner | | --- | --- | +| Shared bundler policy | `packages/build-config/src/index.ts` | | Command names | `packages/command-registry/src/catalog.ts` | | Command descriptors | `packages/command-registry/src/`: `registry.ts`, `descriptor-*.ts`, `descriptors/` | | Daemon request-policy predicates | `packages/daemon/src/core/daemon-command-registry.ts` | diff --git a/examples/sdk/tsconfig.json b/examples/sdk/tsconfig.json index c913117ab3..aeaa54003a 100644 --- a/examples/sdk/tsconfig.json +++ b/examples/sdk/tsconfig.json @@ -37,6 +37,7 @@ "include": [".", "../../src/**/*", "../../packages/command-registry/src/global.d.ts"], "exclude": ["../../src/**/*.test.ts", "../../src/**/__tests__/**", "../../src/**/*.fixtures.ts"], "references": [ + { "path": "../../packages/build-config" }, { "path": "../../packages/ad-replay" }, { "path": "../../packages/ad-script" }, { "path": "../../packages/apple-runner" }, @@ -64,6 +65,7 @@ { "path": "../../packages/provider-limrun" }, { "path": "../../packages/provider-revyl" }, { "path": "../../packages/provider-testmu" }, + { "path": "../../packages/provider-browserstack" }, { "path": "../../packages/provider-webos" }, { "path": "../../packages/provider-tizen" }, { "path": "../../packages/provider-webdriver" }, diff --git a/package.json b/package.json index 7f3b183569..4bc62bdc9e 100644 --- a/package.json +++ b/package.json @@ -376,8 +376,10 @@ "yaml": "^2.9.0", "yauzl": "^3.4.0", "@agent-device/testmu": "workspace:*", + "@agent-device/browserstack": "workspace:*", "@agent-device/revyl": "workspace:*", "@agent-device/webos": "workspace:*", - "@agent-device/tizen": "workspace:*" + "@agent-device/tizen": "workspace:*", + "@agent-device/build-config": "workspace:*" } } diff --git a/packages/build-config/package.json b/packages/build-config/package.json new file mode 100644 index 0000000000..5cae8eb212 --- /dev/null +++ b/packages/build-config/package.json @@ -0,0 +1,16 @@ +{ + "name": "@agent-device/build-config", + "version": "0.0.0", + "private": true, + "type": "module", + "description": "Shared repository bundler configuration.", + "exports": { + ".": { + "types": "./src/index.ts", + "default": "./src/index.ts" + } + }, + "devDependencies": { + "rolldown": "1.2.5" + } +} diff --git a/packages/build-config/src/index.ts b/packages/build-config/src/index.ts new file mode 100644 index 0000000000..38ca7c8926 --- /dev/null +++ b/packages/build-config/src/index.ts @@ -0,0 +1,21 @@ +import type { InputOptions } from 'rolldown'; + +export const strictBundlerInputOptions: InputOptions = { + onLog(level, log, handler) { + if (log.code === 'UNRESOLVED_IMPORT') throw new Error(log.message); + handler(level, log); + }, +}; + +export const providerPluginBuildConfig = { + entry: { 'agent-device': 'src/index.ts' }, + outDir: 'dist', + format: 'esm' as const, + platform: 'node' as const, + target: 'es2022' as const, + minify: true, + dts: false, + hash: false, + deps: { alwaysBundle: [/^@agent-device\//] }, + inputOptions: strictBundlerInputOptions, +}; diff --git a/packages/build-config/tsconfig.json b/packages/build-config/tsconfig.json new file mode 100644 index 0000000000..77de1f500d --- /dev/null +++ b/packages/build-config/tsconfig.json @@ -0,0 +1,14 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "composite": true, + "noEmit": false, + "emitDeclarationOnly": true, + "declaration": true, + "declarationDir": "./dist-types", + "rootDir": "./src", + "tsBuildInfoFile": "./dist-types/index.tsbuildinfo" + }, + "include": ["src"], + "references": [] +} diff --git a/packages/provider-browserstack/README.md b/packages/provider-browserstack/README.md new file mode 100644 index 0000000000..4dcfc47f30 --- /dev/null +++ b/packages/provider-browserstack/README.md @@ -0,0 +1,40 @@ +# @agent-device/browserstack + +Use BrowserStack App Automate Android and iOS devices with [agent-device](https://agent-device.dev). +You need a BrowserStack account with App Automate access. + +```sh +npm install -g agent-device +agent-device plugins add @agent-device/browserstack +export BROWSERSTACK_USERNAME=your-username +export BROWSERSTACK_ACCESS_KEY=your-access-key +agent-device connect browserstack --session checkout-android --platform android --device "Google Pixel 8" --provider-os-version 14.0 --provider-app bs://app-id +``` + +See the [BrowserStack guide](https://agent-device.dev/docs/browserstack) for setup and supported operations. +To update the plugin, run `agent-device plugins update @agent-device/browserstack`. + +After you add or update the plugin, close your sessions and run `agent-device daemon stop --state-dir ` for your daemon before reconnecting. + +## Use it from JavaScript + +The package default-exports a plugin factory. Pass credentials as options, or leave them out to read `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` from the environment: + +```js +import { startAgentDevice } from 'agent-device'; +import browserstack from '@agent-device/browserstack'; + +const host = await startAgentDevice({ + stateDir: './.my-app/agent-device-state', + plugins: [ + browserstack({ credentials: { username: 'your-username', accessKey: 'your-access-key' } }), + ], +}); +try { + console.log(await host.client.sessions.list()); +} finally { + await host.close(); +} +``` + +Each credential key passed as an option replaces its environment variable. A key left out uses the environment, and only that environment key participates in the credential fingerprint. diff --git a/packages/provider-browserstack/package.json b/packages/provider-browserstack/package.json new file mode 100644 index 0000000000..9d95aa18e0 --- /dev/null +++ b/packages/provider-browserstack/package.json @@ -0,0 +1,59 @@ +{ + "name": "@agent-device/browserstack", + "version": "0.22.0-dev", + "private": true, + "type": "module", + "description": "BrowserStack real-device cloud plugin for agent-device.", + "files": [ + "dist" + ], + "scripts": { + "build": "tsdown --config tsdown.config.ts", + "prepack": "pnpm build" + }, + "exports": { + ".": { + "types": "./src/index.ts", + "default": "./src/index.ts" + }, + "./agent-device": { + "types": "./src/index.ts", + "default": "./src/index.ts" + }, + "./connection-verification": { + "types": "./src/browserstack-connection-verification.ts", + "default": "./src/browserstack-connection-verification.ts" + }, + "./package.json": "./package.json" + }, + "devDependencies": { + "@agent-device/contracts": "workspace:*", + "@agent-device/kernel": "workspace:*", + "@agent-device/provider-webdriver": "workspace:*", + "agent-device": "workspace:*", + "@agent-device/test-kit": "workspace:*", + "@agent-device/build-config": "workspace:*" + }, + "publishConfig": { + "exports": { + ".": { + "import": "./dist/agent-device.mjs" + }, + "./agent-device": { + "import": "./dist/agent-device.mjs" + }, + "./connection-verification": { + "import": "./dist/connection-verification.mjs" + }, + "./package.json": "./package.json" + }, + "access": "public" + }, + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/callstack/agent-device.git", + "directory": "packages/provider-browserstack" + }, + "homepage": "https://agent-device.dev/docs/browserstack" +} diff --git a/packages/provider-browserstack/src/browserstack-connection-verification.test.ts b/packages/provider-browserstack/src/browserstack-connection-verification.test.ts new file mode 100644 index 0000000000..cf55bd14b2 --- /dev/null +++ b/packages/provider-browserstack/src/browserstack-connection-verification.test.ts @@ -0,0 +1,206 @@ +import assert from 'node:assert/strict'; +import { afterEach, test, vi } from 'vitest'; +import { AppError } from '@agent-device/kernel/errors'; +import { verifyBrowserStackConnection } from './browserstack-connection-verification.ts'; + +const CLIENT_VERSION = '1.2.3'; + +const browserStackOptions = { + username: 'browser-user', + accessKey: 'browser-key', + platform: 'android' as const, + deviceName: 'Google Pixel 8', + osVersion: '14.0', + app: 'bs://app-id', +}; + +afterEach(() => vi.unstubAllGlobals()); + +test('BrowserStack verifies the selected resources without creating a session', async () => { + const fetchMock = vi.fn(async (input) => + String(input).includes('devices') + ? jsonResponse([ + { os: 'android', os_version: '14.0', device: 'Google Pixel 8', realMobile: true }, + ]) + : jsonResponse([{ app_name: 'sample.apk', app_version: '1.2.3', app_url: 'bs://app-id' }]), + ); + vi.stubGlobal('fetch', fetchMock); + + const result = await verifyBrowserStackConnection( + { + ...browserStackOptions, + devicesEndpoint: 'https://browserstack.test/devices', + appsEndpoint: 'https://browserstack.test/apps', + }, + CLIENT_VERSION, + ); + + assert.equal(result.provider, 'browserstack'); + assert.deepEqual(result.device, { + status: 'verified', + name: 'Google Pixel 8', + platform: 'android', + osVersion: '14.0', + }); + assert.deepEqual(result.app, { + status: 'verified', + name: 'sample.apk', + reference: 'bs://app-id', + version: '1.2.3', + }); + assert.deepEqual( + fetchMock.mock.calls.map(([input]) => String(input)), + ['https://browserstack.test/devices', 'https://browserstack.test/apps'], + ); +}); + +test('BrowserStack classifies rejected credentials without exposing them', async () => { + vi.stubGlobal( + 'fetch', + vi.fn(async () => jsonResponse({}, 401)), + ); + + await assert.rejects( + verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), + (error: unknown) => { + assert.equal((error as { code?: string }).code, 'UNAUTHORIZED'); + assert.doesNotMatch(JSON.stringify(error), /browser-key/); + return true; + }, + ); +}); + +test('BrowserStack points HTTP failures at its service status and transport failures at the network', async () => { + vi.stubGlobal( + 'fetch', + vi.fn(async () => jsonResponse({}, 503)), + ); + await assert.rejects( + verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), + (error: unknown) => { + assert.equal((error as { code?: string }).code, 'COMMAND_FAILED'); + assert.equal( + (error as { details?: { hint?: string } }).details?.hint, + 'Retry connect or check the BrowserStack service status.', + ); + return true; + }, + ); + + vi.stubGlobal( + 'fetch', + vi.fn(async () => { + throw new TypeError('fetch failed'); + }), + ); + await assert.rejects( + verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), + (error: unknown) => { + assert.equal((error as { code?: string }).code, 'COMMAND_FAILED'); + assert.equal( + (error as { details?: { hint?: string } }).details?.hint, + 'Check network access to api-cloud.browserstack.com and retry connect.', + ); + return true; + }, + ); +}); + +test('BrowserStack reports a non-JSON verification answer typed, with its status', async () => { + vi.stubGlobal( + 'fetch', + vi.fn(async () => new Response('maintenance', { status: 200 })), + ); + + await assert.rejects( + verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'COMMAND_FAILED'); + assert.equal(error.message, 'BrowserStack connection verification answer was not JSON.'); + assert.equal(error.details?.status, 200); + assert.equal(error.details?.hint, 'Retry connect or check the BrowserStack service status.'); + return true; + }, + ); +}); + +test('BrowserStack verification canonicalizes the bs:// scheme and refuses an id outside its grammar', async () => { + const fetchMock = vi.fn(async (input) => + String(input).includes('devices') + ? jsonResponse([{ os: 'android', os_version: '14.0', device: 'Google Pixel 8' }]) + : jsonResponse([{ app_name: 'sample.apk', app_url: 'bs://app-id' }]), + ); + vi.stubGlobal('fetch', fetchMock); + + const result = await verifyBrowserStackConnection( + { + ...browserStackOptions, + app: 'BS://app-id', + }, + CLIENT_VERSION, + ); + assert.deepEqual(result.app, { + status: 'verified', + name: 'sample.apk', + reference: 'bs://app-id', + }); + + fetchMock.mockClear(); + await assert.rejects( + verifyBrowserStackConnection({ ...browserStackOptions, app: 'bs://a b' }, CLIENT_VERSION), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'INVALID_ARGS'); + assert.equal(error.message, 'BrowserStack --provider-app bs://a b is not a bs:// app id.'); + assert.deepEqual(error.details, { + providerApp: 'bs://a b', + hint: 'Pass .', + }); + return true; + }, + ); + assert.equal(fetchMock.mock.calls.length, 0); +}); + +test('BrowserStack defers a bs app reference outside the recent upload window', async () => { + vi.stubGlobal( + 'fetch', + vi.fn(async (input) => + String(input).includes('devices') + ? jsonResponse([{ os: 'android', os_version: '14', device: 'Google Pixel 8' }]) + : jsonResponse([]), + ), + ); + + const result = await verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION); + + assert.deepEqual(result.app, { + status: 'configured', + reference: 'bs://app-id', + message: + 'App reference was not found in the 100 most recent uploads; BrowserStack validates it when creating the session.', + }); + assert.match( + result.verificationMessage, + /app availability is checked when the session is created/, + ); +}); + +test('BrowserStack accepts an empty-object recent apps response', async () => { + vi.stubGlobal( + 'fetch', + vi.fn(async (input) => + String(input).includes('devices') + ? jsonResponse([{ os: 'android', os_version: '14', device: 'Google Pixel 8' }]) + : jsonResponse({}), + ), + ); + + const result = await verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION); + assert.equal(result.app.status, 'configured'); +}); + +function jsonResponse(value: unknown, status = 200): Response { + return new Response(JSON.stringify(value), { status }); +} diff --git a/packages/provider-webdriver/src/browserstack-connection-verification.ts b/packages/provider-browserstack/src/browserstack-connection-verification.ts similarity index 92% rename from packages/provider-webdriver/src/browserstack-connection-verification.ts rename to packages/provider-browserstack/src/browserstack-connection-verification.ts index c82482204e..6578ef65ce 100644 --- a/packages/provider-webdriver/src/browserstack-connection-verification.ts +++ b/packages/provider-browserstack/src/browserstack-connection-verification.ts @@ -1,8 +1,5 @@ import path from 'node:path'; import { AppError } from '@agent-device/kernel/errors'; -import { parseBrowserStackAppReference } from './browserstack.ts'; -import { isBrowserStackAppReference } from './providers.ts'; -import { fetchProviderVerificationJson, sameOsVersion } from './webdriver-utils.ts'; import type { ProviderConnectionResource, ProviderConnectionVerification, @@ -35,7 +32,9 @@ export async function verifyBrowserStackConnection( options: BrowserStackConnectionVerificationOptions, clientVersion: string, ): Promise { - const providerApp = readBrowserStackAppOption(options.app); + const { parseBrowserStackAppReference } = await import('./browserstack.ts'); + const { sameOsVersion } = await import('@agent-device/provider-webdriver/plugin'); + const providerApp = parseBrowserStackAppReference(options.app) ?? options.app; const auth = { username: options.username, accessKey: options.accessKey }; const devices = await fetchBrowserStackJson( options.devicesEndpoint ?? BROWSERSTACK_DEVICES_ENDPOINT, @@ -76,17 +75,13 @@ export async function verifyBrowserStackConnection( }; } -/** Hand-authored remote configs reach verification without passing through connect's normalization. */ -function readBrowserStackAppOption(app: string): string { - return parseBrowserStackAppReference(app) ?? app; -} - async function verifyBrowserStackApp( app: string, options: BrowserStackConnectionVerificationOptions, auth: { username: string; accessKey: string }, clientVersion: string, ): Promise { + const { isBrowserStackAppReference } = await import('./providers.ts'); if (isBrowserStackAppReference(app)) { const apps = await fetchBrowserStackJson( options.appsEndpoint ?? BROWSERSTACK_APPS_ENDPOINT, @@ -124,6 +119,7 @@ async function fetchBrowserStackJson( auth: { username: string; accessKey: string }, clientVersion: string, ): Promise { + const { fetchProviderVerificationJson } = await import('@agent-device/provider-webdriver/plugin'); return await fetchProviderVerificationJson(endpoint, { clientVersion, auth, diff --git a/packages/provider-webdriver/src/browserstack-connection.test.ts b/packages/provider-browserstack/src/browserstack-connection.test.ts similarity index 88% rename from packages/provider-webdriver/src/browserstack-connection.test.ts rename to packages/provider-browserstack/src/browserstack-connection.test.ts index ce232c295a..648ad1efa9 100644 --- a/packages/provider-webdriver/src/browserstack-connection.test.ts +++ b/packages/provider-browserstack/src/browserstack-connection.test.ts @@ -2,14 +2,14 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; import { afterEach, test, vi } from 'vitest'; +import type { ProviderPluginHost } from 'agent-device/plugins'; import { AppError } from '@agent-device/kernel/errors'; -import { createBrowserStackConnection } from './browserstack-connection.ts'; -import { verifyBrowserStackConnection } from './connection-verification.ts'; -import type { CloudWebDriverProviderHost } from './provider-plugin.ts'; -import { mkdtempForTestSync } from './tmp-dir.fixtures.ts'; +import { createBrowserStackConnection } from './connection.ts'; +import { verifyBrowserStackConnection } from './browserstack-connection-verification.ts'; +import { mkdtempForTestSync } from '@agent-device/test-kit'; -vi.mock('./connection-verification.ts', async (importOriginal) => ({ - ...(await importOriginal()), +vi.mock('./browserstack-connection-verification.ts', async (importOriginal) => ({ + ...(await importOriginal()), verifyBrowserStackConnection: vi.fn(), })); @@ -26,13 +26,12 @@ const FLAGS = { providerApp: 'bs://app-id', }; -function host(env: Record = CREDENTIALS): CloudWebDriverProviderHost { +function host(env: Record = CREDENTIALS): ProviderPluginHost { return { env, + options: {}, clientVersion: '1.2.3', - runHostCommand: async () => { - throw new Error('BrowserStack runs no host commands'); - }, + createError: (code, message, details) => new AppError(code, message, details), }; } diff --git a/packages/provider-webdriver/src/browserstack-device-features.test.ts b/packages/provider-browserstack/src/browserstack-device-features.test.ts similarity index 100% rename from packages/provider-webdriver/src/browserstack-device-features.test.ts rename to packages/provider-browserstack/src/browserstack-device-features.test.ts diff --git a/packages/provider-webdriver/src/browserstack-device-features.ts b/packages/provider-browserstack/src/browserstack-device-features.ts similarity index 97% rename from packages/provider-webdriver/src/browserstack-device-features.ts rename to packages/provider-browserstack/src/browserstack-device-features.ts index 05995a068e..bb22da96fc 100644 --- a/packages/provider-webdriver/src/browserstack-device-features.ts +++ b/packages/provider-browserstack/src/browserstack-device-features.ts @@ -4,8 +4,8 @@ import { type CloudProviderProfileFields, } from '@agent-device/contracts/remote'; import { AppError } from '@agent-device/kernel/errors'; -import { requireProviderDeviceOrientation } from './webdriver-utils.ts'; -import type { CloudWebDriverPlatform } from './runtime.ts'; +import { requireProviderDeviceOrientation } from '@agent-device/provider-webdriver/plugin'; +import type { CloudWebDriverPlatform } from '@agent-device/provider-webdriver/plugin'; /** * BrowserStack "device feature" session capabilities. diff --git a/packages/provider-webdriver/src/browserstack-profile-fields.test.ts b/packages/provider-browserstack/src/browserstack-profile-fields.test.ts similarity index 77% rename from packages/provider-webdriver/src/browserstack-profile-fields.test.ts rename to packages/provider-browserstack/src/browserstack-profile-fields.test.ts index 0f57ca4975..0f38dffd86 100644 --- a/packages/provider-webdriver/src/browserstack-profile-fields.test.ts +++ b/packages/provider-browserstack/src/browserstack-profile-fields.test.ts @@ -1,9 +1,8 @@ import { test } from 'vitest'; import assert from 'node:assert/strict'; import type { ProviderProfileField } from '@agent-device/contracts/provider-profile-fields'; -import { BROWSERSTACK_PROFILE_FIELDS } from './browserstack.ts'; +import { BROWSERSTACK_PROFILE_FIELDS } from './profile-fields.ts'; import { BROWSERSTACK_DEVICE_FEATURE_SPECS } from './browserstack-device-features.ts'; -import { consumedProfileFields } from './profile-fields.fixtures.ts'; // Fields a hub reads directly while building its session, outside the device-feature table. const HUB_SESSION_FIELDS: readonly ProviderProfileField[] = [ @@ -17,7 +16,9 @@ const HUB_SESSION_FIELDS: readonly ProviderProfileField[] = [ // A consumed device feature with no capability row would be accepted and then dropped at the hub. test('BrowserStack consumes exactly the fields its capability builder reads', () => { assert.deepEqual( - consumedProfileFields(BROWSERSTACK_PROFILE_FIELDS), + (Object.keys(BROWSERSTACK_PROFILE_FIELDS.fields) as ProviderProfileField[]) + .filter((field) => BROWSERSTACK_PROFILE_FIELDS.fields[field] === 'consumed') + .sort(), [...HUB_SESSION_FIELDS, ...BROWSERSTACK_DEVICE_FEATURE_SPECS.map((spec) => spec.field)].sort(), ); }); diff --git a/packages/provider-webdriver/src/browserstack-provider.ts b/packages/provider-browserstack/src/browserstack-webdriver.ts similarity index 71% rename from packages/provider-webdriver/src/browserstack-provider.ts rename to packages/provider-browserstack/src/browserstack-webdriver.ts index 04548c2c79..e014ba1174 100644 --- a/packages/provider-webdriver/src/browserstack-provider.ts +++ b/packages/provider-browserstack/src/browserstack-webdriver.ts @@ -1,47 +1,34 @@ +import type { ProviderPluginHost } from 'agent-device/plugins'; +import type { WebDriverPluginOptions } from 'agent-device/plugins/webdriver'; +import { + buildCloudWebDriverBaseCapabilities, + readFlag, + requireFlag, + requireRequest, + requireRequestPlatform, +} from '@agent-device/provider-webdriver/plugin'; import { BROWSERSTACK_APP_AUTOMATE_ENDPOINT, BROWSERSTACK_APP_UPLOAD_ENDPOINT, BROWSERSTACK_CAPABILITY_OVERRIDES, - BROWSERSTACK_PROFILE_FIELDS, buildBrowserStackCapabilities, createBrowserStackUploadApp, listBrowserStackCloudArtifacts, - requireBrowserStackCredentials, resolveBrowserStackAppReference, } from './browserstack.ts'; import { buildBrowserStackDeviceFeatureCapabilities, readBrowserStackDeviceFeatureFields, } from './browserstack-device-features.ts'; -import { buildCloudWebDriverBaseCapabilities } from './capabilities.ts'; -import type { - BundledCloudWebDriverProvider, - CloudWebDriverConnection, - CloudWebDriverProviderHost, - CloudWebDriverProviderOptions, - CloudWebDriverProviderRegistration, -} from './provider-plugin.ts'; -import { CLOUD_WEBDRIVER_PROVIDERS, cloudWebDriverProviderDeclaration } from './providers.ts'; -import { - readFlag, - requireFlag, - requireRequest, - requireRequestPlatform, -} from './webdriver-utils.ts'; +import { BROWSERSTACK_PROFILE_FIELDS } from './profile-fields.ts'; +import { PROVIDER, requireBrowserStackCredentials } from './providers.ts'; -const PROVIDER = CLOUD_WEBDRIVER_PROVIDERS.browserStack; const SERVICE = 'BrowserStack'; -export const browserStackProvider: BundledCloudWebDriverProvider = { - declaration: cloudWebDriverProviderDeclaration(PROVIDER)!, - create: createBrowserStackProvider, -}; - -function createBrowserStackProvider( - host: CloudWebDriverProviderHost, -): CloudWebDriverProviderRegistration { +/** The BrowserStack WebDriver descriptor the host drives through its shared engine. */ +export function createBrowserStackWebDriver(host: ProviderPluginHost): WebDriverPluginOptions { const { env, clientVersion } = host; - const webDriver: CloudWebDriverProviderOptions = { + const webDriver: WebDriverPluginOptions = { provider: PROVIDER, profileFields: BROWSERSTACK_PROFILE_FIELDS, platform: 'android', @@ -102,11 +89,5 @@ function createBrowserStackProvider( }; }, }; - const connect = async () => - (await import('./browserstack-connection.ts')).createBrowserStackConnection(host); - const connection: CloudWebDriverConnection = { - resolve: async (context) => (await connect()).resolve(context), - verify: async (context) => await (await connect()).verify(context), - }; - return { webDriver, connection }; + return webDriver; } diff --git a/packages/provider-webdriver/src/browserstack.test.ts b/packages/provider-browserstack/src/browserstack.test.ts similarity index 99% rename from packages/provider-webdriver/src/browserstack.test.ts rename to packages/provider-browserstack/src/browserstack.test.ts index 2f77e2c4a6..cc36541656 100644 --- a/packages/provider-webdriver/src/browserstack.test.ts +++ b/packages/provider-browserstack/src/browserstack.test.ts @@ -9,7 +9,7 @@ import { resolveBrowserStackAppReference, uploadBrowserStackApp, } from './browserstack.ts'; -import { mkdtempForTest } from './tmp-dir.fixtures.ts'; +import { mkdtempForTest } from '@agent-device/test-kit'; const realFetch = globalThis.fetch; diff --git a/packages/provider-webdriver/src/browserstack.ts b/packages/provider-browserstack/src/browserstack.ts similarity index 80% rename from packages/provider-webdriver/src/browserstack.ts rename to packages/provider-browserstack/src/browserstack.ts index 4ae188a3d8..9bb5f208f1 100644 --- a/packages/provider-webdriver/src/browserstack.ts +++ b/packages/provider-browserstack/src/browserstack.ts @@ -1,64 +1,24 @@ import type { CloudArtifact, CloudArtifactsResult } from '@agent-device/contracts/observability'; -import type { ProviderProfileFieldDeclaration } from '@agent-device/contracts/provider-profile-fields'; import { AppError } from '@agent-device/kernel/errors'; -import type { CloudWebDriverCapabilityOverrides } from './capabilities.ts'; -import type { CloudWebDriverUploadApp } from './runtime.ts'; -import { cloudArtifactsReadyOrPending, urlArtifactFromDetails } from './artifact-results.ts'; -import { - BROWSERSTACK_CREDENTIAL_VARIABLES, - canonicalBrowserStackAppReference, - CLOUD_WEBDRIVER_PROVIDERS, - isBrowserStackAppReference, -} from './providers.ts'; import { appendUrlPath, appFileUploadForm, + cloudArtifactsReadyOrPending, createHubUploadApp, fetchProviderSessionDetails, postHubAppUpload, - requireEnv, resolveHubAppReference, -} from './webdriver-utils.ts'; - -export const BROWSERSTACK_PROFILE_FIELDS: ProviderProfileFieldDeclaration = { - provider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, - label: 'BrowserStack', - fields: { - providerApp: 'consumed', - providerOsVersion: 'consumed', - providerDeviceType: 'refused', - providerProject: 'consumed', - providerBuild: 'consumed', - providerSessionName: 'consumed', - providerDeviceOrientation: 'consumed', - providerGeoLocation: 'consumed', - providerTimezone: 'consumed', - providerAppiumVersion: 'consumed', - providerLanguage: 'consumed', - providerLocale: 'consumed', - providerNetworkProfile: 'consumed', - providerCustomNetwork: 'consumed', - providerNoResignApp: 'consumed', - providerNetworkLogs: 'refused', - providerNetworkHosts: 'refused', - awsProjectArn: 'refused', - awsDeviceArn: 'refused', - awsAppArn: 'refused', - awsRegion: 'refused', - awsInteractionMode: 'refused', - }, -}; - -/** The BrowserStack credentials in `env`; `consumer` names the command a missing one fails. */ -export function requireBrowserStackCredentials( - env: Readonly>, - consumer: string, -): { username: string; accessKey: string } { - return { - username: requireEnv(env, BROWSERSTACK_CREDENTIAL_VARIABLES.username, consumer), - accessKey: requireEnv(env, BROWSERSTACK_CREDENTIAL_VARIABLES.accessKey, consumer), - }; -} + urlArtifactFromDetails, +} from '@agent-device/provider-webdriver/plugin'; +import type { + CloudWebDriverCapabilityOverrides, + CloudWebDriverUploadApp, +} from '@agent-device/provider-webdriver/plugin'; +import { + PROVIDER, + canonicalBrowserStackAppReference, + isBrowserStackAppReference, +} from './providers.ts'; export const BROWSERSTACK_APP_AUTOMATE_ENDPOINT = 'https://hub-cloud.browserstack.com/wd/hub/'; export const BROWSERSTACK_APP_UPLOAD_ENDPOINT = @@ -130,7 +90,7 @@ export async function uploadBrowserStackApp( signal?.throwIfAborted(); return await postHubAppUpload( await appFileUploadForm(appPath, 'file', { - provider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, + provider: PROVIDER, service: 'BrowserStack', }), { diff --git a/packages/provider-webdriver/src/browserstack-connection.ts b/packages/provider-browserstack/src/connection.ts similarity index 71% rename from packages/provider-webdriver/src/browserstack-connection.ts rename to packages/provider-browserstack/src/connection.ts index 018b23977d..45db16fb2a 100644 --- a/packages/provider-webdriver/src/browserstack-connection.ts +++ b/packages/provider-browserstack/src/connection.ts @@ -1,40 +1,29 @@ +import type { ProviderPluginHost } from 'agent-device/plugins'; +import type { CliFlags } from '@agent-device/contracts/command'; import { rejectRefusedProviderProfileFields, requireResolvedProfilePlatform, requireResolvedProfileValue, } from '@agent-device/contracts/provider-profile-fields'; -import { - BROWSERSTACK_PROFILE_FIELDS, - parseBrowserStackAppReference, - requireBrowserStackCredentials, -} from './browserstack.ts'; -import { readBrowserStackDeviceFeatureFields } from './browserstack-device-features.ts'; -import { verifyBrowserStackConnection } from './connection-verification.ts'; -import type { - CloudWebDriverConnection, - CloudWebDriverConnectionContext, - CloudWebDriverConnectProfileResolution, - CloudWebDriverProviderHost, -} from './provider-plugin.ts'; -import { CLOUD_WEBDRIVER_PROVIDERS } from './providers.ts'; import { requireConnectFlag, requireConnectPlatform, resolveLocalAppArtifact, -} from './webdriver-utils.ts'; +} from '@agent-device/provider-webdriver/plugin'; +import { parseBrowserStackAppReference } from './browserstack.ts'; +import { readBrowserStackDeviceFeatureFields } from './browserstack-device-features.ts'; +import { BROWSERSTACK_PROFILE_FIELDS } from './profile-fields.ts'; +import { PROVIDER, requireBrowserStackCredentials } from './providers.ts'; +import { verifyBrowserStackConnection } from './browserstack-connection-verification.ts'; -const PROVIDER = CLOUD_WEBDRIVER_PROVIDERS.browserStack; const SERVICE = 'BrowserStack'; -const CONSUMER = `connect ${PROVIDER}`; /** The `connect browserstack` callbacks, loaded only when the CLI runs them. */ -export function createBrowserStackConnection(host: CloudWebDriverProviderHost): { - resolve(context: CloudWebDriverConnectionContext): CloudWebDriverConnectProfileResolution; -} & CloudWebDriverConnection { +export function createBrowserStackConnection(host: ProviderPluginHost) { return { - resolve: ({ flags, cwd }): CloudWebDriverConnectProfileResolution => { + resolve: ({ flags, cwd }: { flags: CliFlags; cwd: string }) => { rejectRefusedProviderProfileFields(flags, BROWSERSTACK_PROFILE_FIELDS); - requireBrowserStackCredentials(host.env, CONSUMER); + requireBrowserStackCredentials(host.env, `connect ${PROVIDER}`); const platform = requireConnectPlatform(flags, PROVIDER); const device = requireConnectFlag(flags.device, PROVIDER, '--device '); const providerOsVersion = requireConnectFlag( @@ -67,10 +56,10 @@ export function createBrowserStackConnection(host: CloudWebDriverProviderHost): extraFlags: { providerApp }, }; }, - verify: async ({ flags }) => + verify: async ({ flags }: { flags: CliFlags }) => await verifyBrowserStackConnection( { - ...requireBrowserStackCredentials(host.env, CONSUMER), + ...requireBrowserStackCredentials(host.env, `connect ${PROVIDER}`), platform: requireResolvedProfilePlatform(flags.platform, SERVICE), deviceName: requireResolvedProfileValue( flags.device, diff --git a/packages/provider-browserstack/src/index.test.ts b/packages/provider-browserstack/src/index.test.ts new file mode 100644 index 0000000000..1a1bf73f9a --- /dev/null +++ b/packages/provider-browserstack/src/index.test.ts @@ -0,0 +1,172 @@ +import assert from 'node:assert/strict'; +import { afterEach, test, vi } from 'vitest'; +import type { ProviderPluginHost } from 'agent-device/plugins'; +import { AppError } from '@agent-device/kernel/errors'; +import browserstack from './index.ts'; +import { verifyBrowserStackConnection } from './browserstack-connection-verification.ts'; + +vi.mock('./browserstack-connection-verification.ts', () => ({ + verifyBrowserStackConnection: vi.fn(), +})); + +const realFetch = globalThis.fetch; + +afterEach(() => { + globalThis.fetch = realFetch; + vi.clearAllMocks(); +}); + +function host(env: Record): ProviderPluginHost { + return { + env, + options: {}, + clientVersion: '0.0.0-test', + createError: (code, message, details) => new AppError(code, message, details), + }; +} + +function capturedAuthorization(): { read(): string | undefined } { + let authorization: string | undefined; + globalThis.fetch = async (_input, init) => { + authorization = new Headers(init?.headers).get('authorization') ?? undefined; + return new Response(JSON.stringify({})); + }; + return { read: () => authorization }; +} + +async function listArtifacts(plugin: ReturnType, env: Record) { + const setup = await plugin.setup(host(env)); + if (!('webDriver' in setup)) throw new Error('BrowserStack sets up a WebDriver descriptor'); + await setup.webDriver.listArtifacts!({ provider: 'browserstack', providerSessionId: 'SESSION1' }); +} + +const basic = (username: string, accessKey: string) => + `Basic ${Buffer.from(`${username}:${accessKey}`).toString('base64')}`; + +test('the plugin declares its provider, capabilities and credential variables', () => { + const plugin = browserstack(); + assert.equal(plugin.apiVersion, 2); + assert.equal(plugin.provider, 'browserstack'); + assert.deepEqual(plugin.credentials, { + variables: ['BROWSERSTACK_USERNAME', 'BROWSERSTACK_ACCESS_KEY'], + }); + assert.deepEqual(plugin.connection?.capabilities, { + leaseKind: 'direct-device-provider', + requiresAppAttachment: false, + requiresRemoteDaemon: false, + supportsArtifacts: true, + supportsDeferredAppSelection: false, + supportsDirectPortReverse: false, + usesCloudWebDriverLease: true, + }); +}); + +test('setup builds a WebDriver descriptor that reads its hub endpoint from the environment', async () => { + const setup = await browserstack().setup( + host({ + BROWSERSTACK_USERNAME: 'user', + BROWSERSTACK_ACCESS_KEY: 'key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: 'https://hub.test/wd/hub/', + }), + ); + if (!('webDriver' in setup)) throw new Error('BrowserStack sets up a WebDriver descriptor'); + assert.equal(setup.webDriver.provider, 'browserstack'); + assert.equal(setup.webDriver.endpoint, 'https://hub.test/wd/hub/'); + assert.equal(setup.webDriver.profileFields.provider, 'browserstack'); +}); + +test('the plugin declares the BrowserStack variables only when it reads credentials from the environment', () => { + assert.deepEqual(browserstack().credentials, { + variables: ['BROWSERSTACK_USERNAME', 'BROWSERSTACK_ACCESS_KEY'], + }); + assert.deepEqual(browserstack({ credentials: { username: 'u', accessKey: 'k' } }).credentials, { + variables: [], + }); +}); + +test('a credentials object missing one key still declares the variable it reads from the environment', () => { + assert.deepEqual(browserstack({ credentials: { username: 'u' } }).credentials, { + variables: ['BROWSERSTACK_ACCESS_KEY'], + }); + assert.deepEqual(browserstack({ credentials: { accessKey: 'k' } }).credentials, { + variables: ['BROWSERSTACK_USERNAME'], + }); +}); + +test('credentials passed as options replace the environment, which stays the fallback', async () => { + const captured = capturedAuthorization(); + const env = { BROWSERSTACK_USERNAME: 'env-user', BROWSERSTACK_ACCESS_KEY: 'env-key' }; + + await listArtifacts( + browserstack({ credentials: { username: 'opt-user', accessKey: 'opt-key' } }), + env, + ); + assert.equal(captured.read(), basic('opt-user', 'opt-key')); + await listArtifacts( + browserstack({ credentials: { username: 'opt-user', accessKey: 'opt-key' } }), + {}, + ); + assert.equal(captured.read(), basic('opt-user', 'opt-key')); + await listArtifacts(browserstack(), env); + assert.equal(captured.read(), basic('env-user', 'env-key')); + await assert.rejects(listArtifacts(browserstack(), {}), { code: 'INVALID_ARGS' }); +}); + +test('a credentials object missing one key falls back to the environment for that key', async () => { + const captured = capturedAuthorization(); + await listArtifacts(browserstack({ credentials: { username: 'opt-user' } }), { + BROWSERSTACK_USERNAME: 'env-user', + BROWSERSTACK_ACCESS_KEY: 'env-key', + }); + assert.equal(captured.read(), basic('opt-user', 'env-key')); +}); + +test('connect uses the option credentials without an environment and verifies with them', async () => { + vi.mocked(verifyBrowserStackConnection).mockResolvedValue({ + provider: 'browserstack', + service: 'BrowserStack', + verificationMessage: 'verified', + device: { status: 'verified', name: 'Google Pixel 8', platform: 'android', osVersion: '14.0' }, + app: { status: 'verified', reference: 'bs://app-id' }, + }); + const { connection } = browserstack({ + credentials: { username: 'opt-user', accessKey: 'opt-key' }, + }); + const flags = { + json: false, + help: false, + version: false, + platform: 'android', + device: 'Google Pixel 8', + providerOsVersion: '14.0', + providerApp: 'bs://app-id', + } as const; + + const resolved = await connection!.resolve({ + flags, + stateDir: '/state', + cwd: '/work', + env: {}, + host: host({}), + }); + assert.equal(resolved.profile.leaseProvider, 'browserstack'); + await connection!.verify({ flags, env: {}, host: host({}) }); + assert.deepEqual( + [ + vi.mocked(verifyBrowserStackConnection).mock.calls[0]?.[0].username, + vi.mocked(verifyBrowserStackConnection).mock.calls[0]?.[0].accessKey, + ], + ['opt-user', 'opt-key'], + ); + await assert.rejects( + async () => + await browserstack().connection!.resolve({ + flags, + stateDir: '/state', + cwd: '/work', + env: {}, + host: host({}), + }), + { code: 'INVALID_ARGS' }, + ); +}); diff --git a/packages/provider-browserstack/src/index.ts b/packages/provider-browserstack/src/index.ts new file mode 100644 index 0000000000..30a48debb5 --- /dev/null +++ b/packages/provider-browserstack/src/index.ts @@ -0,0 +1,61 @@ +import type { AgentDevicePlugin, ProviderPluginHost } from 'agent-device/plugins'; +import { HOSTED_WEBDRIVER_CONNECTION } from '@agent-device/provider-webdriver/providers'; + +export type BrowserStackOptions = { + /** Each supplied key replaces its environment variable; omitted keys use the environment. */ + credentials?: { username?: string; accessKey?: string }; +}; + +// The connection and WebDriver code load when they are first used, so importing the package for its +// declaration stays small. +async function loadConnection(host: ProviderPluginHost) { + return (await import('./connection.ts')).createBrowserStackConnection(host); +} + +/** + * BrowserStack as a plugin. The credentials come from `options.credentials`, with the + * `BROWSERSTACK_USERNAME` and `BROWSERSTACK_ACCESS_KEY` environment variables as the fallback for + * each key the options leave out. The plugin declares only the variables it reads from the + * environment; credentials passed as options are not part of the environment the daemon + * fingerprints. + */ +function browserstack(options: BrowserStackOptions = {}): AgentDevicePlugin { + const { credentials } = options; + const withCredentials = (host: ProviderPluginHost): ProviderPluginHost => + credentials + ? { + ...host, + // A key the caller left out falls back to the environment instead of shadowing it. + env: { + ...host.env, + ...(credentials.username ? { BROWSERSTACK_USERNAME: credentials.username } : {}), + ...(credentials.accessKey ? { BROWSERSTACK_ACCESS_KEY: credentials.accessKey } : {}), + }, + } + : host; + // Only the variables the options do not supply come from the environment, so only those are + // part of the credential fingerprint. + const environmentVariables = [ + ...(credentials?.username ? [] : ['BROWSERSTACK_USERNAME']), + ...(credentials?.accessKey ? [] : ['BROWSERSTACK_ACCESS_KEY']), + ]; + return { + apiVersion: 2, + provider: 'browserstack', + credentials: { variables: environmentVariables }, + connection: { + capabilities: { ...HOSTED_WEBDRIVER_CONNECTION }, + resolve: async (context) => + (await loadConnection(withCredentials(context.host))).resolve(context), + verify: async (context) => + await (await loadConnection(withCredentials(context.host))).verify(context), + }, + setup: async (host) => ({ + webDriver: (await import('./browserstack-webdriver.ts')).createBrowserStackWebDriver( + withCredentials(host), + ), + }), + }; +} + +export { browserstack as default }; diff --git a/packages/provider-browserstack/src/profile-fields.ts b/packages/provider-browserstack/src/profile-fields.ts new file mode 100644 index 0000000000..221ee249cd --- /dev/null +++ b/packages/provider-browserstack/src/profile-fields.ts @@ -0,0 +1,30 @@ +import type { ProviderProfileFieldDeclaration } from '@agent-device/contracts/provider-profile-fields'; + +export const BROWSERSTACK_PROFILE_FIELDS: ProviderProfileFieldDeclaration = { + provider: 'browserstack', + label: 'BrowserStack', + fields: { + providerApp: 'consumed', + providerOsVersion: 'consumed', + providerDeviceType: 'refused', + providerProject: 'consumed', + providerBuild: 'consumed', + providerSessionName: 'consumed', + providerDeviceOrientation: 'consumed', + providerGeoLocation: 'consumed', + providerTimezone: 'consumed', + providerAppiumVersion: 'consumed', + providerLanguage: 'consumed', + providerLocale: 'consumed', + providerNetworkProfile: 'consumed', + providerCustomNetwork: 'consumed', + providerNoResignApp: 'consumed', + providerNetworkLogs: 'refused', + providerNetworkHosts: 'refused', + awsProjectArn: 'refused', + awsDeviceArn: 'refused', + awsAppArn: 'refused', + awsRegion: 'refused', + awsInteractionMode: 'refused', + }, +}; diff --git a/packages/provider-browserstack/src/providers.ts b/packages/provider-browserstack/src/providers.ts new file mode 100644 index 0000000000..3a6737129d --- /dev/null +++ b/packages/provider-browserstack/src/providers.ts @@ -0,0 +1,29 @@ +import { requireEnv } from '@agent-device/provider-webdriver/plugin'; +import { canonicalSchemeReference } from '@agent-device/provider-webdriver/providers'; + +/** The provider id the registry, connection profiles, and `connect browserstack` use. */ +export const PROVIDER = 'browserstack'; + +/** The environment variables that hold BrowserStack credentials. */ +const BROWSERSTACK_CREDENTIAL_VARIABLES = { + username: 'BROWSERSTACK_USERNAME', + accessKey: 'BROWSERSTACK_ACCESS_KEY', +} as const; + +export function requireBrowserStackCredentials( + env: Readonly>, + providerLabel: string, +): { username: string; accessKey: string } { + return { + username: requireEnv(env, BROWSERSTACK_CREDENTIAL_VARIABLES.username, providerLabel), + accessKey: requireEnv(env, BROWSERSTACK_CREDENTIAL_VARIABLES.accessKey, providerLabel), + }; +} + +export function isBrowserStackAppReference(reference: string): boolean { + return /^bs:\/\/[\w.-]+$/.test(reference); +} + +export function canonicalBrowserStackAppReference(app: string): string | undefined { + return canonicalSchemeReference(app, 'bs://'); +} diff --git a/packages/provider-browserstack/test/package-smoke.mjs b/packages/provider-browserstack/test/package-smoke.mjs new file mode 100644 index 0000000000..d114c86259 --- /dev/null +++ b/packages/provider-browserstack/test/package-smoke.mjs @@ -0,0 +1,30 @@ +export const provider = 'browserstack'; +export const additionalExports = { + './connection-verification': { import: './dist/connection-verification.mjs' }, + './package.json': './package.json', +}; +export const args = [ + '--platform', + 'android', + '--device', + 'Google Pixel 8', + '--provider-os-version', + '14.0', + '--provider-app', + 'bs://app-id', +]; +export function environment() { + return { BROWSERSTACK_USERNAME: 'user', BROWSERSTACK_ACCESS_KEY: 'key' }; +} +export function respond(url, rejectCredentials) { + const pathname = new URL(url, 'http://fixture').pathname; + if (!['/app-automate/devices.json', '/app-automate/recent_apps'].includes(pathname)) { + return { status: 404, body: { error: 'not-found' } }; + } + if (rejectCredentials) return { status: 401, body: { error: 'unauthorized' } }; + return pathname === '/app-automate/devices.json' + ? { body: [{ os: 'android', os_version: '14.0', device: 'Google Pixel 8', realMobile: true }] } + : { body: [{ app_name: 'app.apk', app_version: '1.0', app_url: 'bs://app-id' }] }; +} + +export const fetchRedirects = ['https://api-cloud.browserstack.com']; diff --git a/packages/provider-browserstack/tsconfig.json b/packages/provider-browserstack/tsconfig.json new file mode 100644 index 0000000000..dacac6776d --- /dev/null +++ b/packages/provider-browserstack/tsconfig.json @@ -0,0 +1,34 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "composite": true, + "noEmit": false, + "emitDeclarationOnly": true, + "declaration": true, + "declarationDir": "./dist-types", + "tsBuildInfoFile": "./dist-types/index.tsbuildinfo", + "rootDir": ".", + "paths": { + "agent-device/plugins": ["./node_modules/agent-device/src/sdk/plugins.ts"], + "agent-device/plugins/webdriver": ["./node_modules/agent-device/src/sdk/plugin-webdriver.ts"] + } + }, + "include": ["src"], + "references": [ + { + "path": "../build-config" + }, + { + "path": "../contracts" + }, + { + "path": "../kernel" + }, + { + "path": "../provider-webdriver" + }, + { + "path": "../test-kit" + } + ] +} diff --git a/packages/provider-browserstack/tsdown.config.ts b/packages/provider-browserstack/tsdown.config.ts new file mode 100644 index 0000000000..b223adde00 --- /dev/null +++ b/packages/provider-browserstack/tsdown.config.ts @@ -0,0 +1,10 @@ +import { defineConfig } from 'tsdown'; +import { providerPluginBuildConfig } from '@agent-device/build-config'; + +export default defineConfig({ + ...providerPluginBuildConfig, + entry: { + 'agent-device': 'src/index.ts', + 'connection-verification': 'src/browserstack-connection-verification.ts', + }, +}); diff --git a/packages/provider-revyl/package.json b/packages/provider-revyl/package.json index a17e04067a..e50a9c4cb3 100644 --- a/packages/provider-revyl/package.json +++ b/packages/provider-revyl/package.json @@ -28,7 +28,8 @@ "@agent-device/provision-kit": "workspace:*", "@agent-device/provider-webdriver": "workspace:*", "@agent-device/test-kit": "workspace:*", - "agent-device": "workspace:*" + "agent-device": "workspace:*", + "@agent-device/build-config": "workspace:*" }, "publishConfig": { "exports": { diff --git a/packages/provider-revyl/tsconfig.json b/packages/provider-revyl/tsconfig.json index 71c7fd8f75..f66af48034 100644 --- a/packages/provider-revyl/tsconfig.json +++ b/packages/provider-revyl/tsconfig.json @@ -15,6 +15,9 @@ }, "include": ["src"], "references": [ + { + "path": "../build-config" + }, { "path": "../capture-kit" }, diff --git a/packages/provider-revyl/tsdown.config.ts b/packages/provider-revyl/tsdown.config.ts index b0e02a7587..ff5b303a0c 100644 --- a/packages/provider-revyl/tsdown.config.ts +++ b/packages/provider-revyl/tsdown.config.ts @@ -1,19 +1 @@ -import { defineConfig } from 'tsdown'; - -export default defineConfig({ - entry: { 'agent-device': 'src/index.ts' }, - outDir: 'dist', - format: 'esm', - platform: 'node', - target: 'es2022', - minify: true, - dts: false, - hash: false, - deps: { alwaysBundle: [/^@agent-device\//] }, - inputOptions: { - onLog(level, log, handler) { - if (log.code === 'UNRESOLVED_IMPORT') throw new Error(log.message); - handler(level, log); - }, - }, -}); +export { providerPluginBuildConfig as default } from '@agent-device/build-config'; diff --git a/packages/provider-testmu/package.json b/packages/provider-testmu/package.json index 5a9a740597..156620b759 100644 --- a/packages/provider-testmu/package.json +++ b/packages/provider-testmu/package.json @@ -29,7 +29,8 @@ "@agent-device/contracts": "workspace:*", "@agent-device/kernel": "workspace:*", "@agent-device/provider-webdriver": "workspace:*", - "agent-device": "workspace:*" + "agent-device": "workspace:*", + "@agent-device/build-config": "workspace:*" }, "publishConfig": { "exports": { diff --git a/packages/provider-testmu/tsconfig.json b/packages/provider-testmu/tsconfig.json index 81ccf03333..0a5a37e397 100644 --- a/packages/provider-testmu/tsconfig.json +++ b/packages/provider-testmu/tsconfig.json @@ -15,6 +15,9 @@ }, "include": ["src"], "references": [ + { + "path": "../build-config" + }, { "path": "../contracts" }, diff --git a/packages/provider-testmu/tsdown.config.ts b/packages/provider-testmu/tsdown.config.ts index b0e02a7587..ff5b303a0c 100644 --- a/packages/provider-testmu/tsdown.config.ts +++ b/packages/provider-testmu/tsdown.config.ts @@ -1,19 +1 @@ -import { defineConfig } from 'tsdown'; - -export default defineConfig({ - entry: { 'agent-device': 'src/index.ts' }, - outDir: 'dist', - format: 'esm', - platform: 'node', - target: 'es2022', - minify: true, - dts: false, - hash: false, - deps: { alwaysBundle: [/^@agent-device\//] }, - inputOptions: { - onLog(level, log, handler) { - if (log.code === 'UNRESOLVED_IMPORT') throw new Error(log.message); - handler(level, log); - }, - }, -}); +export { providerPluginBuildConfig as default } from '@agent-device/build-config'; diff --git a/packages/provider-webdriver/package.json b/packages/provider-webdriver/package.json index b5ed3a1528..ddb52520ce 100644 --- a/packages/provider-webdriver/package.json +++ b/packages/provider-webdriver/package.json @@ -3,7 +3,7 @@ "version": "0.0.0", "private": true, "type": "module", - "description": "BrowserStack and AWS Device Farm WebDriver providers for agent-device. Internal workspace package bundled into the published artifact.", + "description": "AWS Device Farm WebDriver provider for agent-device. Internal workspace package bundled into the published artifact.", "dependencies": { "@agent-device/capture-kit": "workspace:*", "@agent-device/contracts": "workspace:*", diff --git a/packages/provider-webdriver/src/browserstack-provider.test.ts b/packages/provider-webdriver/src/browserstack-provider.test.ts deleted file mode 100644 index cfbff96988..0000000000 --- a/packages/provider-webdriver/src/browserstack-provider.test.ts +++ /dev/null @@ -1,46 +0,0 @@ -import assert from 'node:assert/strict'; -import { test } from 'vitest'; -import { browserStackProvider } from './browserstack-provider.ts'; -import type { CloudWebDriverProviderHost } from './provider-plugin.ts'; - -const HOST: CloudWebDriverProviderHost = { - env: { - BROWSERSTACK_USERNAME: 'user', - BROWSERSTACK_ACCESS_KEY: 'key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: 'https://hub.test/wd/hub/', - }, - clientVersion: '1.2.3', - runHostCommand: async () => { - throw new Error('BrowserStack runs no host commands'); - }, -}; - -test('the declaration reserves the provider id and names the credential variables', () => { - assert.equal(browserStackProvider.declaration.provider, 'browserstack'); - assert.deepEqual(browserStackProvider.declaration.credentialVariables, [ - 'BROWSERSTACK_USERNAME', - 'BROWSERSTACK_ACCESS_KEY', - ]); - assert.equal(browserStackProvider.declaration.connection.usesCloudWebDriverLease, true); -}); - -test('the factory reads its hub endpoint from the environment and connects through the lazy callbacks', async () => { - const { webDriver, connection } = browserStackProvider.create(HOST); - assert.equal(webDriver.provider, 'browserstack'); - assert.equal(webDriver.endpoint, 'https://hub.test/wd/hub/'); - assert.equal(webDriver.profileFields.provider, 'browserstack'); - const { profile } = await connection.resolve({ - flags: { - json: false, - help: false, - version: false, - platform: 'ios', - device: 'iPhone 16', - providerOsVersion: '18.0', - providerApp: 'bs://app-id', - }, - cwd: '/', - }); - assert.equal(profile.leaseProvider, 'browserstack'); - assert.equal(profile.device, 'iPhone 16'); -}); diff --git a/packages/provider-webdriver/src/connection-verification.test.ts b/packages/provider-webdriver/src/connection-verification.test.ts index 2e831f9858..cea3f28095 100644 --- a/packages/provider-webdriver/src/connection-verification.test.ts +++ b/packages/provider-webdriver/src/connection-verification.test.ts @@ -1,23 +1,8 @@ import assert from 'node:assert/strict'; import { afterEach, test, vi } from 'vitest'; -import { AppError } from '@agent-device/kernel/errors'; -import { - verifyAwsDeviceFarmConnection, - verifyBrowserStackConnection, -} from './connection-verification.ts'; +import { verifyAwsDeviceFarmConnection } from './connection-verification.ts'; import type { RunHostCommand } from './dependencies.ts'; -const CLIENT_VERSION = '1.2.3'; - -const browserStackOptions = { - username: 'browser-user', - accessKey: 'browser-key', - platform: 'android' as const, - deviceName: 'Google Pixel 8', - osVersion: '14.0', - app: 'bs://app-id', -}; - const awsResources = { project: { arn: 'project-arn', name: 'Agent Device' }, device: { @@ -37,191 +22,6 @@ const awsResources = { afterEach(() => vi.unstubAllGlobals()); -test('BrowserStack verifies the selected resources without creating a session', async () => { - const fetchMock = vi.fn(async (input) => - String(input).includes('devices') - ? jsonResponse([ - { os: 'android', os_version: '14.0', device: 'Google Pixel 8', realMobile: true }, - ]) - : jsonResponse([{ app_name: 'sample.apk', app_version: '1.2.3', app_url: 'bs://app-id' }]), - ); - vi.stubGlobal('fetch', fetchMock); - - const result = await verifyBrowserStackConnection( - { - ...browserStackOptions, - devicesEndpoint: 'https://browserstack.test/devices', - appsEndpoint: 'https://browserstack.test/apps', - }, - CLIENT_VERSION, - ); - - assert.equal(result.provider, 'browserstack'); - assert.deepEqual(result.device, { - status: 'verified', - name: 'Google Pixel 8', - platform: 'android', - osVersion: '14.0', - }); - assert.deepEqual(result.app, { - status: 'verified', - name: 'sample.apk', - reference: 'bs://app-id', - version: '1.2.3', - }); - assert.deepEqual( - fetchMock.mock.calls.map(([input]) => String(input)), - ['https://browserstack.test/devices', 'https://browserstack.test/apps'], - ); -}); - -test('BrowserStack classifies rejected credentials without exposing them', async () => { - vi.stubGlobal( - 'fetch', - vi.fn(async () => jsonResponse({}, 401)), - ); - - await assert.rejects( - verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), - (error: unknown) => { - assert.equal((error as { code?: string }).code, 'UNAUTHORIZED'); - assert.doesNotMatch(JSON.stringify(error), /browser-key/); - return true; - }, - ); -}); - -test('BrowserStack points HTTP failures at its service status and transport failures at the network', async () => { - vi.stubGlobal( - 'fetch', - vi.fn(async () => jsonResponse({}, 503)), - ); - await assert.rejects( - verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), - (error: unknown) => { - assert.equal((error as { code?: string }).code, 'COMMAND_FAILED'); - assert.equal( - (error as { details?: { hint?: string } }).details?.hint, - 'Retry connect or check the BrowserStack service status.', - ); - return true; - }, - ); - - vi.stubGlobal( - 'fetch', - vi.fn(async () => { - throw new TypeError('fetch failed'); - }), - ); - await assert.rejects( - verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), - (error: unknown) => { - assert.equal((error as { code?: string }).code, 'COMMAND_FAILED'); - assert.equal( - (error as { details?: { hint?: string } }).details?.hint, - 'Check network access to api-cloud.browserstack.com and retry connect.', - ); - return true; - }, - ); -}); - -test('BrowserStack reports a non-JSON verification answer typed, with its status', async () => { - vi.stubGlobal( - 'fetch', - vi.fn(async () => new Response('maintenance', { status: 200 })), - ); - - await assert.rejects( - verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION), - (error: unknown) => { - assert.ok(error instanceof AppError); - assert.equal(error.code, 'COMMAND_FAILED'); - assert.equal(error.message, 'BrowserStack connection verification answer was not JSON.'); - assert.equal(error.details?.status, 200); - assert.equal(error.details?.hint, 'Retry connect or check the BrowserStack service status.'); - return true; - }, - ); -}); - -test('BrowserStack verification canonicalizes the bs:// scheme and refuses an id outside its grammar', async () => { - const fetchMock = vi.fn(async (input) => - String(input).includes('devices') - ? jsonResponse([{ os: 'android', os_version: '14.0', device: 'Google Pixel 8' }]) - : jsonResponse([{ app_name: 'sample.apk', app_url: 'bs://app-id' }]), - ); - vi.stubGlobal('fetch', fetchMock); - - const result = await verifyBrowserStackConnection( - { - ...browserStackOptions, - app: 'BS://app-id', - }, - CLIENT_VERSION, - ); - assert.deepEqual(result.app, { - status: 'verified', - name: 'sample.apk', - reference: 'bs://app-id', - }); - - fetchMock.mockClear(); - await assert.rejects( - verifyBrowserStackConnection({ ...browserStackOptions, app: 'bs://a b' }, CLIENT_VERSION), - (error: unknown) => { - assert.ok(error instanceof AppError); - assert.equal(error.code, 'INVALID_ARGS'); - assert.equal(error.message, 'BrowserStack --provider-app bs://a b is not a bs:// app id.'); - assert.deepEqual(error.details, { - providerApp: 'bs://a b', - hint: 'Pass .', - }); - return true; - }, - ); - assert.equal(fetchMock.mock.calls.length, 0); -}); - -test('BrowserStack defers a bs app reference outside the recent upload window', async () => { - vi.stubGlobal( - 'fetch', - vi.fn(async (input) => - String(input).includes('devices') - ? jsonResponse([{ os: 'android', os_version: '14', device: 'Google Pixel 8' }]) - : jsonResponse([]), - ), - ); - - const result = await verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION); - - assert.deepEqual(result.app, { - status: 'configured', - reference: 'bs://app-id', - message: - 'App reference was not found in the 100 most recent uploads; BrowserStack validates it when creating the session.', - }); - assert.match( - result.verificationMessage, - /app availability is checked when the session is created/, - ); -}); - -test('BrowserStack accepts an empty-object recent apps response', async () => { - vi.stubGlobal( - 'fetch', - vi.fn(async (input) => - String(input).includes('devices') - ? jsonResponse([{ os: 'android', os_version: '14', device: 'Google Pixel 8' }]) - : jsonResponse({}), - ), - ); - - const result = await verifyBrowserStackConnection(browserStackOptions, CLIENT_VERSION); - assert.equal(result.app.status, 'configured'); -}); - test('AWS Device Farm verifies resources without creating a remote access session', async () => { const concurrency = { active: 0, max: 0 }; const runHostCommand = createAwsRunner(awsResources, concurrency); @@ -313,7 +113,3 @@ function createAwsRunner( } }); } - -function jsonResponse(value: unknown, status = 200): Response { - return new Response(JSON.stringify(value), { status }); -} diff --git a/packages/provider-webdriver/src/connection-verification.ts b/packages/provider-webdriver/src/connection-verification.ts index 6d9d6dd90e..6e3b5f596d 100644 --- a/packages/provider-webdriver/src/connection-verification.ts +++ b/packages/provider-webdriver/src/connection-verification.ts @@ -3,5 +3,4 @@ * so a host can substitute every bundled verifier together, the way a plugin's own * `connection-verification` subpath is substituted. */ -export { verifyBrowserStackConnection } from './browserstack-connection-verification.ts'; export { verifyAwsDeviceFarmConnection } from './aws-device-farm-connection-verification.ts'; diff --git a/packages/provider-webdriver/src/index.ts b/packages/provider-webdriver/src/index.ts index f284472929..c0e7ea7518 100644 --- a/packages/provider-webdriver/src/index.ts +++ b/packages/provider-webdriver/src/index.ts @@ -1,5 +1,4 @@ import { awsDeviceFarmProvider } from './aws-device-farm-provider.ts'; -import { browserStackProvider } from './browserstack-provider.ts'; import type { BundledCloudWebDriverProvider } from './provider-plugin.ts'; export type { RunHostCommand } from './dependencies.ts'; @@ -14,7 +13,7 @@ export type { * returns, so moving one out of the bundle is a packaging change, not a provider rewrite. */ export const BUNDLED_CLOUD_WEBDRIVER_PROVIDERS: readonly BundledCloudWebDriverProvider[] = - Object.freeze([browserStackProvider, awsDeviceFarmProvider]); + Object.freeze([awsDeviceFarmProvider]); export function bundledCloudWebDriverProvider( provider: string | undefined, diff --git a/packages/provider-webdriver/src/platform-runtime.test.ts b/packages/provider-webdriver/src/platform-runtime.test.ts index 21d5603747..bc5778a0c9 100644 --- a/packages/provider-webdriver/src/platform-runtime.test.ts +++ b/packages/provider-webdriver/src/platform-runtime.test.ts @@ -16,7 +16,7 @@ import { CLOUD_WEBDRIVER_PROVIDERS } from './providers.ts'; function capabilities( platform: CloudWebDriverPlatform = 'android', overrides?: CloudWebDriverCapabilityOverrides, - provider: string = CLOUD_WEBDRIVER_PROVIDERS.browserStack, + provider: string = CLOUD_WEBDRIVER_PROVIDERS.awsDeviceFarm, ) { return createCloudWebDriverCapabilities({ provider, diff --git a/packages/provider-webdriver/src/plugin.ts b/packages/provider-webdriver/src/plugin.ts index 3d9faadfcd..2f0fc5996e 100644 --- a/packages/provider-webdriver/src/plugin.ts +++ b/packages/provider-webdriver/src/plugin.ts @@ -12,6 +12,7 @@ export type { CloudWebDriverUploadApp, } from './runtime.ts'; export type { CloudWebDriverProviderOptions } from './provider-plugin.ts'; +export type { CloudWebDriverCapabilityOverrides } from './capabilities.ts'; export { appFileUploadForm, appendUrlPath, @@ -32,3 +33,4 @@ export { } from './webdriver-utils.ts'; export { cloudArtifactsReadyOrPending, urlArtifactFromDetails } from './artifact-results.ts'; export { buildCloudWebDriverBaseCapabilities } from './capabilities.ts'; +export { sameOsVersion } from './webdriver-utils.ts'; diff --git a/packages/provider-webdriver/src/providers.ts b/packages/provider-webdriver/src/providers.ts index 7768dd8e3a..d7495d657b 100644 --- a/packages/provider-webdriver/src/providers.ts +++ b/packages/provider-webdriver/src/providers.ts @@ -1,19 +1,12 @@ import type { ConnectionProviderCapabilities } from '@agent-device/contracts/remote'; export const CLOUD_WEBDRIVER_PROVIDERS = { - browserStack: 'browserstack', awsDeviceFarm: 'aws-device-farm', } as const; export type CloudWebDriverKnownProviderName = (typeof CLOUD_WEBDRIVER_PROVIDERS)[keyof typeof CLOUD_WEBDRIVER_PROVIDERS]; -/** The environment variables that hold BrowserStack credentials. */ -export const BROWSERSTACK_CREDENTIAL_VARIABLES = { - username: 'BROWSERSTACK_USERNAME', - accessKey: 'BROWSERSTACK_ACCESS_KEY', -} as const; - /** * What a bundled provider declares before any of its code runs: the same fields an installed * plugin returns from its factory. Connect policy and the credential fingerprint read this, never @@ -26,7 +19,7 @@ export type CloudWebDriverProviderDeclaration = Readonly<{ credentialVariables?: readonly string[]; }>; -const HOSTED_WEBDRIVER_CONNECTION: ConnectionProviderCapabilities = { +export const HOSTED_WEBDRIVER_CONNECTION: ConnectionProviderCapabilities = { leaseKind: 'direct-device-provider', requiresAppAttachment: false, requiresRemoteDaemon: false, @@ -38,11 +31,6 @@ const HOSTED_WEBDRIVER_CONNECTION: ConnectionProviderCapabilities = { export const CLOUD_WEBDRIVER_PROVIDER_DECLARATIONS: readonly CloudWebDriverProviderDeclaration[] = Object.freeze([ - { - provider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, - connection: HOSTED_WEBDRIVER_CONNECTION, - credentialVariables: Object.values(BROWSERSTACK_CREDENTIAL_VARIABLES), - }, { // AWS Device Farm reads the AWS CLI credential chain, which no environment hash identifies. provider: CLOUD_WEBDRIVER_PROVIDERS.awsDeviceFarm, @@ -58,8 +46,6 @@ export function cloudWebDriverProviderDeclaration( ); } -const BROWSERSTACK_APP_SCHEME = 'bs://'; - /** * URI schemes are case-insensitive, but hosted hubs only match the lower-case spelling, so * `BS://id` is returned as `bs://id`. Anything without the lower-case `scheme` returns undefined. @@ -68,12 +54,3 @@ export function canonicalSchemeReference(app: string, scheme: string): string | if (app.slice(0, scheme.length).toLowerCase() !== scheme) return undefined; return `${scheme}${app.slice(scheme.length)}`; } - -export function canonicalBrowserStackAppReference(app: string): string | undefined { - return canonicalSchemeReference(app, BROWSERSTACK_APP_SCHEME); -} - -/** An id outside this grammar would pass every local check and fail only at session creation. */ -export function isBrowserStackAppReference(reference: string): boolean { - return /^bs:\/\/[\w.-]+$/.test(reference); -} diff --git a/packages/provider-webdriver/src/runtime-deployment.test.ts b/packages/provider-webdriver/src/runtime-deployment.test.ts index ce8b5f4c93..80c06e8b60 100644 --- a/packages/provider-webdriver/src/runtime-deployment.test.ts +++ b/packages/provider-webdriver/src/runtime-deployment.test.ts @@ -3,8 +3,8 @@ import path from 'node:path'; import { afterEach, expect, test, vi } from 'vitest'; import { createCloudWebDriverCapabilities } from './capabilities.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; -import { createBrowserStackUploadApp } from './browserstack.ts'; import { mkdtempForTest } from './tmp-dir.fixtures.ts'; +import { appFileUploadForm, createHubUploadApp } from './webdriver-utils.ts'; import { createWebDriverDeploymentRuntime } from './runtime-deployment.ts'; import type { WebDriverProviderSession } from './runtime-session.ts'; import type { CloudWebDriverUploadApp } from './runtime.ts'; @@ -134,12 +134,13 @@ test('a hosted upload refuses a directory typed before any upload request', asyn globalThis.fetch = fetchSpy; const installApp = vi.fn(async () => undefined); const deployment = createWebDriverDeploymentRuntime({ - provider: 'browserstack', - uploadApp: createBrowserStackUploadApp({ - clientVersion: '0.0.0-test', - username: 'user', - accessKey: 'key', - endpoint: 'https://upload.example.test/app', + provider: 'webdriver-test', + uploadApp: createHubUploadApp(async (appPath) => { + await appFileUploadForm(appPath, 'file', { + provider: 'webdriver-test', + service: 'Hub', + }); + return 'hub://uploaded'; }), findSessionForDevice: () => activeSession(installApp), }); @@ -152,8 +153,8 @@ test('a hosted upload refuses a directory typed before any upload request', asyn ), ).rejects.toMatchObject({ code: 'INVALID_ARGS', - message: `BrowserStack can only upload a regular app file: ${installablePath}`, - details: expect.objectContaining({ provider: 'browserstack' }), + message: `Hub can only upload a regular app file: ${installablePath}`, + details: expect.objectContaining({ provider: 'webdriver-test' }), }); expect(fetchSpy).not.toHaveBeenCalled(); expect(installApp).not.toHaveBeenCalled(); diff --git a/packages/proxy/package.json b/packages/proxy/package.json index 2652debc04..ed15c4118e 100644 --- a/packages/proxy/package.json +++ b/packages/proxy/package.json @@ -31,7 +31,8 @@ "devDependencies": { "@agent-device/contracts": "workspace:*", "@agent-device/host-kit": "workspace:*", - "@agent-device/kernel": "workspace:*" + "@agent-device/kernel": "workspace:*", + "@agent-device/build-config": "workspace:*" }, "publishConfig": { "exports": { diff --git a/packages/proxy/tsconfig.json b/packages/proxy/tsconfig.json index 247a915b90..a504c0acb5 100644 --- a/packages/proxy/tsconfig.json +++ b/packages/proxy/tsconfig.json @@ -10,5 +10,18 @@ "tsBuildInfoFile": "./dist-types/index.tsbuildinfo" }, "include": ["src"], - "references": [{ "path": "../contracts" }, { "path": "../host-kit" }, { "path": "../kernel" }] + "references": [ + { + "path": "../build-config" + }, + { + "path": "../contracts" + }, + { + "path": "../host-kit" + }, + { + "path": "../kernel" + } + ] } diff --git a/packages/proxy/tsdown.config.ts b/packages/proxy/tsdown.config.ts index 2b4fe28c98..67dedb454d 100644 --- a/packages/proxy/tsdown.config.ts +++ b/packages/proxy/tsdown.config.ts @@ -1,4 +1,5 @@ import { defineConfig } from 'tsdown'; +import { strictBundlerInputOptions } from '@agent-device/build-config'; const typeScriptPackageJsonUrl = import.meta.resolve('typescript/package.json'); const { default: getTypeScript7ExePath } = await import( @@ -15,10 +16,5 @@ export default defineConfig({ dts: { tsgo: { path: getTypeScript7ExePath() } }, hash: false, deps: { alwaysBundle: [/^@agent-device\//] }, - inputOptions: { - onLog(level, log, handler) { - if (log.code === 'UNRESOLVED_IMPORT') throw new Error(log.message); - handler(level, log); - }, - }, + inputOptions: strictBundlerInputOptions, }); diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b1758d1df3..49b3654f5a 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -29,6 +29,12 @@ importers: '@agent-device/apple-runner': specifier: workspace:* version: link:packages/apple-runner + '@agent-device/browserstack': + specifier: workspace:* + version: link:packages/provider-browserstack + '@agent-device/build-config': + specifier: workspace:* + version: link:packages/build-config '@agent-device/capture-kit': specifier: workspace:* version: link:packages/capture-kit @@ -307,6 +313,12 @@ importers: specifier: workspace:* version: link:../test-kit + packages/build-config: + devDependencies: + rolldown: + specifier: 1.2.5 + version: 1.2.5 + packages/capture-kit: dependencies: '@agent-device/contracts': @@ -861,6 +873,27 @@ importers: specifier: workspace:* version: link:../test-kit + packages/provider-browserstack: + devDependencies: + '@agent-device/build-config': + specifier: workspace:* + version: link:../build-config + '@agent-device/contracts': + specifier: workspace:* + version: link:../contracts + '@agent-device/kernel': + specifier: workspace:* + version: link:../kernel + '@agent-device/provider-webdriver': + specifier: workspace:* + version: link:../provider-webdriver + '@agent-device/test-kit': + specifier: workspace:* + version: link:../test-kit + agent-device: + specifier: workspace:* + version: link:../.. + packages/provider-limrun: dependencies: '@agent-device/capture-kit': @@ -888,6 +921,9 @@ importers: packages/provider-revyl: devDependencies: + '@agent-device/build-config': + specifier: workspace:* + version: link:../build-config '@agent-device/capture-kit': specifier: workspace:* version: link:../capture-kit @@ -912,6 +948,9 @@ importers: packages/provider-testmu: devDependencies: + '@agent-device/build-config': + specifier: workspace:* + version: link:../build-config '@agent-device/contracts': specifier: workspace:* version: link:../contracts @@ -1004,6 +1043,9 @@ importers: packages/proxy: devDependencies: + '@agent-device/build-config': + specifier: workspace:* + version: link:../build-config '@agent-device/contracts': specifier: workspace:* version: link:../contracts diff --git a/scripts/__tests__/help-conformance-sample-producers.ts b/scripts/__tests__/help-conformance-sample-producers.ts index 75e3df243b..6cc0c78469 100644 --- a/scripts/__tests__/help-conformance-sample-producers.ts +++ b/scripts/__tests__/help-conformance-sample-producers.ts @@ -1,5 +1,11 @@ import type { CapturedSample } from '../help-conformance-sample-outputs.mjs'; -import { withCapturedStderrAsync } from '@agent-device/test-kit'; +import { + withCapturedStderrAsync, + pluginHome, + selectV2Plugin, + restoreEnv, +} from '@agent-device/test-kit'; +import { primePluginConnections } from '@agent-device/plugins/connection'; import { AMBIGUOUS_MATCH_SAMPLE, APP_NOT_INSTALLED_SAMPLE, @@ -449,40 +455,54 @@ export const SAMPLE_PRODUCERS: SampleProducer[] = [ name: 'BROWSERSTACK_CONNECT_SAMPLE', producer: 'the connect success renderer with verified BrowserStack readiness', sample: BROWSERSTACK_CONNECT_SAMPLE, - render: () => { - const state = { - version: 1, - session: 'adc-browserstack', - tenant: 'direct-browserstack', - runId: 'run-browserstack', - leaseProvider: 'browserstack', - platform: 'android', - remoteConfigPath: '/tmp/browserstack.json', - remoteConfigHash: 'fixture', - connectedAt: '2026-08-03T00:00:00.000Z', - updatedAt: '2026-08-03T00:00:00.000Z', - } satisfies RemoteConnectionState; - const facts = { - provider: 'browserstack', - service: 'BrowserStack', - verificationMessage: 'Credentials, device, and uploaded app verified.', - device: { - status: 'verified', - name: 'Google Pixel 8', + render: async () => { + const { home } = pluginHome(); + selectV2Plugin( + home, + '@agent-device/browserstack', + `import browserstack from ${JSON.stringify(import.meta.resolve('@agent-device/browserstack'))}; export default browserstack;`, + { selectionOptions: {} }, + ); + const previousHome = process.env.AGENT_DEVICE_HOME; + process.env.AGENT_DEVICE_HOME = home; + try { + await primePluginConnections(process.env); + const state = { + version: 1, + session: 'adc-browserstack', + tenant: 'direct-browserstack', + runId: 'run-browserstack', + leaseProvider: 'browserstack', platform: 'android', - osVersion: '14.0', - }, - app: { - status: 'verified', - name: 'sample.apk', - reference: 'bs://app-id', - version: '1.2.3', - }, - } satisfies ConnectVerification; - return renderConnectSuccess({ - state, - readiness: presentConnectReadiness(state, facts), - }); + remoteConfigPath: '/tmp/browserstack.json', + remoteConfigHash: 'fixture', + connectedAt: '2026-08-03T00:00:00.000Z', + updatedAt: '2026-08-03T00:00:00.000Z', + } satisfies RemoteConnectionState; + const facts = { + provider: 'browserstack', + service: 'BrowserStack', + verificationMessage: 'Credentials, device, and uploaded app verified.', + device: { + status: 'verified', + name: 'Google Pixel 8', + platform: 'android', + osVersion: '14.0', + }, + app: { + status: 'verified', + name: 'sample.apk', + reference: 'bs://app-id', + version: '1.2.3', + }, + } satisfies ConnectVerification; + return renderConnectSuccess({ + state, + readiness: presentConnectReadiness(state, facts), + }); + } finally { + restoreEnv('AGENT_DEVICE_HOME', previousHome); + } }, }, ]; diff --git a/scripts/capability-matrix/collect.ts b/scripts/capability-matrix/collect.ts index 2752911eef..dd96fab271 100644 --- a/scripts/capability-matrix/collect.ts +++ b/scripts/capability-matrix/collect.ts @@ -21,6 +21,7 @@ import { createCloudWebDriverRuntime } from '@agent-device/provider-webdriver/pl import { CLOUD_WEBDRIVER_PROVIDERS } from '@agent-device/provider-webdriver/providers'; import type { RunHostCommand } from '@agent-device/provider-webdriver'; import testmuPlugin from '@agent-device/testmu'; +import browserstackPlugin from '@agent-device/browserstack'; import revylPlugin from '@agent-device/revyl'; import type { DeviceLease, ProviderDeviceRuntime } from '@agent-device/contracts/device'; import type { @@ -113,20 +114,26 @@ async function loadLocalRuntimes(host: PlatformRuntimeHost): Promise> = { - [CLOUD_WEBDRIVER_PROVIDERS.browserStack]: 'browserstack', [CLOUD_WEBDRIVER_PROVIDERS.awsDeviceFarm]: 'aws-device-farm', }; +/** The plugin packages whose factory setup() builds the WebDriver the matrix asks for. */ +const CLOUD_WEBDRIVER_PLUGINS: Readonly> = { + testmu: testmuPlugin, + browserstack: browserstackPlugin, +}; + /** The provider's WebDriver options, from the bundled registration or the plugin package. */ async function cloudWebDriverOptions( plugin: string, runHostCommand: RunHostCommand, ): Promise> { - if (plugin === 'testmu') { + const factory = CLOUD_WEBDRIVER_PLUGINS[plugin]; + if (factory) { // The package's default export is the plugin factory; the WebDriver is what its setup() builds. - const plugin_ = testmuPlugin(); + const plugin_ = factory(); if (!plugin_.setup) - throw new Error('The TestMu plugin exposes no setup() to build a WebDriver from.'); + throw new Error(`The ${plugin} plugin exposes no setup() to build a WebDriver from.`); const created = (await plugin_.setup({ env: PROVIDER_ENV, clientVersion: '0.0.0', diff --git a/scripts/check-provider-plugin.mjs b/scripts/check-provider-plugin.mjs index 513aecad63..df1c11dd29 100644 --- a/scripts/check-provider-plugin.mjs +++ b/scripts/check-provider-plugin.mjs @@ -69,6 +69,7 @@ try { await fs.readFile(path.join(project, 'node_modules', manifest.name, 'package.json'), 'utf8'), ); assert.deepEqual(installed.exports, { + ...fixture.additionalExports, '.': { import: './dist/agent-device.mjs' }, './agent-device': { import: './dist/agent-device.mjs' }, }); @@ -77,6 +78,20 @@ try { await assert.rejects(fs.stat(path.join(project, 'node_modules', 'agent-device')), { code: 'ENOENT', }); + for (const subpath of Object.keys(fixture.additionalExports ?? {})) { + const specifier = `${manifest.name}${subpath.slice(1)}`; + await run( + process.execPath, + [ + '--input-type=module', + '--eval', + `await import(${JSON.stringify(specifier)}, ${JSON.stringify( + subpath.endsWith('.json') ? { with: { type: 'json' } } : {}, + )});`, + ], + project, + ); + } await fs.writeFile( path.join(home, 'config.json'), JSON.stringify({ plugins: { [manifest.name]: { installation } } }), diff --git a/scripts/layering/architecture-ownership.ts b/scripts/layering/architecture-ownership.ts index ed660ad925..a8a3e1189c 100644 --- a/scripts/layering/architecture-ownership.ts +++ b/scripts/layering/architecture-ownership.ts @@ -301,6 +301,7 @@ export const ARCHITECTURE_OWNERSHIP = { 'packages/platform-linux/', 'packages/platform-vega/', 'packages/platform-web/', + 'packages/provider-browserstack/', 'packages/provider-limrun/', 'packages/provider-revyl/', 'packages/provider-testmu/', diff --git a/scripts/layering/model.ts b/scripts/layering/model.ts index 6d1fd33090..e42621b29a 100644 --- a/scripts/layering/model.ts +++ b/scripts/layering/model.ts @@ -55,6 +55,7 @@ export type BackEdgeMap = Record; // ranked here or listed as unranked — `unclassifiedZones` and `model.test.ts` guard // that no zone is silently unclassified. const TARGET_DAG_RANK = new Map([ + ['build-config', 1], ['ad-replay', 1], ['ad-script', 1], ['command-registry', 1], @@ -119,6 +120,7 @@ export const UNRANKED_ZONES: ReadonlySet = new Set([ 'apple-runner', ...PLATFORMS.map((family) => `platform-${family}`), 'provider-webdriver', + 'provider-browserstack', 'provider-limrun', 'provider-revyl', 'provider-testmu', diff --git a/src/__tests__/cloud-connect-testmu.test.ts b/src/__tests__/cloud-connect-testmu.test.ts index b3682dca87..3ce111086a 100644 --- a/src/__tests__/cloud-connect-testmu.test.ts +++ b/src/__tests__/cloud-connect-testmu.test.ts @@ -126,17 +126,12 @@ test('connect testmu generates a local provider profile and verifies the virtual test('connect canonicalizes an upper-case app scheme and refuses an empty app id', async () => { const tempRoot = mkdtempForTestSync('agent-device-connect-app-scheme-'); const base = { json: false, help: false, version: false, platform: 'ios' as const }; - const connect = async (provider: 'testmu' | 'browserstack', providerApp: string) => + const connect = async (provider: 'testmu', providerApp: string) => await resolveConnectProviderProfile({ provider, stateDir: path.join(tempRoot, `.state-${provider}`), cwd: tempRoot, - env: { - LT_USERNAME: 'u', - LT_ACCESS_KEY: 'k', - BROWSERSTACK_USERNAME: 'u', - BROWSERSTACK_ACCESS_KEY: 'k', - }, + env: { LT_USERNAME: 'u', LT_ACCESS_KEY: 'k' }, flags: { ...base, device: 'iPhone 16', providerOsVersion: '18.0', providerApp }, }); @@ -145,22 +140,17 @@ test('connect canonicalizes an upper-case app scheme and refuses an empty app id assert.equal(readGeneratedConfig(upperCase.remoteConfigPath).providerApp, 'lt://APP1'); // Connect verification reads these flags, so they must carry the canonical reference too. assert.equal(upperCase.flags.providerApp, 'lt://APP1'); - assert.equal( - readGeneratedConfig((await connect('browserstack', 'Bs://abc')).remoteConfigPath).providerApp, - 'bs://abc', - ); for (const [provider, app] of [ ['testmu', 'lt://'], ['testmu', 'lt://a b'], ['testmu', 'LT://a/b'], - ['browserstack', 'bs://'], ] as const) { await assert.rejects( connect(provider, app), (error: unknown) => error instanceof AppError && error.code === 'INVALID_ARGS' && - /valid lt:\/\/ app reference|is not a bs:\/\/ app id/.test(error.message), + /valid lt:\/\/ app reference/.test(error.message), ); } } finally { @@ -289,16 +279,6 @@ test('providers other than TestMu refuse --provider-device-type before saving a try { for (const [provider, flags, env] of [ - [ - 'browserstack', - { - ...base, - device: 'Google Pixel 8', - providerOsVersion: '14.0', - providerApp: 'bs://app-id', - }, - { BROWSERSTACK_USERNAME: 'u', BROWSERSTACK_ACCESS_KEY: 'k' }, - ], [ 'aws-device-farm', { diff --git a/src/__tests__/provider-device-runtimes.test.ts b/src/__tests__/provider-device-runtimes.test.ts index 17f980167b..0fee880b70 100644 --- a/src/__tests__/provider-device-runtimes.test.ts +++ b/src/__tests__/provider-device-runtimes.test.ts @@ -31,12 +31,11 @@ test('built-in providers register ahead of the store and an unconfigured Limrun assert.deepEqual( composition.runtimes.map((runtime) => runtime.provider), - ['browserstack', 'aws-device-farm', 'example'], + ['aws-device-farm', 'example'], ); assert.deepEqual( composition.inventory.map(({ provider, source, state }) => [provider, source, state]), [ - ['browserstack', 'builtin', 'active'], ['aws-device-farm', 'builtin', 'active'], ['example', 'store', 'active'], ], @@ -59,7 +58,7 @@ test('daemon composition records Limrun as failed for a partial instance set and assert.deepEqual( composition.runtimes.map((runtime) => runtime.provider), - ['browserstack', 'aws-device-farm', 'example'], + ['aws-device-farm', 'example'], ); const limrun = composition.inventory.find(({ provider }) => provider === 'limrun'); assert.equal(limrun?.state, 'failed'); @@ -69,7 +68,7 @@ test('daemon composition records Limrun as failed for a partial instance set and }); test('a plugin claiming a built-in provider ID is recorded as failed and the built-in keeps the ID', async () => { - for (const provider of ['limrun', 'browserstack', 'aws-device-farm']) { + for (const provider of ['limrun', 'aws-device-farm']) { const { home, env } = pluginHome(); selectV2Plugin(home, 'example', v2RegistrationSource(provider)); const composition = await createDaemonProviderRuntimeComposition({ @@ -88,6 +87,23 @@ test('a plugin claiming a built-in provider ID is recorded as failed and the bui } }); +test('BrowserStack registers as an ordinary store plugin, not a built-in', async () => { + const { home, env } = pluginHome(); + selectV2Plugin(home, '@agent-device/browserstack', v2RegistrationSource('browserstack')); + const composition = await createDaemonProviderRuntimeComposition({ + env: env, + cwd: process.cwd(), + }); + + assert.deepEqual( + composition.inventory + .filter(({ provider }) => provider === 'browserstack') + .map(({ provider, source, state, package: name }) => [provider, source, state, name]), + [['browserstack', 'store', 'active', '@agent-device/browserstack']], + ); + await composition.shutdown(); +}); + test('a plugin claiming a routing identity is refused before the registry settles claims', async () => { for (const provider of ['cloud', 'proxy']) { const { home, env } = pluginHome(); diff --git a/src/__tests__/remote-connection.test.ts b/src/__tests__/remote-connection.test.ts index 9f9bda97b0..f1444be18e 100644 --- a/src/__tests__/remote-connection.test.ts +++ b/src/__tests__/remote-connection.test.ts @@ -298,7 +298,7 @@ test('connect proxy rejects remote-config and unknown provider combinations', as }, client: createTestClient(), }), - /Supported providers: cloud, proxy, browserstack, aws-device-farm/, + /Supported providers: cloud, proxy, aws-device-farm/, ); fs.rmSync(tempRoot, { recursive: true, force: true }); }); diff --git a/src/__tests__/test-utils/browserstack-plugin-inventory.ts b/src/__tests__/test-utils/browserstack-plugin-inventory.ts new file mode 100644 index 0000000000..3201005373 --- /dev/null +++ b/src/__tests__/test-utils/browserstack-plugin-inventory.ts @@ -0,0 +1,19 @@ +import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; +import type { PluginCandidate } from '@agent-device/plugins/registry'; +import { resolveProviderPlugins } from '@agent-device/plugins/registry'; +import manifest from '@agent-device/browserstack/package.json' with { type: 'json' }; + +/** The BrowserStack package as an installed store plugin, without touching the on-disk store. */ +function browserstackPluginCandidate(): PluginCandidate { + return { + source: 'store', + package: manifest.name as string, + load: async () => (await import('@agent-device/browserstack')).default(), + }; +} + +/** The inventory one installed BrowserStack plugin produces, the way the daemon reads it. */ +export async function browserstackPluginInventory(): Promise { + const resolved = await resolveProviderPlugins([browserstackPluginCandidate()]); + return resolved.inventory(); +} diff --git a/src/cli/commands/__tests__/daemon.test.ts b/src/cli/commands/__tests__/daemon.test.ts index 6e368a6496..5dc7082398 100644 --- a/src/cli/commands/__tests__/daemon.test.ts +++ b/src/cli/commands/__tests__/daemon.test.ts @@ -320,7 +320,7 @@ test('daemon status reads the daemon record without stopping or contacting the d version: '0.21.30', plugins: [ { - provider: 'browserstack', + provider: 'aws-device-farm', source: 'builtin', state: 'active', credentials: { variables: [], byBackend: {} }, @@ -354,7 +354,7 @@ test('daemon status reads the daemon record without stopping or contacting the d ); const render = mocks.writeCommandOutput.mock.calls[0]![2] as () => string; expect(render()).toContain('testmu [store] @agent-device/testmu@1.0.0 - failed: bad plugin'); - expect(render()).toContain('browserstack [builtin] builtin - active'); + expect(render()).toContain('aws-device-farm [builtin] builtin - active'); // A host-owned pid changes what a stop may do to it, so status says who owns it. expect(render()).toContain('pid 321, host-owned'); } finally { diff --git a/src/cli/commands/connection-browserstack.test.ts b/src/cli/commands/connection-browserstack.test.ts index d0613e5b53..526ba52e77 100644 --- a/src/cli/commands/connection-browserstack.test.ts +++ b/src/cli/commands/connection-browserstack.test.ts @@ -9,19 +9,44 @@ import { type RemoteConnectionState, } from '@agent-device/remote/remote-connection-state'; import { AppError } from '@agent-device/kernel/errors'; -import { verifyBrowserStackConnection } from '@agent-device/provider-webdriver/connection-verification'; +import { verifyBrowserStackConnection } from '@agent-device/browserstack/connection-verification'; +import browserstack from '@agent-device/browserstack'; +import { resolveProviderPlugins } from '@agent-device/plugins/registry'; import { resolveConnectProviderProfile } from '../connection/connect-provider-adapters.ts'; -import { mkdtempForTestSync, bindTestCommandHost } from '@agent-device/test-kit'; +import { + mkdtempForTestSync, + pluginHome, + selectV2Plugin, + v2RegistrationSource, + bindTestCommandHost, +} from '@agent-device/test-kit'; +import manifest from '@agent-device/browserstack/package.json' with { type: 'json' }; +import type { PluginConnectionCallbacks } from '@agent-device/plugins/connection'; import { connectWithGeneratedProviderProfile } from '../../__tests__/test-utils/connect-command.ts'; bindTestCommandHost(); -vi.mock('@agent-device/provider-webdriver/connection-verification', async (importOriginal) => ({ - ...(await importOriginal< - typeof import('@agent-device/provider-webdriver/connection-verification') - >()), +const CREDENTIALS = { + BROWSERSTACK_USERNAME: 'browser-user', + BROWSERSTACK_ACCESS_KEY: 'browser-key', +}; + +vi.mock('@agent-device/browserstack/connection-verification', () => ({ verifyBrowserStackConnection: vi.fn(), })); +vi.mock('@agent-device/plugins/load', () => ({ + withPluginConnection: async ( + _provider: string, + _builtinProviders: readonly string[], + _env: NodeJS.ProcessEnv, + runConnection: (connection: PluginConnectionCallbacks) => Promise, + ) => { + const { connections } = await resolveProviderPlugins([ + { source: 'store', package: manifest.name, load: () => browserstack() }, + ]); + return await runConnection(connections.get('browserstack')!); + }, +})); afterEach(() => { vi.clearAllMocks(); @@ -30,7 +55,22 @@ afterEach(() => { const mockedVerifyBrowserStackConnection = vi.mocked(verifyBrowserStackConnection); +let pluginHomeDir = ''; + beforeEach(() => { + const { home } = pluginHome(); + pluginHomeDir = home; + // The store declares the plugin installed with BrowserStack's capabilities; the mocked loader + // above supplies the workspace factory those assertions exercise. + selectV2Plugin( + home, + manifest.name, + v2RegistrationSource('browserstack', { + extra: `connection: { capabilities: ${JSON.stringify(browserstack().connection?.capabilities)}, resolve() {}, verify() {} },`, + credentials: '{ variables: ["BROWSERSTACK_USERNAME", "BROWSERSTACK_ACCESS_KEY"] }', + }), + ); + vi.stubEnv('AGENT_DEVICE_HOME', home); mockedVerifyBrowserStackConnection.mockImplementation(async (options) => ({ provider: 'browserstack', service: 'BrowserStack', @@ -111,7 +151,7 @@ test('connect browserstack canonicalizes the app scheme and refuses a malformed provider: 'browserstack', stateDir, cwd: tempRoot, - env: { BROWSERSTACK_USERNAME: 'browser-user', BROWSERSTACK_ACCESS_KEY: 'browser-key' }, + env: CREDENTIALS, flags: { json: false, help: false, version: false, ...flags, providerApp: app }, }), (error: unknown) => { @@ -213,13 +253,15 @@ test('connect browserstack refuses AWS Device Farm flags', async () => { provider: 'browserstack', stateDir: path.join(tempRoot, '.state'), cwd: tempRoot, - env: {}, + env: CREDENTIALS, flags: { json: false, help: false, version: false, platform: 'android', device: 'Google Pixel 8', + providerOsVersion: '14.0', + providerApp: 'bs://app-id', awsProjectArn: 'arn:aws:devicefarm:us-west-2:123:project:project-a', }, }), @@ -236,7 +278,42 @@ test('connect browserstack refuses AWS Device Farm flags', async () => { } }); -test('connect JSON preserves BrowserStack workflow notes from human output', async () => { +test('connect browserstack refuses --provider-device-type before saving a profile', async () => { + const tempRoot = mkdtempForTestSync('agent-device-connect-browserstack-device-type-'); + + try { + await assert.rejects( + resolveConnectProviderProfile({ + provider: 'browserstack', + stateDir: path.join(tempRoot, '.state'), + cwd: tempRoot, + env: CREDENTIALS, + flags: { + json: false, + help: false, + version: false, + platform: 'android', + device: 'Google Pixel 8', + providerOsVersion: '14.0', + providerApp: 'bs://app-id', + providerDeviceType: 'real', + }, + }), + (error: unknown) => { + assert.ok(error instanceof AppError); + assert.equal(error.code, 'INVALID_ARGS'); + assert.match(error.message, /^--provider-device-type is not supported by /); + assert.equal(error.details?.provider, 'browserstack'); + return true; + }, + ); + assert.equal(fs.existsSync(path.join(tempRoot, '.state')), false); + } finally { + fs.rmSync(tempRoot, { recursive: true, force: true }); + } +}); + +test('connect browserstack JSON preserves the workflow notes from human output', async () => { const result = await runCliCapture( [ 'connect', @@ -253,10 +330,7 @@ test('connect JSON preserves BrowserStack workflow notes from human output', asy '--json', ], { - env: { - BROWSERSTACK_USERNAME: 'browser-user', - BROWSERSTACK_ACCESS_KEY: 'browser-key', - }, + env: { ...CREDENTIALS, AGENT_DEVICE_HOME: pluginHomeDir }, stateDirPrefix: 'agent-device-connect-browserstack-json-', }, ); @@ -289,9 +363,7 @@ test('every command BrowserStack connect emits resolves back to the connection t '--state-dir', stateDir, ]; - const captureOptions = { - env: { BROWSERSTACK_USERNAME: 'browser-user', BROWSERSTACK_ACCESS_KEY: 'browser-key' }, - }; + const captureOptions = { env: { ...CREDENTIALS, AGENT_DEVICE_HOME: pluginHomeDir } }; try { const json = await runCliCapture( diff --git a/src/cli/commands/connection-plugin-guidance.test.ts b/src/cli/commands/connection-plugin-guidance.test.ts index 1aac8399f3..af6ec49aa3 100644 --- a/src/cli/commands/connection-plugin-guidance.test.ts +++ b/src/cli/commands/connection-plugin-guidance.test.ts @@ -26,6 +26,29 @@ test('connect names a missing provider plugin and returns installation guidance assert.match(error.hint, /If a local daemon is already running/); }); +test('connect browserstack without its plugin names the package, even with credentials set', async () => { + const { home, env } = pluginHome(); + const result = await runCliCapture( + ['connect', 'browserstack', '--platform', 'android', '--session', 'checkout', '--json'], + { + cwd: home, + env: { ...env, BROWSERSTACK_USERNAME: 'user', BROWSERSTACK_ACCESS_KEY: 'key' }, + stateDirPrefix: 'connect-missing-browserstack-', + }, + ); + assert.equal(result.code, 1); + assert.deepEqual(result.calls, []); + const { error } = JSON.parse(result.stdout); + assert.equal(error.code, 'UNSUPPORTED_OPERATION'); + assert.deepEqual(error.details, { + reason: 'plugin-not-installed', + provider: 'browserstack', + package: '@agent-device/browserstack', + installCommand: 'agent-device plugins add @agent-device/browserstack', + }); + assert.match(error.hint, /agent-device plugins add @agent-device\/browserstack/); +}); + test('connect prints installation guidance without JSON', async () => { const { home, env } = pluginHome(); const result = await runCliCapture(['connect', 'testmu', '--session', 'ci'], { diff --git a/src/cli/connection/provider-policy.test.ts b/src/cli/connection/provider-policy.test.ts index eb2f0fc785..9bef132122 100644 --- a/src/cli/connection/provider-policy.test.ts +++ b/src/cli/connection/provider-policy.test.ts @@ -25,9 +25,8 @@ test('provider policy projects provider identity into semantic capabilities', () holdsCloudDevice: true, forgetsEndedConnectionLease: true, }); - const browserStack = connectionProviderCapabilities('browserstack'); - assert.equal(browserStack.supportsArtifacts, true); - assert.equal(browserStack.usesCloudWebDriverLease, true); + // BrowserStack is a plugin: without an installed one nothing declares its capabilities. + assert.equal(connectionProviderCapabilities('browserstack').leaseKind, 'remote-provider'); assert.equal(connectionProviderCapabilities('aws-device-farm').requiresAppAttachment, true); assert.equal(connectionProviderCapabilities('proxy').leaseKind, 'proxy'); }); @@ -96,8 +95,8 @@ test('a store plugin that fails to load is named where an unknown connect provid test('a plugin that fails to load supplies no connection name even after priming', async () => { const { home, env } = pluginHome(); - selectV2Plugin(home, 'dup', v2RegistrationSource('browserstack')); - await primePluginConnections(env, ['browserstack']); + selectV2Plugin(home, 'dup', v2RegistrationSource('aws-device-farm')); + await primePluginConnections(env, ['aws-device-farm']); // The built-in claimed the id first, so the store package registers nothing. expect(pluginConnectionNames(env)).toEqual([]); expect(pluginLoadFailures(env).map(({ package: name, error }) => [name, error.reason])).toEqual([ diff --git a/src/commands/provider-plugin-catalog.ts b/src/commands/provider-plugin-catalog.ts index 03e8a282e5..f8bd08e794 100644 --- a/src/commands/provider-plugin-catalog.ts +++ b/src/commands/provider-plugin-catalog.ts @@ -5,6 +5,7 @@ type ProviderPluginDeclaration = Readonly<{ }>; const PROVIDER_PLUGIN_CATALOG: readonly ProviderPluginDeclaration[] = [ + { provider: 'browserstack', package: '@agent-device/browserstack', label: 'BrowserStack' }, { provider: 'revyl', package: '@agent-device/revyl', label: 'Revyl' }, { provider: 'testmu', package: '@agent-device/testmu', label: 'TestMu AI' }, { provider: 'webos', package: '@agent-device/webos', label: 'LG webOS' }, diff --git a/src/commands/schema/cli-help-topics.test.ts b/src/commands/schema/cli-help-topics.test.ts index c4575dbe96..7b8370af4f 100644 --- a/src/commands/schema/cli-help-topics.test.ts +++ b/src/commands/schema/cli-help-topics.test.ts @@ -411,7 +411,10 @@ test('usageForCommand resolves remote help topic', async () => { assert.match(help, /agent-device connect cloud discovers the agent-device cloud profile/); assert.match(help, /Direct proxy: agent-device connect proxy/); assert.match(help, /stores the shared proxy profile and client identity/); - assert.match(help, /BrowserStack: agent-device connect browserstack/); + assert.match( + help, + /BrowserStack \(plugin, install separately\): agent-device connect browserstack/, + ); assert.match(help, /AWS Device Farm: agent-device connect aws-device-farm/); assert.match(help, /Limrun: agent-device connect limrun/); assert.match(help, /It does not create an App Automate session/); diff --git a/src/commands/schema/cli-help.ts b/src/commands/schema/cli-help.ts index 0d2416da8e..b01a5321a6 100644 --- a/src/commands/schema/cli-help.ts +++ b/src/commands/schema/cli-help.ts @@ -471,7 +471,7 @@ Providers: Cloud: agent-device connect or agent-device connect cloud discovers the agent-device cloud profile. Remote config: agent-device connect --remote-config ./remote-config.json uses a local profile. Direct proxy: agent-device connect proxy --daemon-base-url stores the shared proxy profile and client identity. - BrowserStack: agent-device connect browserstack verifies credentials, the exact device, and a bs:// app reference, then stores a local provider profile. It does not create an App Automate session. + BrowserStack (plugin, install separately): agent-device connect browserstack verifies credentials, the exact device, and a bs:// app reference, then stores a local provider profile. It does not create an App Automate session. AWS Device Farm: agent-device connect aws-device-farm verifies credentials and the exact project, device, and optional app upload, then stores a local provider profile. It does not create a remote access session. TestMu AI (plugin, install separately): agent-device connect testmu verifies credentials and the exact virtual device (emulator or simulator) or, with --provider-device-type real, real device and OS version, then stores a local provider profile. --provider-app takes an lt:// app reference, an https URL, or a local path: connect looks an lt:// id up among your uploads for that device pool, while URL and local sources are uploaded and validated when open creates the session. It does not create a hub session. Limrun: agent-device connect limrun verifies access to the selected iOS or Android instance service, then stores a local provider profile. It does not create an instance. @@ -546,6 +546,7 @@ TestMu AI real-device flow: ${TV_PLUGIN_FLOWS} BrowserStack hosted-device flow: + agent-device plugins add @agent-device/browserstack export BROWSERSTACK_USERNAME=... BROWSERSTACK_ACCESS_KEY=... AGENT_DEVICE_SESSION=checkout-android agent-device connect browserstack --platform android --device "Google Pixel 8" --provider-os-version 14.0 --provider-app bs://app-id agent-device open com.example.app diff --git a/src/daemon-composition-credentials.test.ts b/src/daemon-composition-credentials.test.ts index 535c94f4b6..f8156f903a 100644 --- a/src/daemon-composition-credentials.test.ts +++ b/src/daemon-composition-credentials.test.ts @@ -6,6 +6,7 @@ import { mkdtempForTestSync, createTestHostEnvironment } from '@agent-device/tes import { createDaemonRuntimeDeps } from './daemon-composition.ts'; import { providerCredentialFingerprint } from '@agent-device/plugins/credential-fingerprint'; import { builtinPluginInventory } from './__tests__/test-utils/builtin-plugin-inventory.ts'; +import { browserstackPluginInventory } from './__tests__/test-utils/browserstack-plugin-inventory.ts'; vi.mock('./platform-runtime.ts', () => ({ androidObservation: {}, @@ -43,15 +44,20 @@ vi.mock('./provider-device-runtimes.ts', async () => ({ ], platformModules: [], shutdown: async () => [], - inventory: await ( - await import('./__tests__/test-utils/builtin-plugin-inventory.ts') - ).builtinPluginInventory(), + inventory: [ + ...(await ( + await import('./__tests__/test-utils/builtin-plugin-inventory.ts') + ).builtinPluginInventory()), + ...(await ( + await import('./__tests__/test-utils/browserstack-plugin-inventory.ts') + ).browserstackPluginInventory()), + ], }), })); test('daemon startup compares lease credentials with its own startup environment', async () => { const stateDir = mkdtempForTestSync('agent-device-daemon-credential-composition-'); - const inventory = await builtinPluginInventory(); + const inventory = [...(await builtinPluginInventory()), ...(await browserstackPluginInventory())]; const daemonEnv = { BROWSERSTACK_USERNAME: 'user', BROWSERSTACK_ACCESS_KEY: 'key-1' }; const runtime = await startDaemonRuntime({ host: createTestHostEnvironment({ diff --git a/src/daemon-entrypoint.test.ts b/src/daemon-entrypoint.test.ts index cd8962ce34..3c7594461b 100644 --- a/src/daemon-entrypoint.test.ts +++ b/src/daemon-entrypoint.test.ts @@ -2,7 +2,6 @@ import assert from 'node:assert/strict'; import { spawn } from 'node:child_process'; import crypto from 'node:crypto'; import fs from 'node:fs'; -import http from 'node:http'; import path from 'node:path'; import { test } from 'vitest'; import { KNOWN_APP_ERROR_CODES } from '@agent-device/kernel/errors'; @@ -22,8 +21,6 @@ import { createDurableResourceEnvelope } from '@agent-device/capture-kit'; import { screenRecordingDurableResource } from '@agent-device/capture-kit/screen-recording-session-resource'; import { - closeLoopbackServer, - listenOnLoopback, mkdtempForTestSync, waitForHttpOk, createTestHostEnvironment, @@ -156,16 +153,6 @@ test('daemon runtime publishes dual transport metadata', async () => { test('daemon rejects unowned cloud artifacts over RPC', async () => { const stateDir = mkdtempForTestSync('agent-device-daemon-provider-'); - const providerRequests: string[] = []; - const providerServer = http.createServer((_req, res) => { - res.setHeader('content-type', 'application/json'); - res.end( - JSON.stringify({ - automation_session: { video_url: 'https://browserstack.example/video.mp4' }, - }), - ); - }); - const providerPort = await listenOnLoopback(providerServer); let runtime: DaemonRuntimeController | null = null; try { @@ -176,9 +163,6 @@ test('daemon rejects unowned cloud artifacts over RPC', async () => { ...process.env, AGENT_DEVICE_STATE_DIR: stateDir, AGENT_DEVICE_DAEMON_SERVER_MODE: 'http', - BROWSERSTACK_USERNAME: 'user', - BROWSERSTACK_ACCESS_KEY: 'key', - BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `http://127.0.0.1:${providerPort}/sessions`, }, }), stderr: { write: () => {} }, @@ -198,7 +182,7 @@ test('daemon rejects unowned cloud artifacts over RPC', async () => { session: 'default', command: 'artifacts', positionals: [], - flags: { provider: 'browserstack', providerSessionId: 'wd-1' }, + flags: { provider: 'aws-device-farm', providerSessionId: 'wd-1' }, }, }), }); @@ -210,10 +194,8 @@ test('daemon rejects unowned cloud artifacts over RPC', async () => { assert.equal(body.error?.code, -32000); assert.equal(body.error?.data?.code, 'UNAUTHORIZED'); assert.deepEqual(body.error?.data?.details, { reason: 'PROVIDER_SESSION_NOT_OWNED' }); - assert.deepEqual(providerRequests, []); } finally { await runtime?.close(); - await closeLoopbackServer(providerServer); fs.rmSync(stateDir, { recursive: true, force: true }); } }); diff --git a/src/provider-credential-fingerprint.test.ts b/src/provider-credential-fingerprint.test.ts index 1c0ffa6508..8db9d1fcff 100644 --- a/src/provider-credential-fingerprint.test.ts +++ b/src/provider-credential-fingerprint.test.ts @@ -4,10 +4,12 @@ import { readDaemonProviderCredentials as daemonCredentialsFor } from './provide import type { PluginInventoryEntry } from '@agent-device/contracts/plugin-inventory'; import type { EnvMap } from '@agent-device/kernel/source-value'; import { builtinPluginInventory } from './__tests__/test-utils/builtin-plugin-inventory.ts'; +import { browserstackPluginInventory } from './__tests__/test-utils/browserstack-plugin-inventory.ts'; import { pluginHome, selectV2Plugin, v2RegistrationSource } from '@agent-device/test-kit'; import { BUILTIN_PROVIDER_IDS } from './builtin-provider-ids.ts'; -const inventory = await builtinPluginInventory(); +// BrowserStack is an installed plugin, so its credential variables come from its own inventory entry. +const inventory = [...(await builtinPluginInventory()), ...(await browserstackPluginInventory())]; const providerCredentialFingerprint = ( provider: string, env: EnvMap, diff --git a/test/integration/provider-scenarios/browserstack-runtime.ts b/test/integration/provider-scenarios/browserstack-runtime.ts new file mode 100644 index 0000000000..cb1f15c622 --- /dev/null +++ b/test/integration/provider-scenarios/browserstack-runtime.ts @@ -0,0 +1,26 @@ +import browserstack from '@agent-device/browserstack'; +import { createPluginHost } from '@agent-device/plugins/host'; +import { createCloudWebDriverRuntime } from '@agent-device/provider-webdriver/plugin'; + +export const BROWSERSTACK_PROVIDER = 'browserstack'; + +/** The WebDriver descriptor the BrowserStack plugin's `setup` builds from `env`, as `clientVersion` hosted. */ +export async function browserStackWebDriver(env: Record, clientVersion: string) { + const setup = await browserstack().setup({ + ...createPluginHost(env, undefined), + clientVersion, + }); + if (!('webDriver' in setup)) throw new Error('BrowserStack sets up a WebDriver descriptor'); + return setup.webDriver; +} + +/** A BrowserStack runtime composed the way the registry composes a plugin's WebDriver descriptor. */ +export async function createBrowserStackRuntime(options: { + env: Record; + clientVersion: string; +}) { + return await createCloudWebDriverRuntime({ + ...(await browserStackWebDriver(options.env, options.clientVersion)), + clientVersion: options.clientVersion, + }); +} diff --git a/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts b/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts index c850de9a9a..46a85c1a14 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-ios-text-entry.test.ts @@ -1,7 +1,7 @@ import type { DaemonWireRequest } from '@agent-device/contracts/command'; import assert from 'node:assert/strict'; import { test } from 'vitest'; -import { createBundledCloudWebDriverRuntimes } from './bundled-cloud-webdriver-runtimes.ts'; +import { BROWSERSTACK_PROVIDER, createBrowserStackRuntime } from './browserstack-runtime.ts'; import type { DeviceLease } from '@agent-device/contracts/device'; import { createProviderDeviceRuntimeRequestProviders } from '../../../src/provider-device-runtime.ts'; import { assertRpcOk } from './assertions.ts'; @@ -18,9 +18,8 @@ import { startCloudWebDriverTestServer, type StartedCloudWebDriverTestServer, } from './cloud-webdriver-test-server.ts'; -import { CLOUD_WEBDRIVER_PROVIDERS } from '@agent-device/provider-webdriver/providers'; -const WEBDRIVER_PROVIDER = CLOUD_WEBDRIVER_PROVIDERS.browserStack; +const WEBDRIVER_PROVIDER = BROWSERSTACK_PROVIDER; const CLIENT_VERSION = '0.20.6-test'; /** @@ -407,18 +406,17 @@ function textEntryTranscript(server: FakeIosWebDriverServer): string[] { async function createCloudIosWorld() { const server = await FakeIosWebDriverServer.start(); - const runtimes = await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'browser-user', - BROWSERSTACK_ACCESS_KEY: 'browser-key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, - }, - clientVersion: CLIENT_VERSION, - runHostCommand: async () => { - throw new Error('BrowserStack scenario must not run host commands'); - }, - }); + const runtimes = [ + await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'browser-user', + BROWSERSTACK_ACCESS_KEY: 'browser-key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, + }, + clientVersion: CLIENT_VERSION, + }), + ]; const providers = createProviderDeviceRuntimeRequestProviders(runtimes); const daemon = await createProviderScenarioHarness({ ...providers, diff --git a/test/integration/provider-scenarios/cloud-webdriver-lease-http.test.ts b/test/integration/provider-scenarios/cloud-webdriver-lease-http.test.ts index 4cf182824c..2c4cd85781 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-lease-http.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-lease-http.test.ts @@ -2,7 +2,7 @@ import assert from 'node:assert/strict'; import { buildScenarioRpcRequest } from './harness-rpc.ts'; import http from 'node:http'; import { test } from 'vitest'; -import { createBundledCloudWebDriverRuntimes } from './bundled-cloud-webdriver-runtimes.ts'; +import { BROWSERSTACK_PROVIDER, createBrowserStackRuntime } from './browserstack-runtime.ts'; import { createProviderDeviceRuntimeRequestProviders } from '../../../src/provider-device-runtime.ts'; import { skipWhenLoopbackUnavailable } from '@agent-device/test-kit'; import { createProviderScenarioHarness, withProviderScenarioResource } from './harness.ts'; @@ -13,7 +13,6 @@ import { startCloudWebDriverTestServer, type StartedCloudWebDriverTestServer, } from './cloud-webdriver-test-server.ts'; -import { CLOUD_WEBDRIVER_PROVIDERS } from '@agent-device/provider-webdriver/providers'; const CLIENT_VERSION = '0.20.3-test'; @@ -30,19 +29,18 @@ test('lease_allocate over HTTP prepares the BrowserStack session end to end', as } await withProviderScenarioResource(FakeBrowserStackServer.start, async (server) => { - const runtimes = await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'browser-user', - BROWSERSTACK_ACCESS_KEY: 'browser-key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - BROWSERSTACK_APP_UPLOAD_ENDPOINT: `${server.url}/app-automate/upload`, - BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, - }, - clientVersion: CLIENT_VERSION, - runHostCommand: async () => { - throw new Error('BrowserStack scenario must not run host commands'); - }, - }); + const runtimes = [ + await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'browser-user', + BROWSERSTACK_ACCESS_KEY: 'browser-key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + BROWSERSTACK_APP_UPLOAD_ENDPOINT: `${server.url}/app-automate/upload`, + BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, + }, + clientVersion: CLIENT_VERSION, + }), + ]; const providers = createProviderDeviceRuntimeRequestProviders(runtimes); const providerModules = runtimes.map((runtime) => Object.freeze({ runtime, module: runtime.platformRuntimeModule }), @@ -74,7 +72,7 @@ test('lease_allocate over HTTP prepares the BrowserStack session end to end', as tenantId: 'team-a', runId: 'run-a', leaseBackend: 'android-instance', - leaseProvider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, + leaseProvider: BROWSERSTACK_PROVIDER, deviceKey: 'webdriver-android-a', clientId: 'client-a', }, diff --git a/test/integration/provider-scenarios/cloud-webdriver-provider-adapters.test.ts b/test/integration/provider-scenarios/cloud-webdriver-provider-adapters.test.ts index bf9d7633e5..a070ca6ddc 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-provider-adapters.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-provider-adapters.test.ts @@ -1,19 +1,21 @@ import { createBundledCloudWebDriverRuntimes } from './bundled-cloud-webdriver-runtimes.ts'; +import { + BROWSERSTACK_PROVIDER, + browserStackWebDriver, + createBrowserStackRuntime, +} from './browserstack-runtime.ts'; import assert from 'node:assert/strict'; import fs from 'node:fs'; import type { IncomingHttpHeaders } from 'node:http'; import path from 'node:path'; import { test } from 'vitest'; import { AppError } from '@agent-device/kernel/errors'; -import { - bundledCloudWebDriverProvider, - type RunHostCommand, -} from '@agent-device/provider-webdriver'; import type { DeviceLease, LeaseLifecycleContext, ProviderDeviceRuntime, } from '@agent-device/contracts/device'; +import type { RunHostCommand } from '@agent-device/provider-webdriver'; import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations'; import type { CloudArtifactsResult } from '@agent-device/contracts/observability'; import { withProviderScenarioResource, withProviderScenarioTempDir } from './harness.ts'; @@ -37,21 +39,17 @@ test('BrowserStack facade prepares capabilities, uploads apps, and returns artif await withProviderScenarioTempDir('agent-device-browserstack-adapter-', async (tempDir) => { const appPath = path.join(tempDir, 'demo.apk'); fs.writeFileSync(appPath, 'fake apk'); - const runtime = runtimeFor( - await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'user', - BROWSERSTACK_ACCESS_KEY: 'key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - BROWSERSTACK_APP_UPLOAD_ENDPOINT: `${server.url}/app-automate/upload`, - BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, - }, - clientVersion: CLIENT_VERSION, - runHostCommand: unexpectedHostCommand, - }), - CLOUD_WEBDRIVER_PROVIDERS.browserStack, - ); - const lease = makeLease(CLOUD_WEBDRIVER_PROVIDERS.browserStack); + const runtime = await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'user', + BROWSERSTACK_ACCESS_KEY: 'key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + BROWSERSTACK_APP_UPLOAD_ENDPOINT: `${server.url}/app-automate/upload`, + BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, + }, + clientVersion: CLIENT_VERSION, + }); + const lease = makeLease(BROWSERSTACK_PROVIDER); try { const allocation = await runtime.leaseLifecycle.allocate?.( lease, @@ -90,20 +88,16 @@ test('BrowserStack facade prepares capabilities, uploads apps, and returns artif test('BrowserStack facade nests device-feature capabilities inside bstack:options', async () => { await withProviderScenarioResource(FakeCloudProviderServer.start, async (server) => { - const runtime = runtimeFor( - await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'user', - BROWSERSTACK_ACCESS_KEY: 'key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, - }, - clientVersion: CLIENT_VERSION, - runHostCommand: unexpectedHostCommand, - }), - CLOUD_WEBDRIVER_PROVIDERS.browserStack, - ); - const lease = makeLease(CLOUD_WEBDRIVER_PROVIDERS.browserStack); + const runtime = await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'user', + BROWSERSTACK_ACCESS_KEY: 'key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, + }, + clientVersion: CLIENT_VERSION, + }); + const lease = makeLease(BROWSERSTACK_PROVIDER); const context = browserStackContext(lease); try { await runtime.leaseLifecycle.allocate?.(lease, { @@ -321,19 +315,15 @@ test('TestMu uploads the materializer-selected simulator archive through the plu test('BrowserStack refuses a refused field on a repeat allocation of its live lease', async () => { await withProviderScenarioResource(FakeCloudProviderServer.start, async (server) => { - const runtime = runtimeFor( - await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'user', - BROWSERSTACK_ACCESS_KEY: 'key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - }, - clientVersion: CLIENT_VERSION, - runHostCommand: unexpectedHostCommand, - }), - CLOUD_WEBDRIVER_PROVIDERS.browserStack, - ); - const lease = makeLease(CLOUD_WEBDRIVER_PROVIDERS.browserStack); + const runtime = await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'user', + BROWSERSTACK_ACCESS_KEY: 'key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + }, + clientVersion: CLIENT_VERSION, + }); + const lease = makeLease(BROWSERSTACK_PROVIDER); const context = browserStackContext(lease); try { await runtime.leaseLifecycle.allocate?.(lease, context); @@ -353,7 +343,7 @@ test('BrowserStack refuses a refused field on a repeat allocation of its live le ); assert.equal(server.calls.length, sessionCalls); assert.deepEqual(await runtime.leaseLifecycle.heartbeat?.(lease), { - provider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, + provider: BROWSERSTACK_PROVIDER, }); } finally { await runtime.shutdown(); @@ -463,21 +453,18 @@ test('AWS Device Farm facade uses the injected host-command capability for its f }); }, 15_000); -test('bundled artifact lookup uses released provider ids without allocating a runtime', async () => { +test('BrowserStack artifact lookup uses the released provider id without allocating a runtime', async () => { await withProviderScenarioResource(FakeCloudProviderServer.start, async (server) => { - const provider = bundledCloudWebDriverProvider(CLOUD_WEBDRIVER_PROVIDERS.browserStack); - assert.ok(provider); - const { webDriver } = provider.create({ - env: { + const webDriver = await browserStackWebDriver( + { BROWSERSTACK_USERNAME: 'user', BROWSERSTACK_ACCESS_KEY: 'key', BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, }, - clientVersion: CLIENT_VERSION, - runHostCommand: unexpectedHostCommand, - }); + CLIENT_VERSION, + ); const result = await webDriver.listArtifacts?.({ - provider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, + provider: BROWSERSTACK_PROVIDER, providerSessionId: 'wd-1', }); assert.deepEqual( @@ -607,10 +594,6 @@ function assertAgentDeviceHeaders(headers: IncomingHttpHeaders | undefined): voi assert.equal(headers?.['x-agent-device-version'], CLIENT_VERSION); } -const unexpectedHostCommand: RunHostCommand = async () => { - throw new Error('unexpected host command'); -}; - class FakeAwsHostCommand { readonly sessionArn = 'arn:aws:devicefarm:session/fake'; readonly calls: string[][] = []; diff --git a/test/integration/provider-scenarios/cloud-webdriver-provider-regressions.test.ts b/test/integration/provider-scenarios/cloud-webdriver-provider-regressions.test.ts index c6666abcf8..41a6ea544e 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-provider-regressions.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-provider-regressions.test.ts @@ -1,10 +1,10 @@ import { createBundledCloudWebDriverRuntimes } from './bundled-cloud-webdriver-runtimes.ts'; +import { BROWSERSTACK_PROVIDER, createBrowserStackRuntime } from './browserstack-runtime.ts'; import type { DaemonWireRequest } from '@agent-device/contracts/command'; import assert from 'node:assert/strict'; import fs from 'node:fs'; import path from 'node:path'; import { test, vi } from 'vitest'; -import { type RunHostCommand } from '@agent-device/provider-webdriver'; import type { CaptureSnapshotResult } from '@agent-device/contracts/client'; import type { DeviceLease } from '@agent-device/contracts/device'; import type { PlatformRuntimeHost } from '@agent-device/contracts/platform-runtime-operations'; @@ -62,19 +62,15 @@ test('AWS Device Farm endpoint selection skips live-control WebSocket URLs', asy test('WebDriver session creation is not retried on transient provider failures', async () => { await withProviderScenarioResource(ProviderRegressionServer.start, async (server) => { server.sessionFailuresRemaining = 1; - const runtime = providerRuntimeFor( - await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'user', - BROWSERSTACK_ACCESS_KEY: 'key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - }, - clientVersion: PROVIDER_REGRESSION_CLIENT_VERSION, - runHostCommand: unexpectedHostCommand, - }), - CLOUD_WEBDRIVER_PROVIDERS.browserStack, - ); - const lease = providerRegressionLease(CLOUD_WEBDRIVER_PROVIDERS.browserStack); + const runtime = await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'user', + BROWSERSTACK_ACCESS_KEY: 'key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + }, + clientVersion: PROVIDER_REGRESSION_CLIENT_VERSION, + }); + const lease = providerRegressionLease(BROWSERSTACK_PROVIDER); try { await assert.rejects( () => runtime.leaseLifecycle.allocate!(lease, browserStackRegressionContext()), @@ -233,15 +229,16 @@ test('BrowserStack iOS snapshot reaches one shared presenter and public daemon o await withProviderScenarioResource( () => ProviderRegressionServer.start('ios'), async (server) => { - const runtimes = await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'user', - BROWSERSTACK_ACCESS_KEY: 'key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - }, - clientVersion: PROVIDER_REGRESSION_CLIENT_VERSION, - runHostCommand: unexpectedHostCommand, - }); + const runtimes = [ + await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'user', + BROWSERSTACK_ACCESS_KEY: 'key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + }, + clientVersion: PROVIDER_REGRESSION_CLIENT_VERSION, + }), + ]; const providers = createProviderDeviceRuntimeRequestProviders(runtimes); const daemon = await createProviderScenarioHarness({ ...providers, @@ -312,17 +309,13 @@ test('BrowserStack iOS snapshot reaches one shared presenter and public daemon o ); }); -const unexpectedHostCommand: RunHostCommand = async () => { - throw new Error('unexpected host command'); -}; - function browserStackIosFlags(leaseId?: string): DaemonWireRequest['flags'] { return { platform: 'ios', tenant: 'team-a', runId: 'run-a', leaseId, - leaseProvider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, + leaseProvider: BROWSERSTACK_PROVIDER, device: 'iPhone 15', providerApp: 'bs://preuploaded', providerOsVersion: '17.0', @@ -338,7 +331,7 @@ function browserStackIosMeta(leaseId?: string): DaemonWireRequest['meta'] { runId: 'run-a', leaseId, leaseBackend: 'ios-instance', - leaseProvider: CLOUD_WEBDRIVER_PROVIDERS.browserStack, + leaseProvider: BROWSERSTACK_PROVIDER, deviceKey: 'webdriver-ios-a', clientId: 'client-a', }; diff --git a/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts b/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts index 4a7ec82b11..51a6d58d04 100644 --- a/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts +++ b/test/integration/provider-scenarios/cloud-webdriver-runtime.test.ts @@ -4,7 +4,7 @@ import fs from 'node:fs'; import path from 'node:path'; import { test, vi } from 'vitest'; import { isRequestCanceledError } from '@agent-device/kernel/errors'; -import { createBundledCloudWebDriverRuntimes } from './bundled-cloud-webdriver-runtimes.ts'; +import { BROWSERSTACK_PROVIDER, createBrowserStackRuntime } from './browserstack-runtime.ts'; import type { CloudArtifact } from '@agent-device/contracts/observability'; import type { DeviceLease } from '@agent-device/contracts/device'; import { createProviderDeviceRuntimeRequestProviders } from '../../../src/provider-device-runtime.ts'; @@ -23,9 +23,8 @@ import { startCloudWebDriverTestServer, type StartedCloudWebDriverTestServer, } from './cloud-webdriver-test-server.ts'; -import { CLOUD_WEBDRIVER_PROVIDERS } from '@agent-device/provider-webdriver/providers'; -const WEBDRIVER_PROVIDER = CLOUD_WEBDRIVER_PROVIDERS.browserStack; +const WEBDRIVER_PROVIDER = BROWSERSTACK_PROVIDER; const CLIENT_VERSION = '0.20.3-test'; /** One transparent pixel: enough for a driver answer to be real base64 PNG. */ const TINY_PNG_BASE64 = @@ -309,19 +308,18 @@ async function waitForLeaseExpiry(server: FakeWebDriverServer): Promise { async function createCloudWebDriverWorld(params: { leaseTtlMs?: number } = {}) { const server = await FakeWebDriverServer.start(); - const runtimes = await createBundledCloudWebDriverRuntimes({ - env: { - BROWSERSTACK_USERNAME: 'browser-user', - BROWSERSTACK_ACCESS_KEY: 'browser-key', - BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, - BROWSERSTACK_APP_UPLOAD_ENDPOINT: `${server.url}/app-automate/upload`, - BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, - }, - clientVersion: CLIENT_VERSION, - runHostCommand: async () => { - throw new Error('BrowserStack scenario must not run host commands'); - }, - }); + const runtimes = [ + await createBrowserStackRuntime({ + env: { + BROWSERSTACK_USERNAME: 'browser-user', + BROWSERSTACK_ACCESS_KEY: 'browser-key', + BROWSERSTACK_WEBDRIVER_ENDPOINT: `${server.url}/wd/hub/`, + BROWSERSTACK_APP_UPLOAD_ENDPOINT: `${server.url}/app-automate/upload`, + BROWSERSTACK_SESSION_DETAILS_ENDPOINT: `${server.url}/app-automate/sessions`, + }, + clientVersion: CLIENT_VERSION, + }), + ]; const providers = createProviderDeviceRuntimeRequestProviders(runtimes); const providerModules = runtimes.map((runtime) => Object.freeze({ runtime, module: runtime.platformRuntimeModule }), diff --git a/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts b/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts index 5dca13a202..8c6a871741 100644 --- a/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts +++ b/test/integration/provider-scenarios/stale-provider-runtime-admission.test.ts @@ -4,6 +4,7 @@ import path from 'node:path'; import { expect, test, vi } from 'vitest'; import type { DeviceLease } from '@agent-device/contracts/device'; import { createBundledCloudWebDriverRuntimes } from './bundled-cloud-webdriver-runtimes.ts'; +import { BROWSERSTACK_PROVIDER, createBrowserStackRuntime } from './browserstack-runtime.ts'; import { createLimrunRuntime, type LimrunRuntimeDependencies } from '@agent-device/provider-limrun'; import { limrunTestDependencies } from '../../../src/platform-runtime-gateway.fixtures.ts'; import type { DeviceInfo } from '@agent-device/kernel/device'; @@ -67,7 +68,7 @@ vi.mock('@limrun/api/instance-client', () => ({ test('a released WebDriver device remains provider-owned with deployment unavailable', async () => { const server = await startCloudWebDriverTestServer(new StaleWebDriverServer()); const runtime = await webDriverRuntime(server.url); - const lease = providerLease(CLOUD_WEBDRIVER_PROVIDERS.browserStack, 'webdriver-stale'); + const lease = providerLease(BROWSERSTACK_PROVIDER, 'webdriver-stale'); try { const allocate = runtime.leaseLifecycle.allocate; @@ -231,22 +232,14 @@ test('an active AWS WebDriver device denies unsupported install from facts befor }); async function webDriverRuntime(endpoint: string) { - const runtimes = await createBundledCloudWebDriverRuntimes({ + return await createBrowserStackRuntime({ env: { BROWSERSTACK_USERNAME: 'browser-user', BROWSERSTACK_ACCESS_KEY: 'browser-key', BROWSERSTACK_WEBDRIVER_ENDPOINT: `${endpoint}/wd/hub/`, }, clientVersion: 'test', - runHostCommand: async () => { - throw new Error('stale WebDriver admission never invokes host commands'); - }, }); - const runtime = runtimes.find( - (candidate) => candidate.provider === CLOUD_WEBDRIVER_PROVIDERS.browserStack, - ); - if (!runtime) throw new Error('Expected BrowserStack WebDriver runtime'); - return runtime; } async function awsWebDriverRuntime(host: AwsRemoteAccessHost) { diff --git a/test/integration/smoke-provider-cli-disconnect.test.ts b/test/integration/smoke-provider-cli-disconnect.test.ts index 7b666b1bbc..1bb34981c7 100644 --- a/test/integration/smoke-provider-cli-disconnect.test.ts +++ b/test/integration/smoke-provider-cli-disconnect.test.ts @@ -4,14 +4,57 @@ import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; import { pathToFileURL } from 'node:url'; +import { pluginHome, selectV2Plugin } from '@agent-device/test-kit'; import { formatResultDebug, runBuiltCliJson } from './cli-json.ts'; import './support/provider-disconnect-fetch.mjs'; +const PROVIDER = 'smoke-cloud'; + +/** + * A hosted provider arrives as an installed plugin, so this flow installs a minimal one: the point + * is the built CLI's connect, open, and disconnect ordering, not a particular provider's API. + */ +const PROVIDER_PLUGIN_SOURCE = `export default () => ({ + apiVersion: 2, + provider: ${JSON.stringify(PROVIDER)}, + credentials: { variables: [] }, + connection: { + capabilities: { + leaseKind: 'direct-device-provider', + requiresAppAttachment: false, + requiresRemoteDaemon: false, + supportsArtifacts: true, + supportsDeferredAppSelection: false, + supportsDirectPortReverse: false, + usesCloudWebDriverLease: true, + }, + resolve: ({ flags }) => ({ + profile: { + leaseProvider: ${JSON.stringify(PROVIDER)}, + platform: flags.platform, + device: flags.device, + providerOsVersion: flags.providerOsVersion, + providerApp: flags.providerApp, + }, + }), + verify: async ({ flags }) => ({ + provider: ${JSON.stringify(PROVIDER)}, + service: 'Smoke Cloud', + verificationMessage: 'Credentials, device, and uploaded app verified.', + device: { status: 'verified', name: flags.device, platform: flags.platform, osVersion: flags.providerOsVersion }, + app: { status: 'verified', reference: flags.providerApp }, + }), + }, + setup: async () => { + throw new Error('The smoke daemon is remote and sets up no provider runtime.'); + }, +});`; + test('built CLI provider flow closes its named session before disconnect cleanup', async (t) => { const fixture = createProviderDaemonFixture(t); const env = createProviderEnv(fixture); - await assertUnnamedRefused(fixture, env, browserStackConnectArgs(fixture)); - const activeSession = await connectBrowserStackProvider(fixture, env); + await assertUnnamedRefused(fixture, env, providerConnectArgs(fixture)); + const activeSession = await connectProvider(fixture, env); await assertUnnamedRefused(fixture, env, ['open', 'Demo']); await openProviderApp(fixture, env, activeSession); await disconnectProviderSession(fixture, env, activeSession); @@ -45,10 +88,11 @@ function createProviderEnv(fixture: ProviderDaemonFixture): NodeJS.ProcessEnv { const fetchFixtureUrl = pathToFileURL( path.join(import.meta.dirname, 'support/provider-disconnect-fetch.mjs'), ).href; + const { home, env: pluginEnv } = pluginHome(); + selectV2Plugin(home, '@agent-device/smoke-cloud', PROVIDER_PLUGIN_SOURCE); return { ...process.env, - BROWSERSTACK_USERNAME: 'browser-user', - BROWSERSTACK_ACCESS_KEY: 'browser-key', + ...pluginEnv, AGENT_DEVICE_TEST_RPC_LOG_PATH: fixture.rpcLogPath, // Generated connection state never persists the daemon bearer token // (ADR 0007), so commands after `connect` must resolve it from the @@ -69,11 +113,11 @@ function readRpcRequests(fixture: ProviderDaemonFixture): any[] { .map((line) => JSON.parse(line)); } -async function connectBrowserStackProvider( +async function connectProvider( fixture: ProviderDaemonFixture, env: NodeJS.ProcessEnv, ): Promise { - const connectArgs = [...browserStackConnectArgs(fixture), '--session', 'bs-smoke']; + const connectArgs = [...providerConnectArgs(fixture), '--session', 'provider-smoke']; const connectResult = await runBuiltCliJson(connectArgs, env); assert.equal(connectResult.status, 0, formatResultDebug('connect', connectArgs, connectResult)); @@ -83,14 +127,14 @@ async function connectBrowserStackProvider( formatResultDebug('connect', connectArgs, connectResult), ); const activeSession = connectResult.json?.data?.session; - assert.equal(activeSession, 'bs-smoke'); + assert.equal(activeSession, 'provider-smoke'); return activeSession; } -function browserStackConnectArgs(fixture: ProviderDaemonFixture): string[] { +function providerConnectArgs(fixture: ProviderDaemonFixture): string[] { return [ 'connect', - 'browserstack', + PROVIDER, '--platform', 'android', '--device', @@ -183,8 +227,8 @@ function assertProviderDisconnectRpc(rpcRequests: any[], activeSession: string): const releaseRpc = rpcRequests.find((request) => request.method === 'agent_device.lease.release'); assert.equal(releaseRpc?.params?.session, activeSession); - assert.equal(releaseRpc?.params?.leaseId, 'lease-bs-1'); - assert.equal(releaseRpc?.params?.leaseProvider, 'browserstack'); + assert.equal(releaseRpc?.params?.leaseId, 'lease-smoke-1'); + assert.equal(releaseRpc?.params?.leaseProvider, PROVIDER); } async function assertNoActiveConnection( diff --git a/test/integration/support/provider-disconnect-fetch.mjs b/test/integration/support/provider-disconnect-fetch.mjs index 383e169cb0..2294faea87 100644 --- a/test/integration/support/provider-disconnect-fetch.mjs +++ b/test/integration/support/provider-disconnect-fetch.mjs @@ -4,8 +4,6 @@ import { EventEmitter } from 'node:events'; import { Readable } from 'node:stream'; const DAEMON_BASE_URL = 'https://agent-device.test/agent-device'; -const DEVICES_URL = 'https://api-cloud.browserstack.com/app-automate/devices.json'; -const APPS_URL = 'https://api-cloud.browserstack.com/app-automate/recent_apps?limit=100'; const rpcLogPath = process.env.AGENT_DEVICE_TEST_RPC_LOG_PATH; if (rpcLogPath) installFixture(rpcLogPath); @@ -18,14 +16,6 @@ function installFixture(logPath) { function createFixtureFetch(logPath) { const routes = [ - route('GET', DEVICES_URL, () => - jsonResponse([ - { os: 'android', os_version: '14.0', device: 'Google Pixel 8', realMobile: true }, - ]), - ), - route('GET', APPS_URL, () => - jsonResponse([{ app_name: 'sample.apk', app_version: '1.2.3', app_url: 'bs://app-id' }]), - ), route('GET', `${DAEMON_BASE_URL}/health`, () => jsonResponse({ ok: true, @@ -103,7 +93,7 @@ async function fetchNodeResponse(fixtureFetch, options, chunks) { const RPC_METHOD_RESPONSES = { 'agent_device.lease.allocate': (params) => ({ lease: { - leaseId: 'lease-bs-1', + leaseId: 'lease-smoke-1', tenantId: params.tenantId, runId: params.runId, backend: params.backend, @@ -114,7 +104,7 @@ const RPC_METHOD_RESPONSES = { }), 'agent_device.lease.release': () => ({ released: true, - provider: { provider: 'browserstack', providerSessionId: 'bs-session-1' }, + provider: { provider: 'smoke-cloud', providerSessionId: 'smoke-session-1' }, }), }; @@ -126,11 +116,11 @@ const COMMAND_RESPONSES = { platform: 'android', target: 'mobile', device: 'Pixel', - id: 'browserstack-pixel', - serial: 'browserstack-pixel', + id: 'smoke-cloud-pixel', + serial: 'smoke-cloud-pixel', }), close: () => ({ - provider: { provider: 'browserstack', providerSessionId: 'bs-session-1' }, + provider: { provider: 'smoke-cloud', providerSessionId: 'smoke-session-1' }, }), }; diff --git a/tsconfig.typecheck.json b/tsconfig.typecheck.json index 122d4298d9..dd7d7586f4 100644 --- a/tsconfig.typecheck.json +++ b/tsconfig.typecheck.json @@ -5,6 +5,7 @@ "extends": "./tsconfig.json", "compilerOptions": { "tsBuildInfoFile": "./.tmp/tsconfig.typecheck.tsbuildinfo" }, "references": [ + { "path": "packages/build-config" }, { "path": "packages/ad-replay" }, { "path": "packages/ad-script" }, { "path": "packages/apple-runner" }, @@ -30,6 +31,7 @@ { "path": "packages/platform-web" }, { "path": "packages/plugins" }, { "path": "packages/provider-limrun" }, + { "path": "packages/provider-browserstack" }, { "path": "packages/provider-revyl" }, { "path": "packages/provider-testmu" }, { "path": "packages/provider-webos" }, diff --git a/website/docs/docs/browserstack.md b/website/docs/docs/browserstack.md index 827916213e..f6bebd8e1b 100644 --- a/website/docs/docs/browserstack.md +++ b/website/docs/docs/browserstack.md @@ -3,7 +3,17 @@ title: BrowserStack description: Drive BrowserStack App Automate sessions with agent-device. --- -Use BrowserStack App Automate to run agent-device on hosted Android and iOS devices over WebDriver. You need a BrowserStack account with App Automate access. +Use BrowserStack App Automate to run agent-device on hosted Android and iOS devices over WebDriver. You need a BrowserStack account with App Automate access and the `@agent-device/browserstack` plugin. + +## Install the plugin + +```bash +agent-device plugins add @agent-device/browserstack +``` + +The plugin is an optional npm package installed under `AGENT_DEVICE_HOME`. +After you add or update it, close open sessions and run `agent-device daemon stop` +with `--state-dir ` set to the state directory you use; the next device command loads the plugin. ## Set credentials and connect diff --git a/website/docs/docs/device-clouds.md b/website/docs/docs/device-clouds.md index 99566acfae..5bc4897c10 100644 --- a/website/docs/docs/device-clouds.md +++ b/website/docs/docs/device-clouds.md @@ -5,7 +5,7 @@ description: Choose a hosted device provider for agent and CI workflows. Use a device cloud or farm when an agent needs to drive a hosted mobile device without an interactive login. Pick the provider whose account and devices you use: -- [BrowserStack](/docs/browserstack): Android and iOS App Automate sessions over WebDriver. +- [BrowserStack](/docs/browserstack): Android and iOS App Automate sessions over WebDriver. Install the `@agent-device/browserstack` plugin first. - [AWS Device Farm](/docs/aws-device-farm): Android and iOS remote-access sessions through AWS. - [TestMu AI](/docs/testmu): Android emulator, iOS simulator, and real-device sessions over WebDriver. - [Limrun](/docs/limrun): direct iOS simulator and Android emulator instances. @@ -16,7 +16,7 @@ Use a device cloud or farm when an agent needs to drive a hosted mobile device w | | BrowserStack | AWS Device Farm | TestMu AI | Limrun | Revyl | | --- | --- | --- | --- | --- | --- | | Devices | Android and iOS real devices | Android and iOS real devices | Android emulators and iOS simulators by default; real devices with `--provider-device-type real` | Android emulators and iOS simulators | Android emulators and iOS simulators | -| Ships as | Built in | Built in; needs the AWS CLI | The `@agent-device/testmu` plugin | Built in | The `@agent-device/revyl` plugin | +| Ships as | The `@agent-device/browserstack` plugin | Built in; needs the AWS CLI | The `@agent-device/testmu` plugin | Built in | The `@agent-device/revyl` plugin | | Credentials | `BROWSERSTACK_USERNAME`, `BROWSERSTACK_ACCESS_KEY` | The AWS CLI credential chain, such as `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION` | `LT_USERNAME`, `LT_ACCESS_KEY` | `LIMRUN_API_KEY` (optional `LIMRUN_REGION`), or `LIM_*_INSTANCE_*` for an existing instance | `REVYL_API_KEY` (optional `REVYL_API_URL` for another Revyl backend) | | Device allocated on | `open` | `open` | `open` | First device command, such as `install` or `open` | First device command, such as `open` | | App source | `--provider-app`: `bs://` reference, HTTP(S) URL, or local path | `--aws-app-arn` upload ARN; no install after allocation | `--provider-app`: `lt://` reference, HTTP(S) URL, or local path | `install `, or `open ` for an uploaded asset | `--provider-app`: a public HTTPS URL only, installed when the device starts | diff --git a/website/docs/docs/plugins.md b/website/docs/docs/plugins.md index 78f316481b..e141c7d711 100644 --- a/website/docs/docs/plugins.md +++ b/website/docs/docs/plugins.md @@ -2,7 +2,7 @@ title: Plugins --- -Provider plugins add device providers that agent-device does not bundle, such as [TestMu AI](/docs/testmu), [LG webOS](/docs/webos), and [Samsung Tizen](/docs/tizen). Installing one requires npm on your host: +Provider plugins add device providers that agent-device does not bundle, such as [BrowserStack](/docs/browserstack), [TestMu AI](/docs/testmu), [LG webOS](/docs/webos), and [Samsung Tizen](/docs/tizen). Installing one requires npm on your host: ```bash agent-device plugins add @example/agent-device-provider @@ -13,9 +13,9 @@ agent-device plugins remove @example/agent-device-provider `agent-device help connect` and `agent-device help remote` identify known optional providers as `plugin, install separately` and show their installation commands, even before you install them. -For example, TestMu AI requires `agent-device plugins add @agent-device/testmu`. +For example, BrowserStack requires `agent-device plugins add @agent-device/browserstack`, and TestMu AI requires `agent-device plugins add @agent-device/testmu`. -If you run `agent-device connect testmu` without its plugin, the error gives that installation +If you run `agent-device connect browserstack` or `agent-device connect testmu` without its plugin, the error gives that installation command and tells you to retry your original command. With `--json`, the error has `details.reason: plugin-not-installed`, `details.package`, and `details.installCommand`. If the plugin is selected but unavailable, the reason is `plugin-unavailable`; run @@ -51,7 +51,7 @@ A missing installation returns `plugin-not-installed` with the package and insta ## See which providers are registered -`agent-device daemon status` lists every provider the running daemon registered: the bundled ones (BrowserStack, AWS Device Farm, and Limrun when it is configured), then installed plugins. With `--json`, each entry has: +`agent-device daemon status` lists every provider the running daemon registered: the bundled ones (AWS Device Farm, and Limrun when it is configured), then installed plugins such as BrowserStack. With `--json`, each entry has: ```json { diff --git a/website/src/site/content.ts b/website/src/site/content.ts index 1bdf878e0b..fb35f5b304 100644 --- a/website/src/site/content.ts +++ b/website/src/site/content.ts @@ -475,7 +475,7 @@ export const cloud = { icon: 'cube', label: 'Device clouds', title: 'On hosted devices', - body: 'The same commands drive BrowserStack, AWS Device Farm and Limrun devices built in, TestMu AI through its provider plugin, and Expo Simulators on EAS.', + body: 'The same commands drive AWS Device Farm and Limrun devices built in, BrowserStack and TestMu AI through their provider plugins, and Expo Simulators on EAS.', cmd: 'agent-device connect limrun --platform ios', href: docs.clouds, },