@xenon-device-management/xenon 2.13.0 → 2.13.2

package/lib/test/unit/lease-held-phone.spec.js

@@ -0,0 +1,196 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const chai_1 = __importDefault(require("chai"));
+const sinon_1 = __importDefault(require("sinon"));
+const sinon_chai_1 = __importDefault(require("sinon-chai"));
+const ActiveLeases = __importStar(require("../../src/services/lease/activeLeases"));
+const DeviceUtils = __importStar(require("../../src/device-utils"));
+const DeviceService = __importStar(require("../../src/data-service/device-service"));
+const db_1 = require("../../src/data-service/db");
+const device_service_1 = require("../../src/data-service/device-service");
+const IPluginArgs_1 = require("../../src/interfaces/IPluginArgs");
+const test_container_1 = require("../helpers/test-container");
+const loki_stores_1 = require("../helpers/loki-stores");
+const scratch_database_1 = require("../helpers/scratch-database");
+chai_1.default.use(sinon_chai_1.default);
+const expect = chai_1.default.expect;
+// A phone an SDK lease holds stays its lease's until the lease ends. Its only
+// lock is `busy`, and three things used to undo that: the idle sweeper (which
+// read the lease's creation as the phone's last command), a lease-bound
+// session's release, and allocation, which offered only the first candidate
+// to the lock and so stalled on a leased phone while others were free.
+describe('a phone an SDK lease holds', () => {
+    (0, loki_stores_1.useLokiStores)();
+    const scratch = (0, scratch_database_1.useScratchDatabase)();
+    const sandbox = sinon_1.default.createSandbox();
+    const pluginArgs = Object.assign({}, IPluginArgs_1.DefaultPluginArgs, {
+        iosDeviceType: 'both',
+        androidDeviceType: 'both',
+    });
+    const phone = (udid, over = {}) => (Object.assign({ udid, name: udid, platform: 'android', sdk: '13', host: 'http://127.0.0.1:4723', busy: false, offline: false, userBlocked: false, state: 'device', deviceType: 'emulator', realDevice: false, systemPort: 57000, totalUtilizationTimeMilliSec: 0, sessionStartTime: 0 }, over));
+    const lease = (udid, over = {}) => scratch.db.lease.create({
+        data: Object.assign({ tokenHash: 'h', deviceUdid: udid, deviceHost: 'http://127.0.0.1:4723', actorId: 'key_owner', status: 'active', expiresAt: Date.now() + 600000, lastHeartbeatAt: Date.now(), allocatedPorts: '{}', capabilityBag: '{}' }, over),
+    });
+    const row = (udid) => __awaiter(void 0, void 0, void 0, function* () { return (yield db_1.XenonDatabase.DeviceModel).findOne({ udid }); });
+    const setRow = (udid, fields) => __awaiter(void 0, void 0, void 0, function* () {
+        return (yield db_1.XenonDatabase.DeviceModel)
+            .chain()
+            .find({ udid })
+            .update((d) => Object.assign(d, fields));
+    });
+    before(() => __awaiter(void 0, void 0, void 0, function* () {
+        yield (0, test_container_1.resetTestContainer)();
+        yield (0, test_container_1.setupTestContainer)();
+    }));
+    after(() => (0, test_container_1.resetTestContainer)());
+    beforeEach(() => __awaiter(void 0, void 0, void 0, function* () {
+        (yield db_1.XenonDatabase.DeviceModel).removeDataOnly();
+        yield scratch.db.lease.deleteMany({});
+        (0, test_container_1.createTestXenonManager)(Object.assign({}, pluginArgs, { maxSessions: 10, platform: 'android' }));
+        sandbox.stub(DeviceUtils, 'setUtilizationTime').resolves();
+    }));
+    afterEach(() => sandbox.restore());
+    describe('the idle sweeper', () => {
+        const idle = { busy: true, lastCmdExecutedAt: Date.now() - 600000 };
+        it('leaves a leased phone with no session alone', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield (0, device_service_1.addNewDevice)([phone('leased-1')]);
+            yield setRow('leased-1', idle);
+            yield lease('leased-1');
+            const unblock = sandbox.spy(DeviceService, 'unblockDevice');
+            yield DeviceUtils.releaseBlockedDevices(20);
+            expect(unblock).not.to.have.been.called;
+            expect((yield row('leased-1')).busy).to.equal(true);
+        }));
+        it('frees it once the lease has lapsed', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield (0, device_service_1.addNewDevice)([phone('lapsed-1')]);
+            yield setRow('lapsed-1', idle);
+            yield lease('lapsed-1', { expiresAt: Date.now() - 1000 });
+            const unblock = sandbox.spy(DeviceService, 'unblockDevice');
+            yield DeviceUtils.releaseBlockedDevices(20);
+            expect(unblock).to.have.been.calledWith('lapsed-1');
+        }));
+        it('skips its tick when it cannot tell which phones are leased', () => __awaiter(void 0, void 0, void 0, function* () {
+            // Failing open would free every leased phone: their last command is
+            // when the lease was taken.
+            yield (0, device_service_1.addNewDevice)([phone('plain-3')]);
+            yield setRow('plain-3', idle);
+            sandbox.stub(ActiveLeases, 'activeLeasesByDevice').rejects(new Error('db down'));
+            const unblock = sandbox.spy(DeviceService, 'unblockDevice');
+            yield DeviceUtils.releaseBlockedDevices(20);
+            expect(unblock).not.to.have.been.called;
+        }));
+        it('still frees an idle phone nobody leases', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield (0, device_service_1.addNewDevice)([phone('plain-1')]);
+            yield setRow('plain-1', idle);
+            const unblock = sandbox.spy(DeviceService, 'unblockDevice');
+            yield DeviceUtils.releaseBlockedDevices(20);
+            expect(unblock).to.have.been.calledWith('plain-1');
+        }));
+    });
+    describe("a lease-bound session's release", () => {
+        it('hands the phone back to the lease, still busy', () => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            yield (0, device_service_1.addNewDevice)([phone('leased-2')]);
+            yield setRow('leased-2', { busy: true, session_id: 'sess-1' });
+            yield lease('leased-2');
+            expect(yield DeviceService.releaseSessionDevice('leased-2', 'http://127.0.0.1:4723', 'sess-1')).to.be.true;
+            const after = yield row('leased-2');
+            expect((_a = after.session_id) !== null && _a !== void 0 ? _a : null).to.equal(null);
+            expect(after.busy).to.equal(true);
+        }));
+        it('undoes the hand-back when the lease ended meanwhile', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield (0, device_service_1.addNewDevice)([phone('racing-1')]);
+            yield setRow('racing-1', { busy: true, session_id: 'sess-3' });
+            // Live at the first check, gone by the second.
+            const lookup = sandbox.stub(ActiveLeases, 'activeLeaseOn');
+            lookup.onFirstCall().resolves({ id: 'l', actorId: 'k' });
+            lookup.resolves(null);
+            yield DeviceService.releaseSessionDevice('racing-1', 'http://127.0.0.1:4723', 'sess-3');
+            expect(lookup).to.have.been.calledTwice;
+            expect((yield row('racing-1')).busy).to.equal(false);
+        }));
+        it('frees a phone with no lease, as before', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield (0, device_service_1.addNewDevice)([phone('plain-2')]);
+            yield setRow('plain-2', { busy: true, session_id: 'sess-2' });
+            yield DeviceService.releaseSessionDevice('plain-2', 'http://127.0.0.1:4723', 'sess-2');
+            expect((yield row('plain-2')).busy).to.equal(false);
+        }));
+    });
+    describe('allocation for a session', () => {
+        const caps = (udid) => ({
+            alwaysMatch: Object.assign({ platformName: 'android' }, (udid ? { 'appium:udid': udid } : {})),
+            firstMatch: [{}],
+        });
+        it("never locks a reserved phone's twin on another host in its place", () => __awaiter(void 0, void 0, void 0, function* () {
+            // Same udid on two hosts: the reserved row is listed first.
+            yield (0, device_service_1.addNewDevice)([
+                phone('twin', {
+                    host: 'http://other:4723',
+                    reservedUntil: Date.now() + 600000,
+                    reservedBy: 'x',
+                }),
+                phone('twin'),
+            ]);
+            const got = yield DeviceUtils.allocateDeviceForSession(caps(), 2000, 100, pluginArgs);
+            expect(got.host).to.equal('http://127.0.0.1:4723');
+            const reserved = (yield db_1.XenonDatabase.DeviceModel).findOne({
+                udid: 'twin',
+                host: 'http://other:4723',
+            });
+            expect(reserved.busy).to.equal(false);
+        }));
+        it('skips a leased phone whose busy flag was cleared and takes a free one', () => __awaiter(void 0, void 0, void 0, function* () {
+            // Listed first, so the old single-candidate lock tried only it, forever.
+            yield (0, device_service_1.addNewDevice)([phone('a-leased'), phone('b-free')]);
+            yield lease('a-leased');
+            const got = yield DeviceUtils.allocateDeviceForSession(caps(), 2000, 100, pluginArgs);
+            expect(got.udid).to.equal('b-free');
+        }));
+    });
+});

