@e2e-dev/testmu 0.0.0-stage → 0.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+@e2e-dev/testmu
+Copyright 2026 TesterArmy, Inc.
+
+This product includes software developed at TesterArmy, Inc.
+(https://tester.army).

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# @e2e-dev/testmu
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Run `@e2e-dev/mobile` tests on [TestMu AI](https://www.lambdatest.com) (formerly LambdaTest)
+Android emulators, iOS simulators, and real devices. Each worker slot leases one device,
+with your app installed, and releases it when the run ends.
+
+```bash
+npm install --save-dev @e2e-dev/testmu
+```
+
+```ts title="e2e.config.ts"
+import type { E2EConfig } from 'e2e';
+import { mobile } from '@e2e-dev/mobile';
+import { testmu } from '@e2e-dev/testmu';
+
+export default {
+  targets: [
+    {
+      engine: mobile({
+        platform: 'android',
+        device: testmu({ device: 'Galaxy S22 Ultra 5G', osVersion: '14', app: 'https://example.com/app.apk' }),
+      }),
+      app: { bundleId: 'com.example.app' },
+    },
+  ],
+  workers: 2,
+} satisfies E2EConfig;
+```
+
+Set `LT_USERNAME` and `LT_ACCESS_KEY` in the run environment, from
+**Account Settings → Password & Security → Username and Access Key**
+([accounts.lambdatest.com/security/username-accesskey](https://accounts.lambdatest.com/security/username-accesskey)).
+`device` and `osVersion` must match TestMu AI's catalog exactly, and `app` is an
+`lt://` app id, an `https` URL, or a local path. `deviceType: 'real'` picks a real device.
+
+See the [integration guide](https://e2e.tester.army/docs/integrations/testmu) for every
+option and the limits.
+
+## License
+
+Apache-2.0

package/dist/.build.json

@@ -0,0 +1 @@
+{"version":"0.0.0"}

package/dist/credentials.d.ts

@@ -0,0 +1,6 @@
+export interface TestmuCredentials {
+    readonly username: string;
+    readonly accessKey: string;
+}
+/** `LT_USERNAME` and `LT_ACCESS_KEY` from the run's environment; throws naming each one that is unset or blank. */
+export declare function testmuCredentials(env: Readonly<Record<string, string | undefined>>): TestmuCredentials;

package/dist/credentials.js

@@ -0,0 +1,17 @@
+const LT_USERNAME = 'LT_USERNAME';
+const LT_ACCESS_KEY = 'LT_ACCESS_KEY';
+/** `LT_USERNAME` and `LT_ACCESS_KEY` from the run's environment; throws naming each one that is unset or blank. */
+export function testmuCredentials(env) {
+    const username = envValue(env, LT_USERNAME);
+    const accessKey = envValue(env, LT_ACCESS_KEY);
+    if (username === undefined || accessKey === undefined) {
+        const missing = [username === undefined ? LT_USERNAME : undefined, accessKey === undefined ? LT_ACCESS_KEY : undefined].filter((name) => name !== undefined);
+        throw new Error(`${missing.join(' and ')} ${missing.length === 1 ? 'is' : 'are'} not set; set ${LT_USERNAME} and ${LT_ACCESS_KEY} to your TestMu AI username and access key in the environment \`e2e run\` starts in`);
+    }
+    return { username, accessKey };
+}
+/** A non-empty variable from the run's environment, trimmed, or `undefined`. */
+function envValue(env, name) {
+    const value = env[name]?.trim();
+    return value === undefined || value === '' ? undefined : value;
+}

package/dist/daemon.d.ts

@@ -0,0 +1,12 @@
+import type { DriverGrant, DriverRequest } from './driver.ts';
+export declare function assertDriverVersion(expected: string): void;
+/**
+ * Registers the installed `@agent-device/testmu` in a private agent-device
+ * home, the layout `agent-device plugins add` writes, without fetching it
+ * from the registry again.
+ */
+export declare function installPlugin(home: string): Promise<void>;
+/** Not cancellable: an interrupted allocation can still grant a lease, which the caller then releases. */
+export declare function startDriver(request: DriverRequest, env: NodeJS.ProcessEnv): Promise<DriverGrant>;
+/** Stopping the daemon releases its leases, which ends their TestMu AI sessions. */
+export declare function stopDriver(stateDir: string, env: NodeJS.ProcessEnv, signal: AbortSignal): Promise<void>;

package/dist/daemon.js

@@ -0,0 +1,80 @@
+import { execFile, fork } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { mkdir, symlink, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const exec = promisify(execFile);
+const PLUGIN = '@agent-device/testmu';
+/** A property of a parsed JSON value, or undefined when the value is not an object. */
+function field(value, key) {
+    return typeof value === 'object' && value !== null ? Reflect.get(value, key) : undefined;
+}
+/** Resolve a dependency's package directory from its entry, without importing it. */
+function installation(name) {
+    let directory = path.dirname(fileURLToPath(import.meta.resolve(name)));
+    while (true) {
+        try {
+            const manifest = JSON.parse(readFileSync(path.join(directory, 'package.json'), 'utf8'));
+            const version = field(manifest, 'version');
+            if (field(manifest, 'name') === name && typeof version === 'string')
+                return { directory, version, bin: field(manifest, 'bin') };
+        }
+        catch { /* The entry may be several directories below its package. */ }
+        const parent = path.dirname(directory);
+        if (parent === directory)
+            throw new Error(`Cannot find the installed ${name} package`);
+        directory = parent;
+    }
+}
+export function assertDriverVersion(expected) {
+    const actual = installation('agent-device').version;
+    if (actual !== expected)
+        throw new Error(`@e2e-dev/testmu uses agent-device ${actual}, but @e2e-dev/mobile uses ${expected}. Install matching versions.`);
+}
+/**
+ * Registers the installed `@agent-device/testmu` in a private agent-device
+ * home, the layout `agent-device plugins add` writes, without fetching it
+ * from the registry again.
+ */
+export async function installPlugin(home) {
+    const plugin = installation(PLUGIN);
+    const id = randomUUID();
+    const scope = path.join(home, 'plugins', id, 'node_modules', '@agent-device');
+    await mkdir(scope, { recursive: true, mode: 0o700 });
+    await symlink(plugin.directory, path.join(scope, 'testmu'), 'junction');
+    await writeFile(path.join(home, 'config.json'), `${JSON.stringify({ plugins: { [PLUGIN]: { installation: id, version: plugin.version } } })}\n`, { mode: 0o600 });
+}
+/** Not cancellable: an interrupted allocation can still grant a lease, which the caller then releases. */
+export async function startDriver(request, env) {
+    const entry = new URL(import.meta.url.endsWith('.ts') ? './driver.ts' : './driver.js', import.meta.url);
+    return new Promise((resolve, reject) => {
+        const child = fork(entry, [], { env, execArgv: [], stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+        let answered = false;
+        child.once('error', reject);
+        child.once('message', (reply) => {
+            answered = true;
+            if (reply.grant)
+                resolve(reply.grant);
+            else
+                reject(new Error(reply.error ?? 'TestMu AI driver returned no lease'));
+        });
+        child.once('exit', () => {
+            if (!answered)
+                reject(new Error('TestMu AI driver exited before allocation finished'));
+        });
+        child.send(request);
+    });
+}
+/** Stopping the daemon releases its leases, which ends their TestMu AI sessions. */
+export async function stopDriver(stateDir, env, signal) {
+    const cli = installation('agent-device');
+    const bin = field(cli.bin, 'agent-device');
+    if (typeof bin !== 'string')
+        throw new Error('The installed agent-device package has no agent-device bin');
+    const { stdout } = await exec(process.execPath, [path.join(cli.directory, bin), 'daemon', 'stop', '--state-dir', stateDir, '--clean', '--json'], { env, signal });
+    const pending = field(field(field(JSON.parse(stdout), 'data'), 'providerReleases'), 'pending');
+    if (Array.isArray(pending) && pending.length > 0)
+        throw new Error(`agent-device stopped without ending ${pending.length} TestMu AI session(s)`);
+}

package/dist/driver.d.ts

@@ -0,0 +1,12 @@
+import { type LeaseAllocateOptions } from 'agent-device';
+/** A separate process gives each daemon its own credentials and plugin home without changing the runner's environment. */
+export interface DriverRequest {
+    stateDir: string;
+    allocate: LeaseAllocateOptions;
+}
+export interface DriverGrant {
+    leaseId: string;
+    tenantId: string;
+    runId: string;
+    retainOnClose: boolean;
+}

package/dist/driver.js

@@ -0,0 +1,8 @@
+import { createAgentDeviceClient } from 'agent-device';
+process.once('message', (request) => {
+    void allocate(request).then((grant) => process.send?.({ grant }, () => process.disconnect?.()), (cause) => process.send?.({ error: cause instanceof Error ? cause.message : String(cause) }, () => process.disconnect?.()));
+});
+async function allocate({ stateDir, allocate: options }) {
+    const lease = await createAgentDeviceClient({ stateDir }).leases.allocate(options);
+    return { leaseId: lease.leaseId, tenantId: lease.tenantId, runId: lease.runId, retainOnClose: lease.retainOnClose === true };
+}

package/dist/heartbeat.d.ts

@@ -0,0 +1,4 @@
+import { type LeaseScopedOptions } from 'agent-device';
+export declare const LEASE_TTL_MS = 60000;
+/** Renew idle leases while other targets run; session retention alone does not prevent expiry. */
+export declare function startHeartbeat(stateDir: string, scope: LeaseScopedOptions, log: (line: string) => void): Promise<() => Promise<void>>;

package/dist/heartbeat.js

@@ -0,0 +1,34 @@
+import { createAgentDeviceClient } from 'agent-device';
+export const LEASE_TTL_MS = 60_000;
+/** Renew idle leases while other targets run; session retention alone does not prevent expiry. */
+export async function startHeartbeat(stateDir, scope, log) {
+    // An explicit empty URL selects the local stateDir instead of an ambient remote daemon.
+    const client = createAgentDeviceClient({ stateDir, daemonBaseUrl: '', daemonAuthToken: '', daemonTransport: 'auto' });
+    const controller = new AbortController();
+    const beat = () => client.leases.heartbeat({ ...scope, ttlMs: LEASE_TTL_MS, signal: AbortSignal.any([controller.signal, AbortSignal.timeout(10_000)]) });
+    await beat();
+    let pending = Promise.resolve();
+    let timer;
+    const schedule = () => {
+        timer = setTimeout(() => {
+            pending = beat().then(() => { }, (error) => {
+                if (controller.signal.aborted)
+                    return;
+                try {
+                    log(`lease ${scope.leaseId}: renewal failed: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                catch {
+                    // The run's log may be closed by now.
+                }
+            }).finally(() => { if (!controller.signal.aborted)
+                schedule(); });
+        }, 20_000);
+        timer.unref();
+    };
+    schedule();
+    return async () => {
+        controller.abort();
+        clearTimeout(timer);
+        await pending;
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@e2e-dev/testmu` public surface: `testmu()`, a device provider that leases
+ * TestMu AI (formerly LambdaTest) Android emulators, iOS simulators, and real
+ * devices for `@e2e-dev/mobile` through agent-device's `@agent-device/testmu`
+ * plugin.
+ */
+export { testmu } from './provider.ts';
+export type { TestmuOptions } from './provider.ts';

package/dist/index.js

@@ -0,0 +1,7 @@
+/**
+ * `@e2e-dev/testmu` public surface: `testmu()`, a device provider that leases
+ * TestMu AI (formerly LambdaTest) Android emulators, iOS simulators, and real
+ * devices for `@e2e-dev/mobile` through agent-device's `@agent-device/testmu`
+ * plugin.
+ */
+export { testmu } from './provider.js';

package/dist/provider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * TestMu AI's hosted Android emulators, iOS simulators, and real devices as a
+ * `DeviceProvider` for the mobile engine, through agent-device's
+ * `@agent-device/testmu` plugin: each lease comes from its own agent-device
+ * daemon, which runs the session over TestMu AI's Appium hub.
+ */
+import type { DeviceProvider } from '@e2e-dev/mobile';
+/** What `testmu()` takes: the device, its OS version, and the app TestMu AI installs on it. */
+export interface TestmuOptions {
+    /** Device name exactly as TestMu AI's catalog lists it: `Galaxy S22 Ultra 5G`, `iPhone 16`. */
+    readonly device: string;
+    /** OS version exactly as the catalog lists it for that device: `14` on Android, `18.0` on a virtual iOS device, `18` on a real one. */
+    readonly osVersion: string;
+    /**
+     * The build TestMu AI installs on every session: an `lt://` app id, an
+     * `https` URL, or a local path, resolved against the project root and
+     * uploaded when the lease is allocated.
+     */
+    readonly app: string;
+    /** `'virtual'` (default) for an emulator or simulator, `'real'` for a real device. */
+    readonly deviceType?: 'virtual' | 'real' | undefined;
+    /** Dashboard project the sessions are grouped under. Defaults to `e2e`. */
+    readonly project?: string | undefined;
+    /** Dashboard build the sessions are grouped under. Defaults to the run id. */
+    readonly build?: string | undefined;
+    /**
+     * Name of every session on the dashboard, with `-<slot>` appended when the
+     * target leases more than one device, so each slot's session has its own.
+     * Defaults to `e2e-<run id>-<target>-<slot>`. Slots count from 1.
+     */
+    readonly sessionName?: string | undefined;
+    /** Orientation the device starts in; absent, the device's default. */
+    readonly orientation?: 'portrait' | 'landscape' | undefined;
+    /** Country the device's IP geolocates to, as a code TestMu AI takes: `US`, `FR`. */
+    readonly geoLocation?: string | undefined;
+    /** The device's time zone, as TestMu AI takes it: `UTC+05:30`. */
+    readonly timezone?: string | undefined;
+    /** The device's language, as a language code: `fr`. */
+    readonly language?: string | undefined;
+    /** The device's locale: `fr_FR`. */
+    readonly locale?: string | undefined;
+    /** Appium version TestMu AI starts for the session; absent, its default for the device. */
+    readonly appiumVersion?: string | undefined;
+}
+/**
+ * TestMu AI devices for `mobile({ device: testmu({ device, osVersion, app }) })`:
+ * one hosted device and isolated agent-device daemon per worker slot. Allocating
+ * the lease starts the TestMu AI session, which installs `app`; releasing it
+ * stops the daemon, which ends the session.
+ */
+export declare function testmu(options: TestmuOptions): DeviceProvider;

package/dist/provider.js

@@ -0,0 +1,221 @@
+/**
+ * TestMu AI's hosted Android emulators, iOS simulators, and real devices as a
+ * `DeviceProvider` for the mobile engine, through agent-device's
+ * `@agent-device/testmu` plugin: each lease comes from its own agent-device
+ * daemon, which runs the session over TestMu AI's Appium hub.
+ */
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { ConfigurationError, rejectUnknownKeys } from 'e2e/engine';
+import { testmuCredentials } from './credentials.js';
+import { assertDriverVersion, installPlugin, startDriver, stopDriver } from './daemon.js';
+import { LEASE_TTL_MS, startHeartbeat } from './heartbeat.js';
+import { findSession, sessionVideoUrl, testmuApiEndpoint } from './sessions.js';
+/** agent-device's name for TestMu AI, as the lease provider and the tenant. */
+const PROVIDER = 'testmu';
+/** The dashboard project sessions are grouped under when `project` is absent. */
+const DEFAULT_PROJECT = 'e2e';
+const DEVICE_TYPES = new Set(['virtual', 'real']);
+const ORIENTATIONS = new Set(['portrait', 'landscape']);
+/** Each device-feature option and the agent-device lease key it is allocated under. */
+const DEVICE_FEATURES = {
+    orientation: 'providerDeviceOrientation',
+    geoLocation: 'providerGeoLocation',
+    timezone: 'providerTimezone',
+    language: 'providerLanguage',
+    locale: 'providerLocale',
+    appiumVersion: 'providerAppiumVersion',
+};
+/** The options that are strings when given, checked at config load. */
+const OPTIONAL_STRING_KEYS = ['project', 'build', 'sessionName', ...Object.keys(DEVICE_FEATURES)];
+/** Every option `testmu()` takes, kept equal to `TestmuOptions` by the compiler. */
+const OPTION_KEYS = Object.keys({
+    device: true,
+    osVersion: true,
+    app: true,
+    deviceType: true,
+    project: true,
+    build: true,
+    sessionName: true,
+    orientation: true,
+    geoLocation: true,
+    timezone: true,
+    language: true,
+    locale: true,
+    appiumVersion: true,
+});
+function driverEnv(env, home, credentials) {
+    const result = { ...env };
+    // A user's daemon settings must not select a different daemon or plugin home.
+    for (const key of Object.keys(result)) {
+        // Keep the user's security policy on both the daemon and its clients.
+        if (key === 'AGENT_DEVICE_DAEMON_POLICY')
+            continue;
+        if (key.startsWith('AGENT_DEVICE_'))
+            delete result[key];
+    }
+    result.AGENT_DEVICE_HOME = home;
+    result.LT_USERNAME = credentials.username;
+    result.LT_ACCESS_KEY = credentials.accessKey;
+    return result;
+}
+/**
+ * TestMu AI devices for `mobile({ device: testmu({ device, osVersion, app }) })`:
+ * one hosted device and isolated agent-device daemon per worker slot. Allocating
+ * the lease starts the TestMu AI session, which installs `app`; releasing it
+ * stops the daemon, which ends the session.
+ */
+export function testmu(options) {
+    rejectUnknownKeys('testmu()', options, OPTION_KEYS);
+    for (const key of ['device', 'osVersion', 'app']) {
+        const value = options[key];
+        if (typeof value !== 'string' || value.trim() === '') {
+            throw new ConfigurationError('INVALID_CONFIG', `testmu: \`${key}\` is required, as a non-empty string`);
+        }
+    }
+    // Only an absent value takes the default: `null` from a JavaScript config is refused like any other.
+    const deviceType = options.deviceType === undefined ? 'virtual' : options.deviceType;
+    if (!DEVICE_TYPES.has(deviceType)) {
+        throw new ConfigurationError('INVALID_CONFIG', `testmu: \`deviceType\` must be 'virtual' or 'real', not ${JSON.stringify(deviceType)}`);
+    }
+    for (const key of OPTIONAL_STRING_KEYS) {
+        const value = options[key];
+        if (value !== undefined && (typeof value !== 'string' || value.trim() === '')) {
+            throw new ConfigurationError('INVALID_CONFIG', `testmu: \`${key}\` must be a non-empty string`);
+        }
+    }
+    if (options.orientation !== undefined && !ORIENTATIONS.has(options.orientation)) {
+        throw new ConfigurationError('INVALID_CONFIG', `testmu: \`orientation\` must be 'portrait' or 'landscape', not ${JSON.stringify(options.orientation)}`);
+    }
+    const deviceFeatures = {};
+    for (const [key, leaseKey] of Object.entries(DEVICE_FEATURES)) {
+        const value = options[key];
+        if (value !== undefined)
+            deviceFeatures[leaseKey] = value;
+    }
+    const { device, osVersion, app, project, build, sessionName } = options;
+    const held = new Map();
+    /** One release per lease, shared by every caller; a failed one may be tried again. */
+    function release(id, resource, signal) {
+        resource.releasing ??= (async () => {
+            await resource.stopHeartbeat?.();
+            await stopDriver(resource.stateDir, resource.env, signal);
+            await rm(resource.dir, { recursive: true, force: true });
+            if (id !== undefined)
+                held.delete(id);
+        })();
+        resource.releasing.catch(() => { resource.releasing = undefined; });
+        return resource.releasing;
+    }
+    return {
+        name: PROVIDER,
+        async acquire(request) {
+            assertDriverVersion(request.agentDeviceVersion);
+            if (request.appPath !== undefined)
+                throw new Error("TestMu AI installs the app from `app`; leave the target's `app.appPath` out");
+            const credentials = testmuCredentials(request.env);
+            request.signal.throwIfAborted();
+            const dir = await mkdtemp(join(tmpdir(), 'e2e-testmu-'));
+            const home = join(dir, 'home');
+            const resource = { dir, stateDir: join(dir, 'state'), env: driverEnv(request.env, home, credentials) };
+            const leaseBackend = request.platform === 'ios' ? 'ios-instance' : 'android-instance';
+            const selectors = {
+                platform: request.platform,
+                target: 'mobile',
+                device,
+                providerOsVersion: osVersion,
+                providerApp: appSource(app, request.projectRoot),
+                providerDeviceType: deviceType,
+                providerProject: project ?? DEFAULT_PROJECT,
+                providerBuild: build ?? request.runId,
+                providerSessionName: slotSessionName(sessionName, request),
+                ...deviceFeatures,
+            };
+            let id;
+            try {
+                await installPlugin(home);
+                const grant = await startDriver({
+                    stateDir: resource.stateDir,
+                    allocate: {
+                        tenant: PROVIDER,
+                        runId: request.runId,
+                        leaseBackend,
+                        leaseProvider: PROVIDER,
+                        ttlMs: LEASE_TTL_MS,
+                        // The engine closes a worker's session when it retires the worker; without this, closing it ends the TestMu AI session mid-run.
+                        retainOnClose: true,
+                        ...selectors,
+                    },
+                }, resource.env);
+                id = grant.leaseId;
+                held.set(id, resource);
+                if (request.signal.aborted)
+                    throw new Error('cancelled');
+                if (!grant.retainOnClose)
+                    throw new Error('agent-device did not keep the lease through session close, so the session would end when a worker retires');
+                const scope = { tenant: grant.tenantId, runId: grant.runId, leaseId: grant.leaseId, leaseBackend, leaseProvider: PROVIDER };
+                resource.stopHeartbeat = await startHeartbeat(resource.stateDir, scope, request.log);
+                request.log(`lease ${id}: ${device}, ${request.platform} ${osVersion} (${deviceType}); session ${selectors.providerSessionName} started`);
+                // The worker's client is created with these fields: the scope picks the lease, and the selectors match the session it holds.
+                return { id, client: { stateDir: resource.stateDir, ...scope, ...selectors } };
+            }
+            catch (cause) {
+                // The engine releases only leases `acquire` returned.
+                try {
+                    await release(id, resource, AbortSignal.timeout(30_000));
+                }
+                catch (cleanup) {
+                    throw new AggregateError([cause, cleanup], `TestMu AI lease failed: ${messageOf(cause)}; cleanup also failed: ${messageOf(cleanup)}`, { cause: cleanup });
+                }
+                throw cause;
+            }
+        },
+        async release(lease, context) {
+            const resource = held.get(lease.id);
+            if (resource)
+                await release(lease.id, resource, context.signal);
+        },
+        // Runs in the worker, from the lease alone. TestMu AI records the whole session, so its video starts when the session did.
+        async record(lease, context) {
+            const calledAt = new Date().toISOString();
+            const session = sessionRef(lease);
+            if (session === undefined)
+                throw new Error(`lease ${lease.id} carries no TestMu AI build and session name to find its recording by`);
+            const credentials = testmuCredentials(context.env);
+            const endpoint = testmuApiEndpoint(context.env);
+            const found = await findSession(endpoint, credentials, session, context.signal);
+            return {
+                // Without a usable start time from TestMu AI, the moment recording was asked for is the closest known bound.
+                startedAt: found.startedAt ?? calledAt,
+                stop: async ({ signal }) => ({ url: await sessionVideoUrl(endpoint, credentials, found.id, session, signal), mediaType: 'video/mp4' }),
+            };
+        },
+    };
+}
+/**
+ * The dashboard name of a slot's session, unique among the run's slots of the
+ * target so `record` can find the session by it within its build.
+ */
+function slotSessionName(sessionName, { runId, targetName, slot, slots }) {
+    if (sessionName === undefined)
+        return `e2e-${runId}-${targetName}-${slot + 1}`;
+    return slots > 1 ? `${sessionName}-${slot + 1}` : sessionName;
+}
+/** `app` as the daemon reads it: an `lt://` id or URL as written, a local path resolved against the project root, never the daemon's working directory. */
+function appSource(app, projectRoot) {
+    if (isAbsolute(app) || /^[a-z][a-z0-9+.-]*:\/\//i.test(app))
+        return app;
+    return resolve(projectRoot, app);
+}
+/** The build and session name `acquire` put on a lease's `client`, when they are there. */
+function sessionRef({ client }) {
+    const build = client?.providerBuild;
+    const sessionName = client?.providerSessionName;
+    if (typeof build !== 'string' || build === '' || typeof sessionName !== 'string' || sessionName === '')
+        return undefined;
+    return { build, sessionName };
+}
+function messageOf(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}

package/dist/sessions.d.ts

@@ -0,0 +1,33 @@
+/**
+ * TestMu AI's mobile automation sessions API over `fetch`, the one
+ * agent-device's `@agent-device/testmu` plugin reads session artifacts from: finds a
+ * session by its build and name, with its start time, and reads the URL of
+ * its video.
+ */
+import type { TestmuCredentials } from './credentials.ts';
+/** A session the recording covers, as the lease named it. */
+export interface SessionRef {
+    readonly build: string;
+    readonly sessionName: string;
+}
+/**
+ * The sessions API at `TESTMU_API_ENDPOINT` from the run's environment, else
+ * TestMu AI's own. Throws, without repeating the value, when the override is
+ * not an http(s) URL or carries a username or password, which a failed
+ * request would otherwise put in its error message.
+ */
+export declare function testmuApiEndpoint(env: Readonly<Record<string, string | undefined>>): string;
+/** A session the list found: its `test_id`, and when it started, if the list says. */
+export interface FoundSession {
+    readonly id: string;
+    /** ISO timestamp in UTC; `undefined` when the row has no start time or one that does not parse. */
+    readonly startedAt: string | undefined;
+}
+/**
+ * The newest session named `sessionName` in `build` that the credentials'
+ * user started, reading the list a page at a time. Every request is bounded by `REQUEST_TIMEOUT_MS` and `signal`,
+ * and errors name the build and the session, never the credentials or a URL.
+ */
+export declare function findSession(endpoint: string, credentials: TestmuCredentials, { build, sessionName }: SessionRef, signal: AbortSignal): Promise<FoundSession>;
+/** The `video_url` of session `id`'s details, bounded and named as `findSession` is. */
+export declare function sessionVideoUrl(endpoint: string, credentials: TestmuCredentials, id: string, { build, sessionName }: SessionRef, signal: AbortSignal): Promise<string>;

package/dist/sessions.js

@@ -0,0 +1,132 @@
+/**
+ * TestMu AI's mobile automation sessions API over `fetch`, the one
+ * agent-device's `@agent-device/testmu` plugin reads session artifacts from: finds a
+ * session by its build and name, with its start time, and reads the URL of
+ * its video.
+ */
+import { ConfigurationError } from 'e2e/engine';
+/** The API's base, as agent-device's `TESTMU_API_ENDPOINT` sets it. */
+const DEFAULT_API_ENDPOINT = 'https://mobile-api.lambdatest.com/mobile-automation/api/v1';
+const REQUEST_TIMEOUT_MS = 15_000;
+/** Sessions the list asks for at once. */
+const PAGE_SIZE = 50;
+/** Pages the lookup reads before it gives up on a build: the list is newest first, so the session is near the top. */
+const MAX_PAGES = 10;
+/**
+ * The sessions API at `TESTMU_API_ENDPOINT` from the run's environment, else
+ * TestMu AI's own. Throws, without repeating the value, when the override is
+ * not an http(s) URL or carries a username or password, which a failed
+ * request would otherwise put in its error message.
+ */
+export function testmuApiEndpoint(env) {
+    const override = env['TESTMU_API_ENDPOINT']?.trim();
+    if (override === undefined || override === '')
+        return DEFAULT_API_ENDPOINT;
+    if (!URL.canParse(override) || !/^https?:$/.test(new URL(override).protocol))
+        throw new ConfigurationError('INVALID_CONFIG', 'TESTMU_API_ENDPOINT is not an http(s) URL');
+    const url = new URL(override);
+    if (url.username !== '' || url.password !== '') {
+        throw new ConfigurationError('INVALID_CONFIG', 'TESTMU_API_ENDPOINT must not carry a username or password; set LT_USERNAME and LT_ACCESS_KEY instead');
+    }
+    return override.replace(/\/+$/, '');
+}
+/**
+ * The newest session named `sessionName` in `build` that the credentials'
+ * user started, reading the list a page at a time. Every request is bounded by `REQUEST_TIMEOUT_MS` and `signal`,
+ * and errors name the build and the session, never the credentials or a URL.
+ */
+export async function findSession(endpoint, credentials, { build, sessionName }, signal) {
+    const auth = basicAuth(credentials);
+    const what = `TestMu AI session lookup for build ${JSON.stringify(build)}`;
+    for (let page = 0; page < MAX_PAGES; page += 1) {
+        const url = new URL(`${endpoint}/sessions`);
+        url.searchParams.set('build', build);
+        // The build filter spans the whole organization; a build name another user's run shares would find their session.
+        url.searchParams.set('username', credentials.username);
+        url.searchParams.set('limit', String(PAGE_SIZE));
+        url.searchParams.set('offset', String(page * PAGE_SIZE));
+        const body = await getJson(url, auth, signal, what);
+        // An empty page comes back as `data: null`.
+        const rows = body['data'] ?? [];
+        if (!Array.isArray(rows))
+            throw new Error(`${what} failed: no session list in the response`);
+        for (const row of rows) {
+            const { name, test_id: id, start_timestamp: start } = asRecord(row) ?? {};
+            if (name === sessionName && typeof id === 'string' && id !== '')
+                return { id, startedAt: utcTimestamp(start) };
+        }
+        if (rows.length < PAGE_SIZE)
+            break;
+    }
+    throw new Error(`TestMu AI has no session named ${JSON.stringify(sessionName)} in build ${JSON.stringify(build)}`);
+}
+/** The `video_url` of session `id`'s details, bounded and named as `findSession` is. */
+export async function sessionVideoUrl(endpoint, credentials, id, { build, sessionName }, signal) {
+    const what = `TestMu AI session ${id} (${JSON.stringify(sessionName)}, build ${JSON.stringify(build)})`;
+    const body = await getJson(new URL(`${endpoint}/sessions/${encodeURIComponent(id)}`), basicAuth(credentials), signal, `${what} details`);
+    const details = asRecord(body['data']);
+    const videoUrl = details?.['video_url'];
+    if (typeof videoUrl !== 'string' || !isHttpUrl(videoUrl))
+        throw new Error(`${what} reports no video URL`);
+    return videoUrl;
+}
+const TIMESTAMP = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2}(?:\.\d+)?)(Z|[+-]\d{2}:\d{2})?$/;
+/**
+ * A `start_timestamp` as an ISO timestamp in UTC. The API formats the
+ * database time as RFC 3339 with its zone; a time without one is read as UTC,
+ * the zone the API's database driver reads it in.
+ */
+function utcTimestamp(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const match = TIMESTAMP.exec(value.trim());
+    if (match === null)
+        return undefined;
+    const [, date, time, zone] = match;
+    const ms = Date.parse(`${date}T${time}${zone ?? 'Z'}`);
+    return Number.isNaN(ms) ? undefined : new Date(ms).toISOString();
+}
+function basicAuth({ username, accessKey }) {
+    return `Basic ${Buffer.from(`${username}:${accessKey}`).toString('base64')}`;
+}
+/** One authenticated GET answered with a JSON object; anything else throws, as `what`, with the HTTP status and the API's message. */
+async function getJson(url, auth, signal, what) {
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(), REQUEST_TIMEOUT_MS);
+    let response;
+    let text;
+    try {
+        response = await fetch(url, { headers: { Authorization: auth, Accept: 'application/json' }, signal: AbortSignal.any([signal, timeout.signal]) });
+        text = await response.text();
+    }
+    catch (cause) {
+        if (signal.aborted)
+            throw new Error(`${what} cancelled`, { cause });
+        if (timeout.signal.aborted)
+            throw new Error(`${what} got no answer within ${REQUEST_TIMEOUT_MS / 1000} s`, { cause });
+        throw new Error(`${what} failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    let body;
+    try {
+        body = asRecord(JSON.parse(text));
+    }
+    catch {
+        body = undefined;
+    }
+    if (body === undefined)
+        throw new Error(`${what} failed: HTTP ${response.status}, not JSON`);
+    if (!response.ok) {
+        const message = body['message'];
+        throw new Error(`${what} failed: HTTP ${response.status}${typeof message === 'string' && message !== '' ? ` (${message.slice(0, 200)})` : ''}`);
+    }
+    return body;
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : undefined;
+}
+function isHttpUrl(value) {
+    return URL.canParse(value) && /^https?:$/.test(new URL(value).protocol);
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@e2e-dev/testmu",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.0",
+  "description": "TestMu AI (formerly LambdaTest) hosted Android emulators, iOS simulators, and real devices for e2e mobile tests",
+  "keywords": [
+    "e2e",
+    "end-to-end",
+    "testing",
+    "mobile-testing",
+    "testmu",
+    "lambdatest",
+    "device-cloud",
+    "real-devices",
+    "ios-simulator",
+    "android-emulator",
+    "agent-device",
+    "ci"
+  ],
+  "license": "Apache-2.0",
+  "contributors": [
+    "Aman Kansal (https://github.com/amankansal-lt)"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tester-army/e2e.git",
+    "directory": "packages/testmu"
+  },
+  "bugs": {
+    "url": "https://github.com/tester-army/e2e/issues"
+  },
+  "homepage": "https://github.com/tester-army/e2e/tree/main/packages/testmu#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "tag": "latest"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "NOTICE"
+  ],
+  "peerDependencies": {
+    "@e2e-dev/mobile": ">=0.11.1 <1",
+    "e2e": ">=0.15.0 <1"
+  },
+  "devDependencies": {
+    "@e2e-dev/mobile": "0.12.2",
+    "@types/node": "26.6.2",
+    "e2e": "0.21.1",
+    "typescript": "7.0.2",
+    "vitest": "5.0.1"
+  },
+  "engines": {
+    "node": "^22.22.3 || >=24.8.0"
+  },
+  "dependencies": {
+    "@agent-device/testmu": "0.21.28",
+    "agent-device": "0.21.28"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc --project tsconfig.build.json && node ../../scripts/stamp-dist.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run tests/unit"
+  }
 }