@xenon-device-management/xenon 2.13.1 → 2.14.0

package/lib/test/unit/lease/session-lease-proof.spec.js

@@ -179,6 +179,8 @@ describe('createSession — a lease-bound session proves it holds the lease', ()
         teamRows = sinon_1.default.stub(prisma_1.prisma.teamMember, 'findMany').resolves([]);
         sinon_1.default.stub(device_store_1.DeviceStoreFactory, 'getStore').returns({
             findDevice: sinon_1.default.stub().callsFake(() => __awaiter(void 0, void 0, void 0, function* () { return device; })),
+            // The lease branch records the session's newCommandTimeout on the row.
+            updateDevice: sinon_1.default.stub().resolves(),
         });
         sinon_1.default.stub(pendingSessions, 'addNewPendingSession').callsFake((c) => __awaiter(void 0, void 0, void 0, function* () {
             pendingCopy = JSON.parse(JSON.stringify(c));
@@ -257,6 +259,63 @@ describe('createSession — a lease-bound session proves it holds the lease', ()
         (0, chai_1.expect)(findById.calledOnce).to.equal(true);
         (0, chai_1.expect)(teamRows.calledOnce).to.equal(true);
     }));
+    describe('the platform allocation lock', () => {
+        // Ordinary creates queue on it, first come first served, each with its
+        // full wait from the head of the queue. A lease-bound create allocates
+        // nothing and used to queue behind them anyway, for up to their wait.
+        const plainCaps = () => {
+            const caps = sessionCaps(ownerKey);
+            delete caps.alwaysMatch['xe:options'].leaseId;
+            return caps;
+        };
+        const tick = (ms) => new Promise((r) => setTimeout(r, ms));
+        it("doesn't make a lease-bound create queue behind one waiting for a phone", () => __awaiter(void 0, void 0, void 0, function* () {
+            const real = deviceUtils.allocateDeviceForSession;
+            let releaseWaiter = () => undefined;
+            sinon_1.default.stub(deviceUtils, 'allocateDeviceForSession').callsFake(((c, ...rest) => {
+                var _a;
+                return ((_a = c.alwaysMatch['xe:options']) === null || _a === void 0 ? void 0 : _a.leaseId)
+                    ? real(c, ...rest)
+                    : new Promise((resolve) => {
+                        releaseWaiter = resolve;
+                    });
+            }));
+            const waiting = create(plainCaps());
+            let leased = Promise.resolve();
+            try {
+                yield tick(50);
+                let leasedDone = false;
+                leased = create(sessionCaps(ownerKey)).then(() => {
+                    leasedDone = true;
+                });
+                yield Promise.race([leased, tick(2000)]);
+                (0, chai_1.expect)(leasedDone, 'the lease-bound create waited on the lock').to.equal(true);
+            }
+            finally {
+                // Free the platform lock even when this fails, and let both creates
+                // finish here, or they run on into the next test.
+                releaseWaiter(device);
+                yield waiting;
+                yield leased;
+            }
+        }));
+        it('still queues ordinary creates one at a time', () => __awaiter(void 0, void 0, void 0, function* () {
+            const waiters = [];
+            const allocate = sinon_1.default
+                .stub(deviceUtils, 'allocateDeviceForSession')
+                .callsFake((() => new Promise((resolve) => waiters.push(resolve))));
+            const first = create(plainCaps());
+            const second = create(plainCaps());
+            yield tick(100);
+            (0, chai_1.expect)(allocate.callCount, 'the second create allocated before the first finished').to.equal(1);
+            waiters[0](device);
+            yield first;
+            yield tick(50);
+            (0, chai_1.expect)(allocate.callCount).to.equal(2);
+            waiters[1](device);
+            yield second;
+        }));
+    });
     it('a session that names a lease reads them once too, for the scope and the lease', () => __awaiter(void 0, void 0, void 0, function* () {
         const findById = sinon_1.default.spy(typedi_1.Container.get(UserService_1.UserService), 'findById');
         yield allowed(sessionCaps(ownerKey));

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/max-sessions.spec.js

@@ -0,0 +1,240 @@
+"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 DeviceUtils = __importStar(require("../../src/device-utils"));
+const db_1 = require("../../src/data-service/db");
+const device_service_1 = require("../../src/data-service/device-service");
+const deviceClaims_1 = require("../../src/data-service/deviceClaims");
+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");
+const expect = chai_1.default.expect;
+/**
+ * `maxSessions` holds new sessions back once that many Appium sessions run.
+ *
+ * It compared the number of busy phones with `===`, so once the count was past
+ * the limit nothing was held back any more, and it counted every busy phone: a
+ * live preview, a recording, or an SDK lease nobody had started a session on
+ * used up a slot that no Appium session was using. What it counts now is the
+ * phones running a session, or being given one.
+ */
+describe('maxSessions', () => {
+    describe('which phones count', () => {
+        const base = { busy: true };
+        it('counts a session being created (a claim with no session id yet)', () => {
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { claimedAt: Date.now() }))).to.equal(true);
+        });
+        it('counts a session that is running', () => {
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { claimedAt: 1, claimSessionId: 'sess-1', session_id: 'sess-1' }))).to.equal(true);
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { session_id: 'sess-1' }))).to.equal(true);
+        });
+        it('does not count a live preview or a recording', () => {
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { session_id: 'manual_u1_phone-1' }))).to.equal(false);
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { session_id: 'manual_phone-1' }))).to.equal(false);
+        });
+        it('does not count a phone an SDK lease holds that has no session on it', () => {
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign({}, base))).to.equal(false);
+        });
+        it('counts a session started on a leased phone', () => {
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { claimSessionId: 'sess-2', claimedAt: 1 }))).to.equal(true);
+        });
+        it('does not count a phone that is not busy', () => {
+            expect((0, deviceClaims_1.countsTowardMaxSessions)({ busy: false })).to.equal(false);
+            expect((0, deviceClaims_1.countsTowardMaxSessions)({ busy: false, session_id: 'sess-1' })).to.equal(false);
+        });
+        it("counts a node's phone the node reports busy, unless the node says it is a preview", () => {
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { nodeBusy: true }))).to.equal(true);
+            expect((0, deviceClaims_1.countsTowardMaxSessions)(Object.assign(Object.assign({}, base), { nodeBusy: true, nodeHold: 'manual_u1_phone-1' }))).to.equal(false);
+        });
+    });
+    describe('the limit itself', () => {
+        it('is the setting when it is a positive number', () => {
+            expect((0, deviceClaims_1.sessionCap)(8)).to.equal(8);
+            expect((0, deviceClaims_1.sessionCap)(1)).to.equal(1);
+        });
+        it('is no limit when it is unset, zero, negative or not a number', () => {
+            for (const value of [undefined, null, 0, -1, NaN, Infinity, '8']) {
+                expect((0, deviceClaims_1.sessionCap)(value), String(value)).to.equal(undefined);
+            }
+        });
+    });
+    describe('allocation', () => {
+        (0, loki_stores_1.useLokiStores)();
+        const scratch = (0, scratch_database_1.useScratchDatabase)();
+        const sandbox = sinon_1.default.createSandbox();
+        const HOST = 'http://127.0.0.1:4723';
+        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: HOST, busy: false, offline: false, userBlocked: false, state: 'device', deviceType: 'emulator', realDevice: false, systemPort: 57000, totalUtilizationTimeMilliSec: 0, sessionStartTime: 0 }, over));
+        // New each time: allocation pins the phone it picked into the caps it is given.
+        const caps = () => ({
+            alwaysMatch: { platformName: 'android' },
+            firstMatch: [{}],
+        });
+        const row = (udid) => __awaiter(void 0, void 0, void 0, function* () { return (yield db_1.XenonDatabase.DeviceModel).findOne({ udid }); });
+        /** Asks for a phone, waiting `ms` at most. Resolves to the udid, or null when held back. */
+        const ask = (ms = 400) => DeviceUtils.allocateDeviceForSession(caps(), ms, 50, pluginArgs).then((d) => d.udid, () => null);
+        const withCap = (maxSessions) => (0, test_container_1.createTestXenonManager)(Object.assign({}, pluginArgs, { maxSessions, platform: 'android' }));
+        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({});
+            sandbox.stub(DeviceUtils, 'setUtilizationTime').resolves();
+        }));
+        afterEach(() => sandbox.restore());
+        const running = (n) => Array.from({ length: n }, (_, i) => phone(`running-${i}`, {
+            busy: true,
+            session_id: `sess-${i}`,
+            claimSessionId: `sess-${i}`,
+            claimedAt: 1,
+        }));
+        it('allocates while fewer sessions run than the limit', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(2);
+            yield (0, device_service_1.addNewDevice)([...running(1), phone('free-1')]);
+            expect(yield ask()).to.equal('free-1');
+        }));
+        it('holds a session back at the limit', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(2);
+            yield (0, device_service_1.addNewDevice)([...running(2), phone('free-1')]);
+            expect(yield ask()).to.equal(null);
+            expect((yield row('free-1')).busy).to.equal(false);
+        }));
+        it('still holds it back when more sessions run than the limit, which `===` let through', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(2);
+            yield (0, device_service_1.addNewDevice)([...running(3), phone('free-1')]);
+            expect(yield ask()).to.equal(null);
+            expect((yield row('free-1')).busy).to.equal(false);
+        }));
+        it('gives the phone once a session ends', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(2);
+            yield (0, device_service_1.addNewDevice)([...running(2), phone('free-1')]);
+            const waiting = ask(2000);
+            yield new Promise((r) => setTimeout(r, 150));
+            (yield db_1.XenonDatabase.DeviceModel)
+                .chain()
+                .find({ udid: 'running-0' })
+                .update((d) => Object.assign(d, {
+                busy: false,
+                session_id: null,
+                claimSessionId: null,
+                claimedAt: null,
+            }));
+            expect(yield waiting).to.be.oneOf(['free-1', 'running-0']);
+        }));
+        it('does not count live previews: they are not sessions', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(2);
+            yield (0, device_service_1.addNewDevice)([
+                phone('preview-1', { busy: true, session_id: 'manual_u1_preview-1' }),
+                phone('preview-2', { busy: true, session_id: 'manual_u1_preview-2' }),
+                phone('free-1'),
+            ]);
+            expect(yield ask()).to.equal('free-1');
+        }));
+        it('does not count a leased phone no session is running on', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(1);
+            yield (0, device_service_1.addNewDevice)([phone('leased-1', { busy: true }), phone('free-1')]);
+            yield scratch.db.lease.create({
+                data: {
+                    tokenHash: 'h',
+                    deviceUdid: 'leased-1',
+                    deviceHost: HOST,
+                    actorId: 'key_owner',
+                    status: 'active',
+                    expiresAt: Date.now() + 600000,
+                    lastHeartbeatAt: Date.now(),
+                    allocatedPorts: '{}',
+                    capabilityBag: '{}',
+                },
+            });
+            expect(yield ask()).to.equal('free-1');
+        }));
+        it('counts a session started on a leased phone', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(1);
+            yield (0, device_service_1.addNewDevice)([
+                phone('leased-1', {
+                    busy: true,
+                    session_id: 'sess-l',
+                    claimSessionId: 'sess-l',
+                    claimedAt: 1,
+                }),
+                phone('free-1'),
+            ]);
+            expect(yield ask()).to.equal(null);
+        }));
+        it('counts a session still being created', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(1);
+            yield (0, device_service_1.addNewDevice)([
+                phone('pending-1', { busy: true, claimedAt: Date.now() }),
+                phone('free-1'),
+            ]);
+            expect(yield ask()).to.equal(null);
+        }));
+        it('holds back exactly the sessions over the limit when many ask at once', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(2);
+            yield (0, device_service_1.addNewDevice)(Array.from({ length: 6 }, (_, i) => phone(`free-${i}`)));
+            const got = yield Promise.all(Array.from({ length: 5 }, () => ask(300)));
+            const given = got.filter((udid) => udid !== null);
+            expect(given, JSON.stringify(got)).to.have.length(2);
+            expect(new Set(given).size).to.equal(2);
+        }));
+        it('has no limit when the setting is not a positive number', () => __awaiter(void 0, void 0, void 0, function* () {
+            withCap(0);
+            yield (0, device_service_1.addNewDevice)([...running(3), phone('free-1')]);
+            expect(yield ask()).to.equal('free-1');
+        }));
+    });
+});