package/lib/test/unit/partial-config-file.spec.js

@@ -0,0 +1,100 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const lodash_1 = __importDefault(require("lodash"));
+// An Appium config file is checked against Xenon's schema.json before Appium
+// fills in defaults (appium/build/lib/main.js: readConfigFile, then
+// defaultsDeep(cli, file, schema defaults)). A `required` option therefore
+// makes Appium refuse any file that leaves it out, even though it has a
+// default. Through 2.13.1 the README's own five-option sample was refused with
+// "REQUIRED must have required property 'enableJsonLogging'". These checks run
+// Appium's own loader so a file that sets a few options keeps starting.
+/* eslint-disable @typescript-eslint/no-var-requires -- Appium's internals have no type exports */
+const appiumSchema = require('appium/build/lib/schema/schema');
+const { readConfigFile } = require('appium/build/lib/config-file');
+/* eslint-enable @typescript-eslint/no-var-requires */
+const xenonSchema = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, '..', '..', 'schema.json'), 'utf8'));
+// The README's sample, verbatim.
+const README_SAMPLE = `server:
+  use-plugins: [xenon]
+  plugin:
+    xenon:
+      platform: both
+      enableDashboard: true
+      maxSessions: 8
+      enableSelfHealing: true
+      buildCleanupDays: 30
+`;
+describe('An Appium config file for Xenon', function () {
+    let dir;
+    function load(yaml) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const file = path_1.default.join(dir, `config-${Math.random().toString(36).slice(2)}.yaml`);
+            fs_1.default.writeFileSync(file, yaml);
+            return readConfigFile(file);
+        });
+    }
+    before(function () {
+        appiumSchema.resetSchema();
+        appiumSchema.registerSchema('plugin', 'xenon', xenonSchema);
+        appiumSchema.finalizeSchema();
+        dir = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'xenon-config-'));
+    });
+    after(function () {
+        appiumSchema.resetSchema();
+        fs_1.default.rmSync(dir, { recursive: true, force: true });
+    });
+    it('is accepted when it sets only a few options (the README sample)', function () {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const result = yield load(README_SAMPLE);
+            (0, chai_1.expect)((_a = result.reason) !== null && _a !== void 0 ? _a : result.errors).to.be.empty;
+        });
+    });
+    it('is accepted when it sets no Xenon option at all', function () {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const result = yield load('server:\n  use-plugins: [xenon]\n');
+            (0, chai_1.expect)((_a = result.reason) !== null && _a !== void 0 ? _a : result.errors).to.be.empty;
+        });
+    });
+    it('is still refused when a value is invalid', function () {
+        return __awaiter(this, void 0, void 0, function* () {
+            const result = yield load(README_SAMPLE.replace('platform: both', 'platform: windows'));
+            (0, chai_1.expect)(result.errors).to.not.be.empty;
+        });
+    });
+    it('leaves Appium to fill every option the file leaves out with its default', function () {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            // What Appium's main does after a file passes: CLI args, then the file,
+            // then the schema's defaults.
+            const result = yield load(README_SAMPLE);
+            const defaults = appiumSchema.getDefaultsForSchema(false);
+            const server = lodash_1.default.defaultsDeep({}, (_a = result.config) === null || _a === void 0 ? void 0 : _a.server, defaults);
+            const xenon = server.plugin.xenon;
+            const setInFile = new Set(Object.keys(result.config.server.plugin.xenon));
+            (0, chai_1.expect)(xenon.maxSessions).to.equal(8); // from the file
+            for (const [key, prop] of Object.entries(xenonSchema.properties)) {
+                if ('default' in prop && !setInFile.has(key)) {
+                    (0, chai_1.expect)(xenon[key], `${key} should take its default`).to.deep.equal(prop.default);
+                }
+            }
+        });
+    });
+});

