@taqwright/taqwright 0.0.24

package/dist/inspector/session.d.ts

@@ -0,0 +1,84 @@
+import type { ChildProcess } from 'node:child_process';
+import type { Client as WebDriverClient } from 'webdriver';
+import { Platform, type DeviceProvider, type DeviceOrientation } from '../types/index.js';
+import { Recorder, type RecordedAction } from './recorder.js';
+export declare function applyLocalCapabilityDefaults(capabilities: Record<string, unknown>, platformName: string): void;
+export interface AppiumOpts {
+    host: string;
+    port: number;
+    path: string;
+    protocol?: 'http' | 'https';
+    user?: string;
+    key?: string;
+}
+export interface InspectorDefaults {
+    project?: string;
+    appium: AppiumOpts;
+    capabilities: Record<string, unknown>;
+    projectRoot?: string;
+    testDir?: string;
+    recordOnConnect?: boolean;
+}
+export interface CloudConnectRequest {
+    provider: 'browserstack' | 'lambdatest';
+    user: string;
+    key: string;
+    platform: 'android' | 'ios';
+    deviceName: string;
+    osVersion: string;
+    orientation?: DeviceOrientation;
+    appUrl: string;
+    appBundleId?: string;
+    capabilities?: Record<string, unknown>;
+    projectName?: string;
+}
+export interface ConnectRequest {
+    appium?: AppiumOpts;
+    capabilities?: Record<string, unknown>;
+    cloud?: CloudConnectRequest;
+}
+export declare class InspectorSession {
+    readonly defaults: InspectorDefaults;
+    driver: WebDriverClient | undefined;
+    platform: Platform | undefined;
+    appiumProc: ChildProcess | undefined;
+    appium: AppiumOpts | undefined;
+    lastCapabilities: Record<string, unknown> | undefined;
+    activeProvider: DeviceProvider | null;
+    readonly recorder: Recorder;
+    recording: boolean;
+    currentContext: string;
+    private aborting;
+    private deviceQueue;
+    suggestGen: number;
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
+    attached: boolean;
+    private resumeResolver;
+    private _resumeRequested;
+    get resumeRequested(): Promise<void>;
+    requestResume(): void;
+    recordIf(action: RecordedAction): void;
+    listContexts(): Promise<{
+        contexts: string[];
+        current: string;
+    }>;
+    switchContext(name: string): Promise<void>;
+    constructor(defaults: InspectorDefaults);
+    isConnected(): boolean;
+    attachDriver(driver: WebDriverClient, platform: Platform, capabilities?: Record<string, unknown>): void;
+    ensureAppium(opts: AppiumOpts): Promise<{
+        started: boolean;
+        alreadyRunning: boolean;
+    }>;
+    restartAppium(opts: AppiumOpts): Promise<{
+        started: boolean;
+        alreadyRunning: boolean;
+    }>;
+    connect(req: ConnectRequest): Promise<void>;
+    private connectLocal;
+    private connectCloud;
+    private abortIfCancelled;
+    cancelConnect(): void;
+    disconnect(): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/inspector/session.js

@@ -0,0 +1,262 @@
+import WebDriver from 'webdriver';
+import { Platform, } from '../types/index.js';
+import { isPortOpen } from '../auto-appium.js';
+import { omitLocalEmulatorCaps } from '../capabilities.js';
+import { startAppiumServer, killAppiumOnPort } from '../providers/appium.js';
+import { createDeviceProvider } from '../providers/index.js';
+import { Recorder } from './recorder.js';
+export function applyLocalCapabilityDefaults(capabilities, platformName) {
+    if (platformName === 'ios' &&
+        !('appium:forceSimulatorSoftwareKeyboardPresence' in capabilities)) {
+        capabilities['appium:forceSimulatorSoftwareKeyboardPresence'] = true;
+    }
+    if (platformName === 'android' && !('appium:chromedriverAutodownload' in capabilities)) {
+        capabilities['appium:chromedriverAutodownload'] = true;
+    }
+    if (platformName === 'android' && !('appium:nativeWebScreenshot' in capabilities)) {
+        capabilities['appium:nativeWebScreenshot'] = true;
+    }
+}
+export class InspectorSession {
+    defaults;
+    driver;
+    platform;
+    appiumProc;
+    appium;
+    lastCapabilities;
+    activeProvider = null;
+    recorder = new Recorder();
+    recording = false;
+    currentContext = 'NATIVE_APP';
+    aborting = false;
+    deviceQueue = Promise.resolve();
+    suggestGen = 0;
+    runExclusive(fn) {
+        const run = this.deviceQueue.then(fn, fn);
+        this.deviceQueue = run.then(() => { }, () => { });
+        return run;
+    }
+    attached = false;
+    resumeResolver = null;
+    _resumeRequested = null;
+    get resumeRequested() {
+        if (!this._resumeRequested) {
+            this._resumeRequested = new Promise((resolve) => {
+                this.resumeResolver = resolve;
+            });
+        }
+        return this._resumeRequested;
+    }
+    requestResume() {
+        this.resumeResolver?.();
+    }
+    recordIf(action) {
+        if (this.recording)
+            this.recorder.push(action);
+    }
+    async listContexts() {
+        if (!this.driver)
+            throw new Error('not connected');
+        const contexts = (await this.driver.getAppiumContexts());
+        try {
+            this.currentContext = (await this.driver.getAppiumContext());
+        }
+        catch {
+        }
+        return { contexts, current: this.currentContext };
+    }
+    async switchContext(name) {
+        if (!this.driver)
+            throw new Error('not connected');
+        await this.driver.switchAppiumContext(name);
+        this.currentContext = name;
+        this.recordIf({ kind: 'switchContext', context: name });
+    }
+    constructor(defaults) {
+        this.defaults = defaults;
+        this.appium = { ...defaults.appium };
+    }
+    isConnected() {
+        return !!this.driver;
+    }
+    attachDriver(driver, platform, capabilities) {
+        if (this.driver)
+            throw new Error('attachDriver: already connected');
+        this.driver = driver;
+        this.platform = platform;
+        this.lastCapabilities = capabilities ?? {};
+        this.activeProvider = null;
+        this.attached = true;
+        this.currentContext = 'NATIVE_APP';
+    }
+    async ensureAppium(opts) {
+        this.appium = opts;
+        if (await isPortOpen(opts.host, opts.port)) {
+            return { started: false, alreadyRunning: true };
+        }
+        if (this.appiumProc && !this.appiumProc.killed) {
+            for (let i = 0; i < 60; i++) {
+                if (await isPortOpen(opts.host, opts.port)) {
+                    return { started: true, alreadyRunning: false };
+                }
+                await sleep(500);
+            }
+        }
+        this.appiumProc = await startAppiumServer('inspector', {
+            host: opts.host,
+            port: opts.port,
+            basePath: opts.path,
+        });
+        return { started: true, alreadyRunning: false };
+    }
+    async restartAppium(opts) {
+        if (this.isConnected()) {
+            await this.disconnect().catch(() => { });
+        }
+        if (this.appiumProc && !this.appiumProc.killed) {
+            this.appiumProc.kill();
+        }
+        this.appiumProc = undefined;
+        await killAppiumOnPort(opts.port);
+        for (let i = 0; i < 20; i++) {
+            if (!(await isPortOpen(opts.host, opts.port)))
+                break;
+            await sleep(250);
+        }
+        return this.ensureAppium(opts);
+    }
+    async connect(req) {
+        if (this.driver) {
+            throw new Error('already connected — disconnect first');
+        }
+        this.aborting = false;
+        if (req.cloud) {
+            await this.connectCloud(req.cloud);
+        }
+        else {
+            if (!req.appium || !req.capabilities) {
+                throw new Error('Local connect requires { appium, capabilities }.');
+            }
+            await this.connectLocal(req.appium, req.capabilities);
+        }
+        if (this.defaults.recordOnConnect) {
+            this.recorder.clear();
+            this.recording = true;
+        }
+    }
+    async connectLocal(appium, capabilities) {
+        this.appium = appium;
+        const platformName = String(capabilities['platformName'] ?? '').toLowerCase();
+        this.platform = platformName === 'ios' ? Platform.IOS : Platform.ANDROID;
+        applyLocalCapabilityDefaults(capabilities, platformName);
+        this.lastCapabilities = capabilities;
+        this.activeProvider = null;
+        this.driver = await WebDriver.newSession({
+            hostname: appium.host,
+            port: appium.port,
+            path: appium.path,
+            protocol: appium.protocol ?? 'http',
+            logLevel: 'warn',
+            capabilities,
+        });
+        this.currentContext = 'NATIVE_APP';
+        await this.abortIfCancelled();
+    }
+    async connectCloud(cloud) {
+        if (!cloud.appUrl) {
+            throw new Error('Cloud connect requires an app URL (bs://… or lt://…).');
+        }
+        if (!cloud.user || !cloud.key) {
+            throw new Error(`${cloud.provider} username + access key are required.`);
+        }
+        if (cloud.provider === 'browserstack') {
+            process.env.BROWSERSTACK_USERNAME = cloud.user;
+            process.env.BROWSERSTACK_ACCESS_KEY = cloud.key;
+        }
+        else {
+            process.env.LAMBDATEST_USERNAME = cloud.user;
+            process.env.LAMBDATEST_ACCESS_KEY = cloud.key;
+        }
+        const platform = cloud.platform === 'ios' ? Platform.IOS : Platform.ANDROID;
+        const userCloudCaps = omitLocalEmulatorCaps(cloud.capabilities ?? {});
+        const permKeys = cloud.provider === 'browserstack'
+            ? ['appium:autoGrantPermissions', 'appium:autoAcceptAlerts']
+            : ['autoGrantPermissions', 'autoAcceptAlerts'];
+        const codegenPermOff = {};
+        for (const k of permKeys) {
+            if (!(k in userCloudCaps))
+                codegenPermOff[k] = false;
+        }
+        const use = {
+            platform,
+            device: {
+                provider: cloud.provider,
+                name: cloud.deviceName,
+                osVersion: cloud.osVersion,
+                orientation: cloud.orientation ?? 'portrait',
+            },
+            buildPath: cloud.appUrl,
+            appBundleId: cloud.appBundleId,
+            capabilities: { ...codegenPermOff, ...userCloudCaps },
+        };
+        const provider = createDeviceProvider(use, cloud.projectName ?? 'inspector');
+        if (provider.globalSetup)
+            await provider.globalSetup();
+        const handle = await provider.getDevice();
+        this.activeProvider = provider;
+        this.driver = handle.driver;
+        this.platform = platform;
+        this.lastCapabilities = userCloudCaps;
+        this.currentContext = 'NATIVE_APP';
+        await this.abortIfCancelled();
+    }
+    async abortIfCancelled() {
+        if (!this.aborting)
+            return;
+        await this.disconnect();
+        throw new Error('connect cancelled');
+    }
+    cancelConnect() {
+        this.aborting = true;
+        if (this.driver)
+            void this.disconnect();
+    }
+    async disconnect() {
+        if (!this.driver)
+            return;
+        if (this.activeProvider?.syncTestDetails) {
+            try {
+                await this.activeProvider.syncTestDetails({
+                    status: 'passed',
+                    reason: 'taqwright inspector ended',
+                });
+            }
+            catch {
+            }
+        }
+        if (!this.attached) {
+            try {
+                await this.driver.deleteSession();
+            }
+            catch {
+            }
+        }
+        this.driver = undefined;
+        this.platform = undefined;
+        this.lastCapabilities = undefined;
+        this.activeProvider = null;
+        this.attached = false;
+        this.recording = false;
+        this.currentContext = 'NATIVE_APP';
+    }
+    async cleanup() {
+        await this.disconnect();
+        if (this.appiumProc && !this.appiumProc.killed) {
+            this.appiumProc.kill();
+            this.appiumProc = undefined;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}