@xenon-device-management/xenon 2.14.0 → 2.16.0

package/lib/test/unit/ios-simulator-session-teardown.spec.js

@@ -0,0 +1,158 @@
+"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 = require("chai");
+const sinon_1 = __importDefault(require("sinon"));
+const typedi_1 = require("typedi");
+const DeviceService = __importStar(require("../../src/data-service/device-service"));
+const IOSStreamService_1 = __importDefault(require("../../src/device-managers/ios/IOSStreamService"));
+const event_manager_1 = require("../../src/dashboard/event-manager");
+const SessionLifecycleService_1 = require("../../src/services/SessionLifecycleService");
+const SessionMetricsService_1 = require("../../src/services/metrics/SessionMetricsService");
+const PhoneNetworkRestore_1 = require("../../src/services/network/PhoneNetworkRestore");
+const VideoPipelineService_1 = require("../../src/services/VideoPipelineService");
+const LocalSession_1 = require("../../src/sessions/LocalSession");
+const SessionManager_1 = require("../../src/sessions/SessionManager");
+const container_registration_1 = require("../helpers/container-registration");
+const scratch_database_1 = require("../helpers/scratch-database");
+/**
+ * What Xenon does around a session on an iOS simulator, whose WebDriverAgent
+ * the XCUITest driver runs on this Mac.
+ *
+ * A session that passed every command ended failed: its end stopped a
+ * performance recording that Xenon starts only on an iPhone, the driver
+ * refuses that on a simulator without relaxed security, and the refused stop
+ * counted as a failed command of the session. Its video was never written:
+ * it was read from the iPhone stream's USB forward (iproxy), which on a
+ * simulator forwards nothing, while the simulator's own WebDriverAgent serves
+ * the picture on this Mac at the session's mjpegServerPort.
+ */
+const SIMULATOR = '35429994-B029-4AF4-9634-880B89DAC782';
+const IPHONE = '00008150-000E78612168C01C';
+const device = (udid, realDevice) => ({
+    udid,
+    name: 'iPhone 16 Pro',
+    platform: 'ios',
+    sdk: '18.4',
+    host: 'http://127.0.0.1:4723',
+    realDevice,
+    deviceType: realDevice ? 'real' : 'simulator',
+    screenWidth: '402',
+    screenHeight: '874',
+});
+describe('iOS simulator sessions: around the session', function () {
+    this.timeout(30000);
+    afterEach(() => sinon_1.default.restore());
+    describe('the end of a session', () => {
+        (0, scratch_database_1.useScratchDatabase)();
+        let restoreRegs;
+        beforeEach(() => {
+            restoreRegs = (0, container_registration_1.saveRegistrations)(PhoneNetworkRestore_1.PhoneNetworkRestore, SessionMetricsService_1.SessionMetricsService);
+            typedi_1.Container.set(PhoneNetworkRestore_1.PhoneNetworkRestore, { restoreSession: sinon_1.default.stub().resolves() });
+            typedi_1.Container.set(SessionMetricsService_1.SessionMetricsService, { stop: sinon_1.default.stub().resolves() });
+            sinon_1.default.stub(DeviceService, 'releaseSessionDevices').resolves();
+            sinon_1.default.stub(event_manager_1.DASHBORD_EVENT_MANAGER, 'onSessionStopped').resolves();
+            sinon_1.default.stub(SessionManager_1.SESSION_MANAGER, 'removeSession');
+        });
+        afterEach(() => restoreRegs());
+        /** Deletes a session on `phone`; resolves to whether its end stopped a performance recording. */
+        function endSessionOn(phone) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const stopPerformanceRecording = sinon_1.default.stub().resolves(null);
+                const session = {
+                    isStopping: false,
+                    getId: () => 's-1',
+                    getDevice: () => phone,
+                    stopPerformanceRecording,
+                    isVideoRecordingInProgress: () => false,
+                };
+                sinon_1.default.stub(SessionManager_1.SESSION_MANAGER, 'getSession').returns(session);
+                yield typedi_1.Container.get(SessionLifecycleService_1.SessionLifecycleService).deleteSession(sinon_1.default.stub().resolves(), 's-1');
+                return stopPerformanceRecording.called;
+            });
+        }
+        it('stops no performance recording on a simulator, where none was started', () => __awaiter(this, void 0, void 0, function* () {
+            (0, chai_1.expect)(yield endSessionOn(device(SIMULATOR, false))).to.equal(false);
+        }));
+        it("still stops an iPhone's, which Xenon started", () => __awaiter(this, void 0, void 0, function* () {
+            (0, chai_1.expect)(yield endSessionOn(device(IPHONE, true))).to.equal(true);
+        }));
+    });
+    describe('the session video', () => {
+        let startRecording;
+        let startStream;
+        beforeEach(() => {
+            startRecording = sinon_1.default.stub(VideoPipelineService_1.VideoPipelineService.prototype, 'startRecording').resolves();
+            startStream = sinon_1.default
+                .stub(IOSStreamService_1.default.prototype, 'startStream')
+                .resolves({ mjpegPort: 9150 });
+        });
+        const local = (phone) => new LocalSession_1.LocalSession({
+            sessionId: 's-video',
+            device: phone,
+            // The capabilities the driver answered the create with.
+            sessionResponse: { udid: phone.udid, wdaLocalPort: 8101, mjpegServerPort: 9101 },
+            xenonOption: {},
+            driver: { opts: { address: '127.0.0.1', port: 4723, basePath: '/wd/hub' }, sessions: {} },
+        });
+        it("is read from the simulator's own WebDriverAgent, at the session's MJPEG port", () => __awaiter(this, void 0, void 0, function* () {
+            yield local(device(SIMULATOR, false)).startVideoRecording();
+            (0, chai_1.expect)(startStream.called, 'started the iPhone stream').to.equal(false);
+            (0, chai_1.expect)(startRecording.calledOnce).to.equal(true);
+            (0, chai_1.expect)(startRecording.firstCall.args[0]).to.deep.include({
+                udid: SIMULATOR,
+                mjpegPort: 9101,
+            });
+        }));
+        it("is still read from an iPhone's stream", () => __awaiter(this, void 0, void 0, function* () {
+            yield local(device(IPHONE, true)).startVideoRecording();
+            (0, chai_1.expect)(startStream.calledOnceWith(IPHONE)).to.equal(true);
+            (0, chai_1.expect)(startRecording.firstCall.args[0]).to.deep.include({ udid: IPHONE, mjpegPort: 9150 });
+        }));
+    });
+});