package/lib/test/unit/schema-required-args.spec.js

@@ -2,10 +2,13 @@
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
+var _a;
 Object.defineProperty(exports, "__esModule", { value: true });
 const chai_1 = require("chai");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+// eslint-disable-next-line @typescript-eslint/no-var-requires -- a plain Node script's list
+const { ALWAYS_PRESENT_PLUGIN_ARGS } = require('../../scripts/lib/always-present-plugin-args');
 // Adding a plugin arg to schema.json's `required` list is a BREAKING change for
 // every existing config file. Appium validates the config against this schema
 // and refuses to start when a required key is absent:
@@ -18,28 +21,30 @@ const path_1 = __importDefault(require("path"));
 // in 1.12.0 — an already-running server would not come back up after upgrading,
 // with no way to tell from the message that the fix is to edit a YAML file.
 //
-// An arg with a default must be optional: the schema default and the code's own
-// destructuring fallback already supply the value.
+// An arg with a default must be optional: Appium fills in schema defaults after
+// it validates the file, and the plugin merges DefaultPluginArgs as well. Until
+// 2.13.1, 23 args were both required and defaulted, so a config file had to list
+// all of them; even the README's five-option sample was refused. None is now.
 const schema = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, '..', '..', 'schema.json'), 'utf8'));
