@xenon-device-management/xenon 2.14.0 → 2.15.0

package/lib/test/unit/interceptor-visual-elements.spec.js

@@ -0,0 +1,192 @@
+"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 CommandInterceptor_1 = require("../../src/interceptors/CommandInterceptor");
+const HealingOrchestrator_1 = require("../../src/services/healing/HealingOrchestrator");
+const types_1 = require("../../src/services/healing/types");
+const OmniVisionService_1 = require("../../src/services/omni-vision/OmniVisionService");
+const SelfHealingSwitch_1 = require("../../src/services/settings/SelfHealingSwitch");
+const event_manager_1 = require("../../src/dashboard/event-manager");
+const IPluginArgs_1 = require("../../src/interfaces/IPluginArgs");
+const container_registration_1 = require("../helpers/container-registration");
+const scratch_database_1 = require("../helpers/scratch-database");
+/**
+ * Elements Xenon found in a screenshot (Omni-Vision's `-custom:ai-*` locators,
+ * and self-healing's OCR and Visual AI tiers) are boxes on the screen with an
+ * id of Xenon's own (`omni_*`, `healed_ocr*`, `healed_visual*`). The
+ * interceptor answers their commands itself. Through 2.14:
+ *
+ * - a `-custom:ai-*` findElement that matched nothing answered `unknown error`
+ *   ("NoSuchElement: AI Vision failed…"), and self-healing then ran on it;
+ * - a healed OCR or Visual AI element was tapped during the find, and the
+ *   test's own click tapped it again;
+ * - `getText` on a healed element answered Xenon's note about the match;
+ * - `setValue` never reached the element: Appium passes it (text, elementId),
+ *   and the interceptor read the text as the element id.
+ *
+ * No AI provider, OCR or phone: healing, OCR and the driver are stubbed.
+ */
+describe('Elements Xenon found in a screenshot', () => {
+    (0, scratch_database_1.useScratchDatabase)();
+    const SESSION = 'visual-session';
+    let pluginArgs;
+    let restoreContainer;
+    let attemptHealing;
+    let driver;
+    let omni;
+    beforeEach(() => {
+        pluginArgs = Object.assign({}, IPluginArgs_1.DefaultPluginArgs);
+        restoreContainer = (0, container_registration_1.saveRegistrations)(HealingOrchestrator_1.HealingOrchestrator, SelfHealingSwitch_1.SelfHealingSwitch);
+        typedi_1.Container.set(SelfHealingSwitch_1.SelfHealingSwitch, new SelfHealingSwitch_1.SelfHealingSwitch());
+        attemptHealing = sinon_1.default.stub().resolves(null);
+        typedi_1.Container.set(HealingOrchestrator_1.HealingOrchestrator, { attemptHealing });
+        sinon_1.default.stub(event_manager_1.DASHBORD_EVENT_MANAGER, 'afterSessionCommand').resolves();
+        omni = typedi_1.Container.get(OmniVisionService_1.OmniVisionService);
+        driver = {
+            sessionId: SESSION,
+            caps: { platformName: 'Android' },
+            performActions: sinon_1.default.stub().resolves(),
+            releaseActions: sinon_1.default.stub().resolves(),
+            findElement: sinon_1.default.stub().rejects(new Error('unexpected find')),
+            active: sinon_1.default.stub().resolves({ 'element-6066-11e4-a52e-4f735466cecf': 'field-1' }),
+            setValue: sinon_1.default.stub().resolves(null),
+            elementEnabled: sinon_1.default.stub().resolves(true),
+        };
+    });
+    afterEach(() => {
+        restoreContainer();
+        sinon_1.default.restore();
+    });
+    const run = (command, args, next = () => undefined) => typedi_1.Container.get(CommandInterceptor_1.CommandInterceptor).handle(() => __awaiter(void 0, void 0, void 0, function* () { return next(); }), driver, command, [...args, SESSION], pluginArgs, false);
+    const failure = (promise) => __awaiter(void 0, void 0, void 0, function* () {
+        try {
+            yield promise;
+        }
+        catch (err) {
+            return err;
+        }
+        throw new Error('expected the command to fail');
+    });
+    const tapsAt = () => driver.performActions.getCalls().map((c) => {
+        const move = c.args[0][0].actions[0];
+        return { x: move.x, y: move.y };
+    });
+    describe('a -custom:ai-* find that matches nothing', () => {
+        it('fails with the standard "no such element" error for ai-text', () => __awaiter(void 0, void 0, void 0, function* () {
+            sinon_1.default.stub(omni, 'findByText').resolves([]);
+            const err = yield failure(run('findElement', ['-custom:ai-text', 'Checkout']));
+            (0, chai_1.expect)(err.error).to.equal('no such element');
+            (0, chai_1.expect)(err.w3cStatus).to.equal(404);
+        }));
+        it('fails with the standard "no such element" error for ai-icon', () => __awaiter(void 0, void 0, void 0, function* () {
+            sinon_1.default.stub(omni, 'findByIcon').resolves(null);
+            const err = yield failure(run('findElement', ['-custom:ai-icon', 'a cart icon']));
+            (0, chai_1.expect)(err.error).to.equal('no such element');
+        }));
+        it('is not handed to self-healing', () => __awaiter(void 0, void 0, void 0, function* () {
+            sinon_1.default.stub(omni, 'findByText').resolves([]);
+            yield failure(run('findElement', ['-custom:ai-text', 'Checkout']));
+            (0, chai_1.expect)(attemptHealing.called).to.equal(false);
+        }));
+        it('still answers an empty list to findElements', () => __awaiter(void 0, void 0, void 0, function* () {
+            sinon_1.default.stub(omni, 'findByText').resolves([]);
+            (0, chai_1.expect)(yield run('findElements', ['-custom:ai-text', 'Checkout'])).to.deep.equal([]);
+        }));
+    });
+    describe('a healed OCR or Visual AI element', () => {
+        const healedBy = (id, tier, text) => (Object.assign({ id,
+            tier, confidence: 0.9, originalSelector: "//*[@text='Login']", originalStrategy: 'xpath', recommendedSelector: 'ocr:text="Login"', recommendedStrategy: 'xenon:visual', message: 'Found text "Login" via local OCR (90% confidence)', rect: { x: 100, y: 400, width: 80, height: 24 } }, (text !== undefined ? { text } : {})));
+        const findHealed = (healed) => __awaiter(void 0, void 0, void 0, function* () {
+            attemptHealing.resolves(healed);
+            return run('findElement', ['xpath', "//*[@text='Login']"], () => {
+                throw Object.assign(new Error('NoSuchElement: gone'), { name: 'NoSuchElementError' });
+            });
+        });
+        it('is not tapped during the find', () => __awaiter(void 0, void 0, void 0, function* () {
+            const found = yield findHealed(healedBy('healed_ocr_1', types_1.HealingTier.TIER_3_LOCAL_OCR, 'Login'));
+            (0, chai_1.expect)(found).to.deep.include({ 'element-6066-11e4-a52e-4f735466cecf': 'healed_ocr_1' });
+            (0, chai_1.expect)(driver.performActions.called, 'tapped during the find').to.equal(false);
+        }));
+        it("is tapped once, by the test's own click", () => __awaiter(void 0, void 0, void 0, function* () {
+            yield findHealed(healedBy('healed_visual_1', types_1.HealingTier.TIER_4_VISUAL_AI));
+            yield run('click', ['healed_visual_1']);
+            (0, chai_1.expect)(tapsAt()).to.deep.equal([{ x: 140, y: 412 }]);
+        }));
+        it('answers getText with the text OCR read, not a note about the match', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield findHealed(healedBy('healed_ocr_2', types_1.HealingTier.TIER_3_LOCAL_OCR, 'Login'));
+            (0, chai_1.expect)(yield run('getText', ['healed_ocr_2'])).to.equal('Login');
+        }));
+        it('refuses getText when Visual AI found it, since no text was read', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield findHealed(healedBy('healed_visual_2', types_1.HealingTier.TIER_4_VISUAL_AI));
+            const err = yield failure(run('getText', ['healed_visual_2']));
+            (0, chai_1.expect)(err.error).to.equal('unsupported operation');
+            (0, chai_1.expect)(err.message).to.match(/text/i);
+        }));
+    });
+    describe('setValue on an element found in a screenshot', () => {
+        beforeEach(() => {
+            omni.remember(SESSION, {
+                id: 'omni_ocr_field',
+                text: 'Email',
+                rect: { x: 10, y: 20, width: 100, height: 40 },
+                confidence: 0.9,
+            });
+        });
+        it('taps it, then types into the field that has the keyboard focus', () => __awaiter(void 0, void 0, void 0, function* () {
+            yield run('setValue', ['me@example.com', 'omni_ocr_field']);
+            (0, chai_1.expect)(tapsAt()).to.deep.equal([{ x: 60, y: 40 }]);
+            (0, chai_1.expect)(driver.active.calledAfter(driver.performActions)).to.equal(true);
+            (0, chai_1.expect)(driver.setValue.firstCall.args.slice(0, 2)).to.deep.equal([
+                'me@example.com',
+                'field-1',
+            ]);
+        }));
+        it('refuses before tapping when the driver cannot tell which field has the focus', () => __awaiter(void 0, void 0, void 0, function* () {
+            delete driver.active;
+            const err = yield failure(run('setValue', ['me@example.com', 'omni_ocr_field']));
+            (0, chai_1.expect)(err.error).to.equal('unsupported operation');
+            (0, chai_1.expect)(driver.performActions.called, 'tapped').to.equal(false);
+        }));
+        it('says so when no field took the focus after the tap', () => __awaiter(void 0, void 0, void 0, function* () {
+            driver.active.rejects(new Error('no element has focus'));
+            const err = yield failure(run('setValue', ['me@example.com', 'omni_ocr_field']));
+            (0, chai_1.expect)(err.error).to.equal('element not interactable');
+            (0, chai_1.expect)(driver.setValue.called).to.equal(false);
+        }));
+    });
+    describe('other commands on an element found in a screenshot', () => {
+        it("refuses them clearly instead of sending Xenon's id to the driver", () => __awaiter(void 0, void 0, void 0, function* () {
+            omni.remember(SESSION, {
+                id: 'omni_ai_cart',
+                rect: { x: 0, y: 0, width: 40, height: 40 },
+                confidence: 0.85,
+            });
+            const next = sinon_1.default.stub();
+            const err = yield failure(run('getAttribute', ['content-desc', 'omni_ai_cart'], next));
+            (0, chai_1.expect)(err.error).to.equal('unsupported operation');
+            (0, chai_1.expect)(next.called, 'sent to the driver').to.equal(false);
+        }));
+    });
+    describe('autowait before setValue on a real element', () => {
+        it('waits for the element, not for an element named after the text', () => __awaiter(void 0, void 0, void 0, function* () {
+            pluginArgs = Object.assign(Object.assign({}, IPluginArgs_1.DefaultPluginArgs), { autowait: Object.assign(Object.assign({}, IPluginArgs_1.DefaultPluginArgs.autowait), { enabled: true }) });
+            yield run('setValue', ['hello', 'el-1']);
+            (0, chai_1.expect)(driver.elementEnabled.firstCall.args[0]).to.equal('el-1');
+        }));
+    });
+});

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/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);
+    }));
+});

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