package/lib/test/unit/ocr-text-match.spec.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const chai_1 = require("chai");
+const ocrTextMatch_1 = require("../../src/services/omni-vision/ocrTextMatch");
+describe('ocrTextMatch', () => {
+    const word = (text, x0, y0, x1, y1, confidence = 90) => ({ text, x0, y0, x1, y1, confidence });
+    it('groups words into lines and runs, in reading order, despite a slightly uneven baseline', () => {
+        const runs = (0, ocrTextMatch_1.wordRuns)([
+            word('Done', 900, 40, 980, 70),
+            word('in', 158, 202, 180, 226),
+            word('Cancel', 20, 42, 120, 70),
+            word('Sign', 100, 200, 150, 224),
+        ]);
+        (0, chai_1.expect)(runs.map((r) => r.map((w) => w.text))).to.deep.equal([
+            ['Cancel'],
+            ['Done'],
+            ['Sign', 'in'],
+        ]);
+    });
+    it('finds every occurrence, once per set of words, with the lowest confidence of the words', () => {
+        const words = [
+            word('Add', 10, 10, 50, 30, 95),
+            word('to', 56, 10, 70, 30, 70),
+            word('cart', 76, 10, 120, 30, 88),
+            word('Add', 10, 100, 50, 120),
+            word('to', 56, 100, 70, 120),
+            word('cart', 76, 100, 120, 120),
+        ];
+        const found = (0, ocrTextMatch_1.findText)(words, '  add   TO cart ');
+        (0, chai_1.expect)(found.map((m) => [m.text, m.y0, m.confidence])).to.deep.equal([
+            ['Add to cart', 10, 70],
+            ['Add to cart', 100, 90],
+        ]);
+        (0, chai_1.expect)(found[0]).to.include({ x0: 10, x1: 120, y1: 30 });
+    });
+    it('matches a one-word text inside a word once, however often it appears there', () => {
+        (0, chai_1.expect)((0, ocrTextMatch_1.findText)([word('banana', 0, 0, 60, 20)], 'an').map((m) => m.text)).to.deep.equal([
+            'banana',
+        ]);
+    });
+    it('matches nothing for an empty text', () => {
+        (0, chai_1.expect)((0, ocrTextMatch_1.findText)([word('Sign', 0, 0, 40, 20)], '   ')).to.deep.equal([]);
+    });
+});