-/** Args already both required and defaulted when this guard was added. */
-const KNOWN_REQUIRED_WITH_DEFAULT = 23;
+const required = (_a = schema.required) !== null && _a !== void 0 ? _a : [];
 describe('schema.json required args', () => {
-    it('does not grow the set of args that are required despite having a default', () => {
+    it('requires no arg that has a default', () => {
         // A default means "you may omit this", which is the opposite of required.
-        // 23 args already sit in both lists; they only work because the Mac app
-        // writes every required key into the config it generates, so a hand-written
-        // or older config is already fragile against them. That is pre-existing
-        // debt, not something to fix in a hotfix — but the set must not GROW,
-        // because each addition breaks every config written before it.
-        const contradictory = schema.required.filter((key) => schema.properties[key] && 'default' in schema.properties[key]);
-        (0, chai_1.expect)(contradictory.length, `New required-with-default arg(s): ${contradictory.slice(KNOWN_REQUIRED_WITH_DEFAULT).join(', ')}. ` +
-            'An existing config that omits them fails Appium config validation and the server ' +
-            'will not start. Give the arg a default and leave it out of `required`.').to.equal(KNOWN_REQUIRED_WITH_DEFAULT);
+        const contradictory = required.filter((key) => schema.properties[key] && 'default' in schema.properties[key]);
+        (0, chai_1.expect)(contradictory, 'An existing config that omits these fails Appium config validation and the server ' +
+            'will not start. Give the arg a default and leave it out of `required`.').to.deep.equal([]);
     });
     it('keeps every required arg present in properties', () => {
-        const missing = schema.required.filter((key) => !schema.properties[key]);
+        const missing = required.filter((key) => !schema.properties[key]);
         (0, chai_1.expect)(missing, 'required lists an arg that does not exist').to.deep.equal([]);
     });
+    it('types as always present only args that have a default', () => {
+        // IPluginArgs keeps these fields non-optional (scripts/generate-types-from-schema.js
+        // marks them required for type generation only). That is true only while each
+        // exists and has a default for Appium and DefaultPluginArgs to fill in.
+        const wrong = ALWAYS_PRESENT_PLUGIN_ARGS.filter((key) => !schema.properties[key] || !('default' in schema.properties[key]));
+        (0, chai_1.expect)(wrong, 'listed as always present but missing or without a default').to.deep.equal([]);
+    });
     it('does not require the recording retention args', () => {
         // Named explicitly: this is the regression that took a live server down.
         for (const key of [
@@ -48,7 +53,7 @@ describe('schema.json required args', () => {
             'recordingFailedCleanupDays',
         ]) {
             (0, chai_1.expect)(schema.properties[key], `${key} should exist`).to.be.an('object');
-            (0, chai_1.expect)(schema.required, `${key} must stay optional`).to.not.include(key);
+            (0, chai_1.expect)(required, `${key} must stay optional`).to.not.include(key);
         }
     });
 });

package/lib/test/unit/wda-client-session.spec.js

@@ -0,0 +1,128 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const chai_1 = require("chai");
+const axios_1 = __importDefault(require("axios"));
+const sinon_1 = __importDefault(require("sinon"));
+const typedi_1 = require("typedi");
+const IOSStreamService_1 = __importDefault(require("../../src/device-managers/ios/IOSStreamService"));
+const WDAClient_1 = require("../../src/device-managers/ios/WDAClient");
+const device_store_1 = require("../../src/data-service/device-store");
+/**
+ * Each live preview creates its own WebDriverAgent session, and WDAClient kept
+ * the session it had seen first. After the preview restarted (device control
+ * closed and opened again), every hardware button went to the old session:
+ * WDA answered 404 "invalid session id", which pressButton and homescreen
+ * treat as "not supported" rather than a dead session, so Home and the volume
+ * buttons answered 500 until a lock or a swipe happened to renew it. A key
+ * the iPhone does have was also reported as one it doesn't.
+ */
+describe('WDAClient follows the live preview’s WebDriverAgent session', () => {
+    const PHONE = '00008110-00084CE80E51401E';
+    const PORT = 28100;
+    let urls;
+    // The session WebDriverAgent has now, and the one the preview recorded.
+    let live;
+    let previews;
+    // Whether WDA names its live session when it refuses a dead one, as WDA does.
+    let namesLiveSession;
+    const deadSession = () => Object.assign(new Error('Request failed with status code 404'), {
+        response: {
+            status: 404,
+            data: {
+                value: { error: 'invalid session id', message: 'Session does not exist' },
+                sessionId: namesLiveSession ? live : null,
+            },
+        },
+    });
+    const unknownCommand = () => Object.assign(new Error('Request failed with status code 404'), {
+        response: {
+            status: 404,
+            data: { value: { error: 'unknown command' }, sessionId: live },
+        },
+    });
+    beforeEach(() => {
+        urls = [];
+        namesLiveSession = true;
+        sinon_1.default.stub(device_store_1.DeviceStoreFactory, 'getStore').returns({
+            findDevice: () => __awaiter(void 0, void 0, void 0, function* () { return ({ udid: PHONE, realDevice: true }); }),
+        });
+        const real = typedi_1.Container.get.bind(typedi_1.Container);
+        sinon_1.default.stub(typedi_1.Container, 'get').callsFake((token) => {
+            if (token === IOSStreamService_1.default) {
+                return {
+                    getStreamStatus: () => ({ status: 'running', wdaPort: PORT }),
+                    getWDASessionId: () => previews,
+                    setWDASessionId: (_udid, sid) => {
+                        previews = sid || undefined;
+                    },
+                };
+            }
+            return real(token);
+        });
+        sinon_1.default.stub(axios_1.default, 'post').callsFake(((url) => __awaiter(void 0, void 0, void 0, function* () {
+            var _a;
+            urls.push(url);
+            const session = (_a = /\/session\/([^/]+)\//.exec(url)) === null || _a === void 0 ? void 0 : _a[1];
+            if (session && session !== live)
+                throw deadSession();
+            // As WDA does: a button press needs a session, and the home screen
+            // is reached only without one.
+            if (!session && url.endsWith('/wda/pressButton'))
+                throw unknownCommand();
+            if (session && url.endsWith('/wda/homescreen'))
+                throw unknownCommand();
+            return { status: 200, data: { value: null, sessionId: live } };
+        })));
+    });
+    afterEach(() => sinon_1.default.restore());
+    it('presses a button in the restarted preview’s session', () => __awaiter(void 0, void 0, void 0, function* () {
+        const wda = new WDAClient_1.WDAClient();
+        live = previews = 'FIRST';
+        yield wda.pressKey(PHONE, 'volumeup');
+        // Device control closed and opened again: a new preview, a new session.
+        live = previews = 'SECOND';
+        urls = [];
+        yield wda.pressKey(PHONE, 'volumeup');
+        (0, chai_1.expect)(urls).to.deep.equal([`http://127.0.0.1:${PORT}/session/SECOND/wda/pressButton`]);
+    }));
+    it('moves to the session WebDriverAgent names when the one it knew is gone', () => __awaiter(void 0, void 0, void 0, function* () {
+        const wda = new WDAClient_1.WDAClient();
+        live = previews = 'FIRST';
+        yield wda.pressKey(PHONE, 'home');
+        // WDA started a new session that nothing here recorded.
+        live = 'SECOND';
+        urls = [];
+        yield wda.pressKey(PHONE, 'home');
+        (0, chai_1.expect)(urls[urls.length - 1]).to.equal(`http://127.0.0.1:${PORT}/session/SECOND/wda/pressButton`);
+        (0, chai_1.expect)(previews).to.equal('SECOND');
+    }));
+    it('does not call a dead session a key the iPhone lacks', () => __awaiter(void 0, void 0, void 0, function* () {
+        live = 'SECOND';
+        previews = 'FIRST';
+        namesLiveSession = false;
+        const err = yield new WDAClient_1.WDAClient().pressKey(PHONE, 'camera').then(() => null, (e) => e);
+        (0, chai_1.expect)(err).to.be.an('error');
+        (0, chai_1.expect)(err).not.to.be.instanceOf(WDAClient_1.UnsupportedKeyError);
+    }));
+    // Every caller sent it inside the session and got 404 "unknown command":
+    // the Home key's fallback, the clipboard read, and putting the home screen
+    // back after a clipboard write, which left WDA's black screen in front.
+    it('goes to the home screen without a session, the only way WDA takes it', () => __awaiter(void 0, void 0, void 0, function* () {
+        live = previews = 'FIRST';
+        yield new WDAClient_1.WDAClient().sendWDACommand(PHONE, 'post', '/wda/homescreen', {});
+        (0, chai_1.expect)(urls).to.deep.equal([`http://127.0.0.1:${PORT}/wda/homescreen`]);
+    }));
+});

package/lib/test/unit/wda-clipboard-write.spec.js

@@ -0,0 +1,135 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const chai_1 = require("chai");
+const sinon_1 = __importDefault(require("sinon"));
+const typedi_1 = require("typedi");
+const IOSStreamService_1 = __importDefault(require("../../src/device-managers/ios/IOSStreamService"));
+const WDAClient_1 = require("../../src/device-managers/ios/WDAClient");
+const device_store_1 = require("../../src/data-service/device-store");
+/**
+ * iOS ignores a pasteboard write from an app in the background, and
+ * WebDriverAgent still answers success. Device control's "Write to device"
+ * on an iPhone reported success and left the clipboard as it was (checked on
+ * an iPhone 14 Plus, iOS 26.5). The write now brings WDA's own app forward,
+ * reads the text back, and puts back the app that was in front.
+ *
+ * Bringing WDA's app forward waits for it to go idle, which it never does, so
+ * the call took about 21 s. WDA's idle wait is turned off for that step and
+ * put back after.
+ */
+describe('WDAClient writes an iPhone’s clipboard', () => {
+    const PHONE = '00008110-00084CE80E51401E';
+    const WDA = 'com.qasecret.WebDriverAgentRunner.xctrunner';
+    const b64 = (s) => Buffer.from(s).toString('base64');
+    // The phone as iOS behaves: only the app in front can write the pasteboard.
+    let phone;
+    let calls;
+    let idleWaitAtActivation;
+    let unreadableSettings;
+    beforeEach(() => {
+        idleWaitAtActivation = [];
+        unreadableSettings = false;
+        phone = {
+            front: 'com.apple.springboard',
+            pasteboard: '',
+            idleWait: 10,
+            takesWrites: true,
+            realDevice: true,
+        };
+        calls = [];
+        sinon_1.default.stub(device_store_1.DeviceStoreFactory, 'getStore').returns({
+            findDevice: () => __awaiter(void 0, void 0, void 0, function* () { return ({ udid: PHONE, realDevice: phone.realDevice }); }),
+        });
+        const real = typedi_1.Container.get.bind(typedi_1.Container);
+        sinon_1.default.stub(typedi_1.Container, 'get').callsFake((token) => {
+            if (token === IOSStreamService_1.default)
+                return { detectWDABundleId: () => __awaiter(void 0, void 0, void 0, function* () { return WDA; }) };
+            return real(token);
+        });
+        sinon_1.default.stub(WDAClient_1.WDAClient.prototype, 'sendWDACommand').callsFake(((_udid, method, endpoint, data) => __awaiter(void 0, void 0, void 0, function* () {
+            calls.push(`${method} ${endpoint}`);
+            const ok = (value = null) => ({ status: 200, data: { value } });
+            switch (`${method} ${endpoint}`) {
+                case 'get /wda/activeAppInfo':
+                    return ok({ bundleId: phone.front });
+                case 'get /appium/settings':
+                    if (unreadableSettings)
+                        throw new Error('WDA request failed: /appium/settings');
+                    return ok({ waitForIdleTimeout: phone.idleWait });
+                case 'post /appium/settings':
+                    phone.idleWait = data.settings.waitForIdleTimeout;
+                    return ok();
+                case 'post /wda/apps/activate':
+                    if (data.bundleId === WDA)
+                        idleWaitAtActivation.push(phone.idleWait);
+                    phone.front = data.bundleId;
+                    return ok();
+                case 'post /wda/homescreen':
+                    phone.front = 'com.apple.springboard';
+                    return ok();
+                case 'post /wda/setPasteboard':
+                    if (phone.front === WDA && phone.takesWrites) {
+                        phone.pasteboard = Buffer.from(data.content, 'base64').toString();
+                    }
+                    return ok(); // success either way, as WDA answers
+                case 'post /wda/getPasteboard':
+                    return ok(phone.front === WDA ? b64(phone.pasteboard) : '');
+                default:
+                    throw new Error(`unexpected ${method} ${endpoint}`);
+            }
+        })));
+    });
+    afterEach(() => sinon_1.default.restore());
+    it('writes the clipboard while WebDriverAgent is in the background', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield new WDAClient_1.WDAClient().setClipboard(PHONE, 'hello from Xenon');
+        (0, chai_1.expect)(phone.pasteboard).to.equal('hello from Xenon');
+    }));
+    it('puts the home screen back when that was in front', () => __awaiter(void 0, void 0, void 0, function* () {
+        yield new WDAClient_1.WDAClient().setClipboard(PHONE, 'x');
+        (0, chai_1.expect)(phone.front).to.equal('com.apple.springboard');
+    }));
+    it('puts back the app that was in front', () => __awaiter(void 0, void 0, void 0, function* () {
+        phone.front = 'com.apple.Preferences';
+        yield new WDAClient_1.WDAClient().setClipboard(PHONE, 'x');
+        (0, chai_1.expect)(phone.front).to.equal('com.apple.Preferences');
+    }));
+    it('brings WebDriverAgent forward without its idle wait, and restores the wait', () => __awaiter(void 0, void 0, void 0, function* () {
+        phone.idleWait = 7;
+        yield new WDAClient_1.WDAClient().setClipboard(PHONE, 'x');
+        (0, chai_1.expect)(idleWaitAtActivation).to.deep.equal([0]);
+        (0, chai_1.expect)(phone.idleWait).to.equal(7);
+    }));
+    it('fails when the iPhone did not take the text', () => __awaiter(void 0, void 0, void 0, function* () {
+        phone.takesWrites = false;
+        const err = yield new WDAClient_1.WDAClient().setClipboard(PHONE, 'lost').then(() => null, (e) => e);
+        (0, chai_1.expect)(err === null || err === void 0 ? void 0 : err.message).to.equal('The iPhone didn’t take the clipboard text.');
+        (0, chai_1.expect)(phone.front).to.equal('com.apple.springboard');
+        (0, chai_1.expect)(phone.idleWait).to.equal(10);
+    }));
+    it('writes a simulator’s clipboard directly', () => __awaiter(void 0, void 0, void 0, function* () {
+        phone.realDevice = false;
+        phone.front = WDA; // a simulator's pasteboard takes the write from anywhere
+        yield new WDAClient_1.WDAClient().setClipboard(PHONE, 'sim');
+        (0, chai_1.expect)(calls).to.deep.equal(['post /wda/setPasteboard']);
+    }));
+    it('leaves the idle wait alone when it can’t read it, since it couldn’t put it back', () => __awaiter(void 0, void 0, void 0, function* () {
+        unreadableSettings = true;
+        yield new WDAClient_1.WDAClient().setClipboard(PHONE, 'slow but safe');
+        (0, chai_1.expect)(idleWaitAtActivation).to.deep.equal([10]);
+        (0, chai_1.expect)(calls).not.to.include('post /appium/settings');
+        (0, chai_1.expect)(phone.pasteboard).to.equal('slow but safe');
+    }));
+});