@@ -0,0 +1,122 @@
+"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 OcrHealingProvider_1 = require("../../src/services/healing/OcrHealingProvider");
+const OmniVisionService_1 = require("../../src/services/omni-vision/OmniVisionService");
+const VisualAiHealingProvider_1 = require("../../src/services/healing/VisualAiHealingProvider");
+const AIService_1 = require("../../src/services/AIService");
+/**
+ * Self-healing's OCR tier took the first word OCR read that contained the
+ * text, or was part of it: for `Sign in` that was any lone "in" or "Sign" on
+ * the screen, and for `Login` a "Log". It now matches as Omni-Vision's
+ * `-custom:ai-text` does (ocrTextMatch.ts): the text across neighbouring words
+ * on one line, the first match in reading order.
+ *
+ * OCR is stubbed with the words it would read, in screenshot pixels: no
+ * Tesseract runs. ocr-healing-tier-real-ocr.spec.ts runs the tier on a real
+ * screenshot, which a stub can't stand in for: tesseract.js's own output is
+ * what hid the tier's never healing.
+ */
+describe('The OCR healing tier matches text as Omni-Vision does', () => {
+    const word = (text, x0, y0, x1, y1) => ({
+        text,
+        confidence: 90,
+        bbox: { x0, y0, x1, y1 },
+    });
+    // A heading with "Log" and a lone "in" read first; then "Sign in", far
+    // from "Help" on its line; then "Login".
+    const WORDS = [
+        word('Log', 40, 60, 90, 84),
+        word('in', 300, 60, 320, 84),
+        word('Sign', 100, 200, 150, 224),
+        word('in', 158, 200, 180, 224),
+        word('Help', 600, 200, 650, 224),
+        word('Login', 100, 400, 180, 424),
+    ];
+    let driver;
+    beforeEach(() => {
+        // OCR reads these words: the tier asks Omni-Vision's OCR.
+        sinon_1.default
+            .stub(typedi_1.Container.get(OmniVisionService_1.OmniVisionService), 'performOcr')
+            .resolves({ text: '', words: WORDS });
+        // Android: no element is found by an iOS predicate, so the tier answers
+        // with where the text is.
+        driver = { findElement: sinon_1.default.stub().rejects(new Error('unsupported locator strategy')) };
+    });
+    afterEach(() => sinon_1.default.restore());
+    const heal = (selector) => new OcrHealingProvider_1.OcrHealingProvider().heal({
+        sessionId: 'ocr-session',
+        driver,
+        strategy: 'xpath',
+        selector,
+        screenshotBase64: 'aGVsbG8=',
+    });
+    it('finds a two-word text across its words, not a lone word of it', () => __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.recommendedSelector).to.equal('ocr:text="Sign in"');
+        (0, chai_1.expect)(healed.rect).to.deep.equal({ x: 100, y: 200, width: 80, height: 24 });
+    }));
+    it('hands on the text it read, for getText on the element it returns', () => __awaiter(void 0, void 0, void 0, function* () {
+        const healed = yield heal("//*[@text='sign IN']");
+        (0, chai_1.expect)(healed.text).to.equal('Sign in');
+        (0, chai_1.expect)(healed.message).to.not.equal(healed.text);
+    }));
+    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.recommendedSelector).to.equal('ocr:text="Login"');
+        (0, chai_1.expect)(healed.rect).to.deep.equal({ x: 100, y: 400, width: 80, height: 24 });
+    }));
+    it('finds 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);
+    }));
+});
+/**
+ * A healed element's id names it in the server's memory of virtual elements,
+ * which every session shares. `healed_ocr_<ms>` was the same for two heals in
+ * one millisecond, so the second overwrote the first.
+ */
+describe('Elements healed by OCR or Visual AI', () => {
+    afterEach(() => sinon_1.default.restore());
+    const context = {
+        sessionId: 'ids-session',
+        driver: { findElement: () => __awaiter(void 0, void 0, void 0, function* () { return Promise.reject(new Error('no predicate')); }) },
+        strategy: 'xpath',
+        selector: "//*[@text='Login']",
+        screenshotBase64: 'aGVsbG8=',
+    };
+    it('get ids of their own when healed in the same millisecond', () => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b, _c, _d;
+        sinon_1.default.stub(Date, 'now').returns(1700000000000);
+        sinon_1.default.stub(typedi_1.Container.get(OmniVisionService_1.OmniVisionService), 'performOcr').resolves({
+            text: '',
+            words: [{ text: 'Login', confidence: 90, bbox: { x0: 1, y0: 1, x1: 50, y1: 20 } }],
+        });
+        sinon_1.default.stub(AIService_1.AI_SERVICE, 'isEnabled').returns(true);
+        sinon_1.default.stub(AIService_1.AI_SERVICE, 'visualFind').resolves({ x: 100, y: 100 });
+        const ids = [
+            (_a = (yield new OcrHealingProvider_1.OcrHealingProvider().heal(context))) === null || _a === void 0 ? void 0 : _a.id,
+            (_b = (yield new OcrHealingProvider_1.OcrHealingProvider().heal(context))) === null || _b === void 0 ? void 0 : _b.id,
+            (_c = (yield new VisualAiHealingProvider_1.VisualAiHealingProvider().heal(context))) === null || _c === void 0 ? void 0 : _c.id,
+            (_d = (yield new VisualAiHealingProvider_1.VisualAiHealingProvider().heal(context))) === null || _d === void 0 ? void 0 : _d.id,
+        ];
+        (0, chai_1.expect)(ids.every(Boolean), String(ids)).to.equal(true);
+        (0, chai_1.expect)(new Set(ids).size, String(ids)).to.equal(4);
+    }));
+});