package/lib/test/unit/lease/lease-override.spec.js

@@ -26,14 +26,31 @@ describe('canOverrideLease — who may use a lease they did not create', () => {
             (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'api-key', scopes: 'admin', user: null })).to.equal(false);
         });
     });
-    describe('a session token (the user themselves, like a dashboard cookie)', () => {
-        it('is allowed for an ADMIN or SUPER_ADMIN', () => {
-            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', user: user('ADMIN') })).to.equal(true);
-            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', user: user('SUPER_ADMIN') })).to.equal(true);
+    // A session token carries the scopes of the credential that minted it, and
+    // is judged by them like a key. By role alone, an ADMIN's key without the
+    // admin scope minted itself a token that could override.
+    describe("a session token (judged by its scopes and its user's role now)", () => {
+        // resolveActor's rule (a SUPER_ADMIN, or a credential with `admin`), on
+        // the user's role now: the scope is fixed at mint, so an ADMIN's token
+        // also needs the role to still be ADMIN, which notices a demotion.
+        it("is allowed for an ADMIN's or SUPER_ADMIN's token carrying the admin scope", () => {
+            for (const role of ['ADMIN', 'SUPER_ADMIN']) {
+                (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', scopes: 'admin,sessions', user: user(role) })).to.equal(true);
+            }
+        });
+        // As their key pair overrides, and their Bearer token in per-command auth.
+        it("is allowed for a SUPER_ADMIN's token without the admin scope", () => {
+            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', scopes: 'sessions', user: user('SUPER_ADMIN') })).to.equal(true);
+        });
+        it('is refused for a token with the admin scope whose user is now a member', () => {
+            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', scopes: 'admin,sessions', user: user('MEMBER') })).to.equal(false);
+        });
+        it("is refused for an ADMIN's token without the admin scope", () => {
+            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', scopes: 'sessions', user: user('ADMIN') })).to.equal(false);
         });
         it('is refused for a member, or a user who is not active', () => {
-            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', user: user('MEMBER') })).to.equal(false);
-            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', user: null })).to.equal(false);
+            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', scopes: 'sessions', user: user('MEMBER') })).to.equal(false);
+            (0, chai_1.expect)((0, leaseOverride_1.canOverrideLease)({ kind: 'session-token', scopes: 'admin', user: null })).to.equal(false);
         });
     });
     it('is allowed with auth disabled, where every caller is a SUPER_ADMIN', () => {

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

@@ -83,8 +83,11 @@ const sessionCaps = (xenonOptions, extra = {}) => ({
 const key = (accessKey) => ({ accessKey, token: 'tk' });
 const ownerKey = key('ak_owner');
 const otherKey = key('ak_other');
-// A session token names its user in `sub`; the fake verifier echoes it back.
-const sessionToken = (sub) => ({ sessionToken: `jwt:${sub}` });
+// A session token names its user in `sub` and carries the scopes of the
+// credential that minted it; the fake verifier echoes both back.
+const sessionToken = (sub, scopes = 'sessions') => ({
+    sessionToken: `jwt:${sub}|${scopes}`,
+});
 const keys = {
     ak_owner: { id: 'key_owner', userId: 'usr_owner', scopes: 'sessions', teamId: null },
     ak_other: { id: 'key_other', userId: 'usr_other', scopes: 'sessions', teamId: null },
@@ -174,7 +177,10 @@ describe('createSession — a lease-bound session proves it holds the lease', ()
             findById: (id) => __awaiter(void 0, void 0, void 0, function* () { return roles[id] ? { id, role: roles[id], status: 'ACTIVE' } : null; }),
         });
         typedi_1.Container.set(JwtKeyService_1.JwtKeyService, {
-            verify: (t) => __awaiter(void 0, void 0, void 0, function* () { return ({ sub: t.replace(/^jwt:/, ''), teamId: null }); }),
+            verify: (t) => __awaiter(void 0, void 0, void 0, function* () {
+                const [sub, scopes] = t.replace(/^jwt:/, '').split('|');
+                return { sub, teamId: null, scopes };
+            }),
         });
         teamRows = sinon_1.default.stub(prisma_1.prisma.teamMember, 'findMany').resolves([]);
         sinon_1.default.stub(device_store_1.DeviceStoreFactory, 'getStore').returns({
@@ -331,8 +337,14 @@ describe('createSession — a lease-bound session proves it holds the lease', ()
         it("is allowed to a SUPER_ADMIN's key", () => __awaiter(void 0, void 0, void 0, function* () {
             (0, chai_1.expect)(yield allowed(sessionCaps(key('ak_super')))).to.equal(true);
         }));
+        // A session token minted from the dashboard carries the admin's admin
+        // scope; one minted with an ADMIN's narrower key doesn't, and overrides
+        // no more than that key does.
         it('is allowed to an ADMIN presenting a session token, as on the dashboard', () => __awaiter(void 0, void 0, void 0, function* () {
-            (0, chai_1.expect)(yield allowed(sessionCaps(sessionToken('usr_admin')))).to.equal(true);
+            (0, chai_1.expect)(yield allowed(sessionCaps(sessionToken('usr_admin', 'admin,sessions')))).to.equal(true);
+        }));
+        it("is refused to an ADMIN's session token minted without the admin scope", () => __awaiter(void 0, void 0, void 0, function* () {
+            (0, chai_1.expect)(yield refusal(sessionCaps(sessionToken('usr_admin', 'sessions')))).to.equal(REFUSED);
         }));
         it('is refused to a member presenting a session token', () => __awaiter(void 0, void 0, void 0, function* () {
             (0, chai_1.expect)(yield refusal(sessionCaps(sessionToken('usr_other')))).to.equal(REFUSED);

package/lib/test/unit/logcat-ws.spec.js

@@ -73,6 +73,10 @@ function harness(over) {
         const mux = new LogcatMultiplexer_1.LogcatMultiplexer();
         const state = { startCalls: 0, authorizeCalls: 0, authorizeActors: [] };
         const server = http_1.default.createServer();
+        const connectionsClosed = [];
+        server.on('connection', (socket) => {
+            connectionsClosed.push(new Promise((r) => socket.once('close', () => r())));
+        });
         const userAuthorize = (_a = over.authorize) !== null && _a !== void 0 ? _a : (() => __awaiter(this, void 0, void 0, function* () { return true; }));
         const deps = {
             redeem: (_b = over.redeem) !== null && _b !== void 0 ? _b : (() => __awaiter(this, void 0, void 0, function* () { return ({ actorId: 'usr_alice' }); })),
@@ -109,6 +113,13 @@ function harness(over) {
             get authorizeActors() {
                 return state.authorizeActors;
             },
+            serverSawClose: () => __awaiter(this, void 0, void 0, function* () {
+                yield Promise.all(connectionsClosed);
+                // ws emits the server WebSocket's 'close' from the TCP socket's 'close'
+                // listener, or from a process.nextTick after it (its receiver's
+                // 'finish'). Either has run by the event loop's next check phase.
+                yield new Promise((r) => setImmediate(r));
+            }),
             close: () => new Promise((r) => {
                 var _a;
                 // http.Server#close only fires its callback once every connection has
@@ -159,6 +170,50 @@ function connectCollecting(h_1) {
         return { code, got };
     });
 }
+/**
+ * Holds one handshake step until the test releases it, and says when the
+ * server has reached it, so a test acts while that step is in flight instead
+ * of guessing how long the steps before it take. Under load a fixed 50 ms
+ * wasn't enough: the client was still CONNECTING, and terminate() there
+ * raised an uncaught error.
+ */
+function heldStep() {
+    let enter = () => undefined;
+    let release = () => undefined;
+    const entered = new Promise((r) => (enter = r));
+    const released = new Promise((r) => (release = r));
+    return {
+        entered,
+        release,
+        /** For the stubbed step: marks it entered, then waits for the release. */
+        hold: () => __awaiter(this, void 0, void 0, function* () {
+            enter();
+            yield released;
+        }),
+    };
+}
+/**
+ * Connects, drops the connection once it is open and `step` is in flight,
+ * and resolves when the server has seen it go.
+ */
+function dropDuring(h, step) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const ws = new ws_1.WebSocket(url(h.port));
+        // terminate() waits for 'open', so it never raises the 'error' it raises on
+        // a CONNECTING socket. Any other unhandled 'error' would be an uncaught
+        // exception, failing whichever test is running when it lands.
+        ws.on('error', () => undefined);
+        yield Promise.all([new Promise((r) => ws.once('open', r)), step.entered]);
+        ws.terminate();
+        yield h.serverSawClose();
+    });
+}
+/**
+ * Lets the handshake run on after a held step is released. Everything after
+ * a step is promise continuations (the harness's steps do no I/O), so it has
+ * all run by the event loop's next check phase.
+ */
+const handshakeSettled = () => new Promise((r) => setImmediate(r));
 describe('attachLogcatWs handshake', () => {
     it('accepts a valid ticket for a device the caller may use', () => __awaiter(void 0, void 0, void 0, function* () {
         const h = yield harness({});
@@ -265,26 +320,21 @@ describe('attachLogcatWs handshake', () => {
     // The trap documented in h264StreamWs: without cleanup registered before the
     // awaits, clientCount stays inflated and the idle watchdog never fires.
     it('leaves no client registered when the socket drops mid-handshake during redeem', () => __awaiter(void 0, void 0, void 0, function* () {
-        let release = () => undefined;
-        const gate = new Promise((r) => (release = r));
+        const step = heldStep();
         const h = yield harness({
             redeem: () => __awaiter(void 0, void 0, void 0, function* () {
-                yield gate;
+                yield step.hold();
                 return { actorId: 'usr_alice' };
             }),
         });
-        const ws = new ws_1.WebSocket(url(h.port));
-        yield new Promise((r) => setTimeout(r, 50));
-        ws.terminate(); // disconnect while redeem is still pending
-        // Let the server actually observe the close (a real socket teardown is a
-        // macrotask; resolving `gate` below is a same-tick microtask chain that
-        // would otherwise race ahead of it) BEFORE unblocking redeem. Otherwise
-        // this proves nothing about the post-redeem guard: the client could get
-        // registered first and only be torn down afterward by the 'close'
-        // listener firing late — same end state, different (unguarded) mechanism.
-        yield new Promise((r) => setTimeout(r, 100));
-        release();
-        yield new Promise((r) => setTimeout(r, 150));
+        // Disconnect while redeem is still pending, and let the server see the
+        // close BEFORE redeem resolves. Otherwise this proves nothing about the
+        // post-redeem guard: the client could get registered first and only be
+        // torn down afterward by the 'close' listener firing late — same end
+        // state, different (unguarded) mechanism.
+        yield dropDuring(h, step);
+        step.release();
+        yield handshakeSettled();
         (0, chai_1.expect)(h.mux.clientCount).to.equal(0);
         // The final clientCount alone can't distinguish "the post-redeem guard
         // short-circuited" from "a later guard cleaned up after the fact" — both
@@ -301,20 +351,16 @@ describe('attachLogcatWs handshake', () => {
     // session owner) when the caller disconnects. Same reasoning as the two
     // neighbours — the observable is the adb spawn that must not happen.
     it('leaves no client registered when the socket drops mid-handshake during authorize', () => __awaiter(void 0, void 0, void 0, function* () {
-        let release = () => undefined;
-        const gate = new Promise((r) => (release = r));
+        const step = heldStep();
         const h = yield harness({
             authorize: () => __awaiter(void 0, void 0, void 0, function* () {
-                yield gate;
+                yield step.hold();
                 return true;
             }),
         });
-        const ws = new ws_1.WebSocket(url(h.port));
-        yield new Promise((r) => setTimeout(r, 50));
-        ws.terminate(); // disconnect while authorize is still pending
-        yield new Promise((r) => setTimeout(r, 100));
-        release();
-        yield new Promise((r) => setTimeout(r, 150));
+        yield dropDuring(h, step); // disconnect while authorize is still pending
+        step.release();
+        yield handshakeSettled();
         (0, chai_1.expect)(h.authorizeCalls, 'authorize was already in flight').to.equal(1);
         (0, chai_1.expect)(h.startCalls, 'must not start a logcat process once the caller is gone').to.equal(0);
         (0, chai_1.expect)(h.mux.clientCount).to.equal(0);
@@ -324,25 +370,20 @@ describe('attachLogcatWs handshake', () => {
     // but startStream (which can shell out to adb) is still in flight when the
     // caller disconnects.
     it('leaves no client registered when the socket drops mid-handshake during startStream', () => __awaiter(void 0, void 0, void 0, function* () {
-        let release = () => undefined;
-        const gate = new Promise((r) => (release = r));
+        const step = heldStep();
         const gatedMux = new LogcatMultiplexer_1.LogcatMultiplexer();
         const h = yield harness({
             startStream: () => __awaiter(void 0, void 0, void 0, function* () {
-                yield gate;
+                yield step.hold();
                 return { mux: gatedMux };
             }),
         });
-        const ws = new ws_1.WebSocket(url(h.port));
-        yield new Promise((r) => setTimeout(r, 50));
-        ws.terminate(); // disconnect while startStream is still pending
-        // See the matching comment in the redeem-timing test above: give the
-        // server's close listener time to actually run before startStream
-        // resolves, or this races the wrong way and proves nothing about the
-        // post-startStream guard.
-        yield new Promise((r) => setTimeout(r, 100));
-        release();
-        yield new Promise((r) => setTimeout(r, 150));
+        // As in the redeem test above: the server sees the close before
+        // startStream resolves, or this proves nothing about the post-startStream
+        // guard.
+        yield dropDuring(h, step);
+        step.release();
+        yield handshakeSettled();
         (0, chai_1.expect)(gatedMux.clientCount).to.equal(0);
         yield h.close();
     }));

package/lib/test/unit/logger-json-levels.spec.js

@@ -0,0 +1,44 @@
+"use strict";
+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 sinon_1 = __importDefault(require("sinon"));
+const logger_1 = require("../../src/logger");
+/**
+ * In JSON log mode every line was written through Appium's `info`, whatever
+ * its level: a debug line printed at `--log-level info`, and an error went to
+ * stdout, since Appium's console sends only its `error` level to stderr. Each
+ * line now goes out at its own level, as in text mode.
+ */
+describe('XenonLogger in JSON mode writes each line at its own level', () => {
+    let wasJson;
+    let base;
+    let logger;
+    beforeEach(() => {
+        wasJson = logger_1.XenonLogger.isJsonLogging;
+        logger_1.XenonLogger.configure({ enableJsonLogging: true });
+        base = {
+            debug: sinon_1.default.stub(),
+            info: sinon_1.default.stub(),
+            warn: sinon_1.default.stub(),
+            error: sinon_1.default.stub(),
+        };
+        logger = new logger_1.XenonLogger('probe');
+        logger.baseLogger = base;
+    });
+    afterEach(() => {
+        logger_1.XenonLogger.configure({ enableJsonLogging: wasJson });
+    });
+    for (const level of ['debug', 'info', 'warn', 'error']) {
+        it(level, () => {
+            logger[level](`a ${level} line`);
+            const written = Object.keys(base).filter((l) => base[l].called);
+            (0, chai_1.expect)(written).to.deep.equal([level]);
+            const entry = JSON.parse(base[level].firstCall.args[0]);
+            (0, chai_1.expect)(entry.level).to.equal(level);
+            (0, chai_1.expect)(entry.message).to.equal(`a ${level} line`);
+        });
+    }
+});

package/lib/test/unit/mcp-token-ttl.spec.js

@@ -0,0 +1,38 @@
+"use strict";
+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 sinon_1 = __importDefault(require("sinon"));
+const mcpTokenTtl_1 = require("../../src/services/token/mcpTokenTtl");
+/**
+ * XENON_MCP_TOKEN_TTL_SEC=abc made every xenon-mcp token's lifetime NaN.
+ * A value that isn't a whole number of seconds above 0 now warns and keeps
+ * the default.
+ */
+describe('XENON_MCP_TOKEN_TTL_SEC', () => {
+    it('is the default (a day) when unset or empty, without a warning', () => {
+        const warn = sinon_1.default.stub();
+        (0, chai_1.expect)((0, mcpTokenTtl_1.mcpTokenTtlSec)(undefined, warn)).to.equal(86400);
+        (0, chai_1.expect)((0, mcpTokenTtl_1.mcpTokenTtlSec)('', warn)).to.equal(86400);
+        (0, chai_1.expect)((0, mcpTokenTtl_1.mcpTokenTtlSec)('  ', warn)).to.equal(86400);
+        (0, chai_1.expect)(mcpTokenTtl_1.DEFAULT_MCP_TOKEN_TTL_SEC).to.equal(86400);
+        (0, chai_1.expect)(warn.called).to.equal(false);
+    });
+    it('is the number of seconds it gives', () => {
+        const warn = sinon_1.default.stub();
+        (0, chai_1.expect)((0, mcpTokenTtl_1.mcpTokenTtlSec)('3600', warn)).to.equal(3600);
+        (0, chai_1.expect)((0, mcpTokenTtl_1.mcpTokenTtlSec)(' 120 ', warn)).to.equal(120);
+        (0, chai_1.expect)(warn.called).to.equal(false);
+    });
+    for (const bad of ['abc', '0', '-60', '1.5', '1e400', 'Infinity', '12s']) {
+        it(`warns and keeps the default for "${bad}"`, () => {
+            const warn = sinon_1.default.stub();
+            (0, chai_1.expect)((0, mcpTokenTtl_1.mcpTokenTtlSec)(bad, warn)).to.equal(86400);
+            (0, chai_1.expect)(warn.calledOnce).to.equal(true);
+            (0, chai_1.expect)(warn.firstCall.args[0]).to.include('XENON_MCP_TOKEN_TTL_SEC');
+            (0, chai_1.expect)(warn.firstCall.args[0]).to.include(bad);
+        });
+    }
+});

package/lib/test/unit/observability-example-loki.spec.js

@@ -0,0 +1,25 @@
+"use strict";
+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 path_1 = __importDefault(require("path"));
+const js_yaml_1 = __importDefault(require("js-yaml"));
+/**
+ * The example Loki config set `limits_config.retention_period: 24h`, but Loki
+ * deletes nothing unless its compactor runs retention, so the logs it kept
+ * grew for ever. Loki 3 also refuses to start with retention enabled and no
+ * store for delete requests.
+ */
+describe('examples/observability/loki.yml', () => {
+    const config = js_yaml_1.default.load(fs_1.default.readFileSync(path_1.default.join(__dirname, '../../examples/observability/loki.yml'), 'utf8'));
+    it('keeps logs for the retention period it sets', () => {
+        var _a, _b, _c;
+        (0, chai_1.expect)(config.limits_config.retention_period).to.equal('24h');
+        (0, chai_1.expect)((_a = config.compactor) === null || _a === void 0 ? void 0 : _a.retention_enabled, 'compactor.retention_enabled').to.equal(true);
+        (0, chai_1.expect)((_b = config.compactor) === null || _b === void 0 ? void 0 : _b.delete_request_store, 'compactor.delete_request_store').to.equal(config.schema_config.configs[0].object_store);
+        (0, chai_1.expect)((_c = config.compactor) === null || _c === void 0 ? void 0 : _c.working_directory, 'compactor.working_directory').to.be.a('string');
+    });
+});

package/lib/test/unit/ocr-healing-tier-real-ocr.spec.js

@@ -0,0 +1,113 @@
+"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 sharp_1 = __importDefault(require("sharp"));
+const typedi_1 = require("typedi");
+const OcrHealingProvider_1 = require("../../src/services/healing/OcrHealingProvider");
+const OmniVisionService_1 = require("../../src/services/omni-vision/OmniVisionService");
+const container_registration_1 = require("../helpers/container-registration");
+/**
+ * The OCR healing tier, on a real screenshot read by a real Tesseract worker
+ * (the language data the plugin ships), with nothing stubbed between them.
+ *
+ * Through 2.14 the tier read `result.data.words` from tesseract.js, which
+ * since tesseract.js 6 returns text only unless asked: `words` was undefined,
+ * and the tier healed nothing, ever. Its tests stubbed the OCR with words, so
+ * none of them could see it. ocr-healing-tier.spec.ts covers the matching
+ * rules on stubbed words; this checks the whole tier reads a screen.
+ */
+describe('The OCR healing tier, reading a real screenshot', () => {
+    let restoreContainer;
+    let screenshot;
+    // A phone-like screen: four lines, 200 px apart, each at x 60. "Log out"
+    // and "Check in" come first, so a tier that took a lone "Log" for "Login",
+    // or a lone "in" for "Sign in", answers with the wrong line.
+    const WIDTH = 720;
+    const LINES = { 'Log out': 150, 'Check in': 350, 'Sign in': 550, Login: 750 };
+    const FONT_SIZE = 56;
+    /** Where a line's text is: from its cap height above the baseline to just below it. */
+    const band = (line) => ({
+        top: LINES[line] - FONT_SIZE,
+        bottom: LINES[line] + FONT_SIZE / 4,
+    });
+    before(() => __awaiter(void 0, void 0, void 0, function* () {
+        const text = Object.entries(LINES)
+            .map(([words, y]) => `<text x="60" y="${y}" font-family="Helvetica, Arial, sans-serif" font-size="${FONT_SIZE}" fill="#111">${words}</text>`)
+            .join('');
+        const png = yield (0, sharp_1.default)({
+            create: { width: WIDTH, height: 900, channels: 3, background: '#ffffff' },
+        })
+            .composite([
+            {
+                input: Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="900">${text}</svg>`),
+            },
+        ])
+            .png()
+            .toBuffer();
+        screenshot = png.toString('base64');
+        // An Omni-Vision of its own, whose worker this suite starts and ends.
+        restoreContainer = (0, container_registration_1.saveRegistrations)(OmniVisionService_1.OmniVisionService);
+        typedi_1.Container.set(OmniVisionService_1.OmniVisionService, new OmniVisionService_1.OmniVisionService());
+    }));
+    after(() => __awaiter(void 0, void 0, void 0, function* () {
+        const worker = typedi_1.Container.get(OmniVisionService_1.OmniVisionService).sharedWorker;
+        yield (worker === null || worker === void 0 ? void 0 : worker.terminate());
+        restoreContainer();
+    }));
+    /** An Android driver: no element answers an iOS predicate, so the tier says where the text is. */
+    const android = { findElement: () => __awaiter(void 0, void 0, void 0, function* () { return Promise.reject(new Error('unsupported locator')); }) };
+    const heal = (selector) => new OcrHealingProvider_1.OcrHealingProvider().heal({
+        sessionId: 'real-ocr-session',
+        driver: android,
+        strategy: 'xpath',
+        selector,
+        screenshotBase64: screenshot,
+    });
+    /** The healed element's box lies on `line`, starting where its text starts. */
+    const expectOnLine = (rect, line) => {
+        const { top, bottom } = band(line);
+        (0, chai_1.expect)(rect, 'rect').to.be.an('object');
+        (0, chai_1.expect)(rect.y, `top of the box, on "${line}"`).to.be.within(top, bottom);
+        (0, chai_1.expect)(rect.y + rect.height, `bottom of the box, on "${line}"`).to.be.within(top, bottom);
+        (0, chai_1.expect)(rect.x, 'left of the box').to.be.within(40, 80);
+    };
+    it('finds a two-word text on its line, not a lone word of it read earlier', () => __awaiter(void 0, void 0, void 0, function* () {
+        const healed = yield heal("//*[@text='Sign in']");
+        (0, chai_1.expect)(healed, 'healed').to.not.equal(null);
+        (0, chai_1.expect)(healed.id).to.match(/^healed_ocr_/);
+        (0, chai_1.expect)(healed.recommendedSelector).to.equal('ocr:text="Sign in"');
+        (0, chai_1.expect)(healed.text).to.equal('Sign in');
+        expectOnLine(healed.rect, 'Sign in');
+        // Both words: wider than "Sign" alone at this size.
+        (0, chai_1.expect)(healed.rect.width).to.be.above(150);
+        (0, chai_1.expect)(healed.confidence).to.be.within(0.6, 1);
+    }));
+    it('does not take a word that is only part of the text', () => __awaiter(void 0, void 0, void 0, function* () {
+        const healed = yield heal("//*[@text='Login']");
+        (0, chai_1.expect)(healed, 'healed').to.not.equal(null);
+        (0, chai_1.expect)(healed.text).to.equal('Login');
+        expectOnLine(healed.rect, 'Login');
+    }));
+    it('reads the text from the attribute the selector names, whatever its case', () => __awaiter(void 0, void 0, void 0, function* () {
+        const healed = yield heal("//android.widget.Button[@content-desc='check IN']");
+        (0, chai_1.expect)(healed, 'healed').to.not.equal(null);
+        (0, chai_1.expect)(healed.text).to.equal('Check in');
+        expectOnLine(healed.rect, 'Check in');
+    }));
+    it('heals nothing when the text is not on the screen', () => __awaiter(void 0, void 0, void 0, function* () {
+        (0, chai_1.expect)(yield heal("//*[@text='Sign up']")).to.equal(null);
+    }));
+});