package/lib/test/unit/omni-vision-analyze-screen.spec.js

@@ -0,0 +1,72 @@
+"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 OmniVisionService_1 = require("../../src/services/omni-vision/OmniVisionService");
+const AIService_1 = require("../../src/services/AIService");
+/**
+ * `xenon: analyzeScreen` (and device control's Omni-Scan) sent the screenshot's
+ * base64 where a file path was expected. The AI step found no such file and
+ * asked the provider without an image, under a "why did this test fail"
+ * prompt, so `ai_insights` was generic text about no screen at all.
+ *
+ * Now the screenshot goes to the provider with a prompt about the screen, and
+ * when there is no AI answer `ai_insights_error` says why.
+ */
+describe('xenon: analyzeScreen', () => {
+    const SCREEN = 'c2NyZWVuc2hvdA==';
+    let service;
+    const driver = { sessionId: 'session-1', getScreenshot: () => __awaiter(void 0, void 0, void 0, function* () { return SCREEN; }) };
+    beforeEach(() => {
+        service = new OmniVisionService_1.OmniVisionService();
+        sinon_1.default.stub(service, 'performOcr').resolves({
+            text: 'Sign in',
+            words: [{ text: 'Sign', confidence: 95, bbox: { x0: 10, y0: 10, x1: 50, y1: 30 } }],
+        });
+        sinon_1.default.stub(AIService_1.AI_SERVICE, 'initializeProvider');
+    });
+    afterEach(() => sinon_1.default.restore());
+    it('sends the screenshot to the AI provider and asks about the screen', () => __awaiter(void 0, void 0, void 0, function* () {
+        sinon_1.default.stub(AIService_1.AI_SERVICE, 'provider').value({ analyze: () => __awaiter(void 0, void 0, void 0, function* () { return ''; }) });
+        const call = sinon_1.default
+            .stub(AIService_1.AI_SERVICE, 'callProvider')
+            .resolves('A sign-in screen with an email field.');
+        const analysis = yield service.analyzeScreen(driver);
+        (0, chai_1.expect)(call.calledOnce).to.equal(true);
+        const [prompt, image] = call.firstCall.args;
+        (0, chai_1.expect)(image).to.equal(SCREEN);
+        (0, chai_1.expect)(prompt).to.match(/screen/i);
+        (0, chai_1.expect)(prompt).to.not.match(/root cause|failed/i);
+        (0, chai_1.expect)(analysis.ai_insights).to.equal('A sign-in screen with an email field.');
+        (0, chai_1.expect)(analysis).to.not.have.property('ai_insights_error');
+        (0, chai_1.expect)(analysis.ocr.text).to.equal('Sign in');
+    }));
+    it('says why there are no AI insights when no provider is configured', () => __awaiter(void 0, void 0, void 0, function* () {
+        sinon_1.default.stub(AIService_1.AI_SERVICE, 'provider').value(null);
+        const analysis = yield service.analyzeScreen(driver);
+        (0, chai_1.expect)(analysis.ai_insights).to.equal(null);
+        (0, chai_1.expect)(analysis.ai_insights_error).to.match(/No AI provider is configured/);
+        (0, chai_1.expect)(analysis.ocr.text).to.equal('Sign in');
+    }));
+    it('says why there are no AI insights when the provider fails', () => __awaiter(void 0, void 0, void 0, function* () {
+        sinon_1.default.stub(AIService_1.AI_SERVICE, 'provider').value({ analyze: () => __awaiter(void 0, void 0, void 0, function* () { return ''; }) });
+        sinon_1.default.stub(AIService_1.AI_SERVICE, 'callProvider').rejects(new Error('429 quota exceeded'));
+        const analysis = yield service.analyzeScreen(driver);
+        (0, chai_1.expect)(analysis.ai_insights).to.equal(null);
+        (0, chai_1.expect)(analysis.ai_insights_error).to.match(/429 quota exceeded/);
+        (0, chai_1.expect)(analysis.ocr.text).to.equal('Sign in');
+    }));
+});