mobile-automator 0.23.8

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2025 Mobile QA Skills Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,167 @@
+# 🚀 Mobile Automator
+
+> **Turn your AI coding agent into a mobile QA engineer.**
+
+`mauto` is a host-agnostic CLI that lets **any** AI coding agent author and run UI tests on a real device or emulator. The agent decides *what* to do; `mauto` does it — tap, type, swipe, assert — through [mobile-mcp](https://github.com/mobile-next/mobile-mcp). Tests are plain JSON scenarios, **platform-agnostic** by default, so the same scenario runs on Android and iOS.
+
+Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents all have one-command setup via `mauto init --agent <claude|cursor|gemini|copilot|agents|all>`, which installs native Agent Skills into each host's skills directory (claude and cursor also get slash-commands/rules and the `mauto` MCP entry); any other MCP-capable agent connects via the `mauto mcp` prompts server. See [Using another agent](#-using-another-agent).
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Android%20%7C%20iOS%20%7C%20Flutter%20%7C%20RN%20%7C%20KMP%20%7C%20CMP-green.svg)](#)
+[![Node](https://img.shields.io/badge/Node-%E2%89%A518-brightgreen.svg)](#)
+
+---
+
+## ⏱️ Quick start (5 minutes)
+
+**You need:** Node ≥ 18 · an AI coding agent · a running emulator/simulator or a connected device.
+
+> This quick start uses **Claude Code** as the example agent. For Cursor, swap `--agent claude` → `--agent cursor`. For any other agent, see [Using another agent](#-using-another-agent).
+
+**1. Install `mauto`** (from source — not yet on npm):
+
+```bash
+git clone https://github.com/sh3lan93/mobile-automator
+cd mobile-automator
+npm install && npm link        # exposes `mauto` globally
+```
+
+**2. Wire it into your project and agent:**
+
+```bash
+cd ~/projects/my-app
+mauto init --agent claude      # or: cursor | gemini | copilot | agents | all
+mauto setup                    # scaffolds mobile-automator/ + config
+```
+
+`init` installs native Agent Skills into each host's skills directory and writes agent command files + MCP server entry (`.claude/commands/` + `.mcp.json` for Claude Code; `.cursor/` for Cursor). `setup` creates the `mobile-automator/` workspace. Add `--mode agnostic` to `setup` for cross-platform apps (Flutter/RN/KMP/CMP).
+
+**3. Check your device is visible:**
+
+```bash
+mauto devices                  # lists devices; `mauto devices use <id>` to pin one
+```
+
+**4. Author and run a test — from inside your agent:**
+
+Open your agent in the project. In **Claude Code**, `init` installs slash commands:
+
+```
+/mobile-automator-generate     → describe a flow in plain English; the agent
+                                 drives the app and writes a scenario JSON
+
+/mobile-automator-execute      → the agent replays the scenario and reports
+                                 pass/fail with diagnostics
+```
+
+In **Cursor**, `init` installs a project rule instead — just ask the agent in plain language (e.g. *"generate a login test"* / *"execute the login scenario"*) and it follows the same workflow. **Any other agent:** see [Using another agent](#-using-another-agent) below.
+
+That's it. Scenarios land in `mobile-automator/scenarios/`, results in `mobile-automator/results/`.
+
+---
+
+## 🧠 How it works
+
+`mauto` splits the work into a **brain** and **hands**:
+
+- **The agent (brain)** resolves targets ("the Login button"), judges visual assertions, and assembles scenarios. It reads workflow guidance on demand with `mauto guide <topic>`.
+- **`mauto` (hands)** performs deterministic, scriptable actions and mechanical assertions, driving the device via mobile-mcp. Every verb emits a uniform JSON envelope (`{ok, data, error, hint}`); add `--human` for readable output.
+
+Targets are always **visible text + semantic role + coordinates** — never brittle resource-ids — which is what makes scenarios portable across Android and iOS.
+
+```
+   Your agent  ──drives──▶  mauto verbs  ──wrap──▶  mobile-mcp  ──▶  device
+   (decisions)             (deterministic)        (automation)
+```
+
+Because the contract is just verbs + JSON, **no agent is special** — `mauto init` ships native Agent Skills for Claude Code, Cursor, Gemini CLI, GitHub Copilot, and OpenAI Agents, but any agent that can run a shell command or speak MCP can drive the same tool.
+
+---
+
+## 🤖 Using another agent
+
+`mauto init` ships native Agent Skills for **Claude Code**, **Cursor**, **Gemini CLI**, **GitHub Copilot** (`copilot`), and **OpenAI Agents** (`agents`); use `--agent all` to install for all hosts at once. Any other AI agent can drive `mauto` through one of these, no adapter required:
+
+- **MCP (recommended):** point your MCP-capable agent at the prompts server — `mauto mcp` (stdio) — which exposes the `generate` / `execute` / `setup` workflows as prompts. Register it like any MCP server: command `mauto`, args `["mcp"]`.
+- **Plain shell:** have the agent read `mauto bootstrap` once (the verb map + invariants), then read `mauto guide <topic>` for a workflow and call the verbs (`mauto elements`, `tap`, `type`, `assert`, …) directly. Every verb returns the `{ok, data, error, hint}` envelope, so the agent can act on results programmatically.
+
+Either way the workspace, scenarios, and schemas are identical — the agent is just a different driver for the same `mauto` hands.
+
+---
+
+## 🔀 Platform modes
+
+Chosen at `mauto setup` (stored in `mobile-automator/config.json`):
+
+| Mode | Best for | Enable |
+|------|----------|--------|
+| **platform-aware** (default) | Single-OS / OS-specific UI | `mauto setup` |
+| **platform-agnostic** | Cross-platform (Flutter, RN, KMP, CMP) | `mauto setup --mode agnostic` |
+
+In agnostic mode, OS-shaped gestures become four semantic actions — `press_back`, `dismiss_keyboard`, `grant_permission`, `deny_permission` — resolved to the right native primitive at runtime, so one scenario covers both platforms.
+
+---
+
+## 📋 Command reference
+
+Most low-level verbs are called **by the agent**, not by you. The ones you'll run directly are at the top.
+
+| Command | What it does |
+|---------|--------------|
+| `mauto init --agent <claude\|cursor\|gemini\|copilot\|agents\|all>` | Install native Agent Skills into each host's skills directory; also writes slash-commands/rules + MCP entry for claude/cursor |
+| `mauto setup [--mode aware\|agnostic]` | Scaffold the `mobile-automator/` workspace + config |
+| `mauto devices` · `devices use <id>` · `devices clear` | List / pin / unpin the target device |
+| `mauto guide <generate\|execute\|setup>` | Print the workflow guidance for a topic |
+| `mauto mcp` | Run the MCP prompts server (for any MCP-capable agent) |
+| `mauto bootstrap` | Print the verb map + invariants (onboarding for any agent) |
+| `mauto memory show [--kind <k>] [--scenario <id>]` | Print cross-session memory (run history auto-harvested from results) as raw markdown for the agent to read at run start |
+| `mauto memory add <text> --kind <app-knowledge\|preferences>` | Record a durable agent-learned app fact or user preference (`[asserted]`, de-duped) |
+| `mauto memory forget --kind <k> --match <substr>` | Remove agent-authored memory entries matching a substring (the correction path) |
+| `mauto validate <file>` | Validate a scenario JSON against the schema |
+| `mauto config get\|set <key> [value]` | Read / update workspace config |
+| **Agent-driven verbs** | `elements`, `tap`, `type`, `swipe`, `press`, `screenshot`, `assert`, `result`, `schema` |
+
+Run `mauto <command> --help` for full flags.
+
+---
+
+## 📂 Workspace layout
+
+After `mauto setup`:
+
+```
+mobile-automator/
+├── config.json        # mode, environments, project config
+├── scenarios/         # test scenarios (JSON, schema 2.1)
+├── screenshots/       # reference screenshots
+└── results/           # execution results
+```
+
+Scenario, result, and config schemas: `mauto schema scenario` / `mauto schema result` / `mauto schema config`.
+
+---
+
+## 🐛 Troubleshooting
+
+See **[TROUBLESHOOTING.md](TROUBLESHOOTING.md)**.
+
+## 🤝 Contributing
+
+Contributions welcome under Apache 2.0. Good first areas: platform support, assertion types, CI/CD integrations.
+
+## 📄 License
+
+[Apache License 2.0](LICENSE).
+
+## 🙏 Acknowledgments
+
+- **[mobile-mcp](https://github.com/mobile-next/mobile-mcp)** — the device-automation engine `mauto` wraps.
+- **[Conductor](https://github.com/gemini-cli-extensions/conductor)** — inspired the structured-workflow approach.
+
+---
+
+<div align="center">
+
+**Built for mobile QA engineers** · [Report a bug](https://github.com/sh3lan93/mobile-automator/issues) · [Request a feature](https://github.com/sh3lan93/mobile-automator/issues)
+
+</div>

package/bin/mauto-session-daemon.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+'use strict';
+
+// Detached entrypoint for the device session daemon. session-spawn.js launches
+// this with the project root / device / idle timeout passed via env vars.
+//
+// Kept dependency-light and side-effect-free at require time so the unit smoke
+// test can load it without spawning a daemon: startDaemon only runs under
+// `require.main === module`.
+
+const fs = require('fs');
+
+const { startDaemon } = require('../src/device/session-daemon');
+const paths = require('../src/device/session-paths');
+
+// Best-effort synchronous unlink — never throws. Used by the crash guards so a
+// hard failure can't leave a stale lock/socket/pidfile wedging the next spawn.
+function safeUnlinkSync(p) {
+  try {
+    fs.unlinkSync(p);
+  } catch (_) {
+    /* not present */
+  }
+}
+
+// Tear down this process's workspace files (lock/socket/pid/handle) on exit —
+// but ONLY if we still own the lock (it holds our pid). This is load-bearing
+// for the spawn race: a loser whose startDaemon threw ELOCKED never acquired
+// the lock, so it must NOT delete the winner's files. Deleting them would free
+// the lock and unlink the live socket path, so the next client re-spawns and a
+// second mobile-mcp child starts — the exact C2/B2 orphan the lock prevents.
+// Gating on the lock's pid also stops a departing owner from nuking a successor
+// that has already taken over the workspace.
+function cleanupWorkspaceIfOwned(projectRoot) {
+  let owner;
+  try {
+    owner = fs.readFileSync(paths.lockPath(projectRoot), 'utf8').trim();
+  } catch (_) {
+    return; // no lock present — nothing of ours to clean
+  }
+  if (owner !== String(process.pid)) return; // not our lock — leave the owner's files
+  safeUnlinkSync(paths.lockPath(projectRoot));
+  safeUnlinkSync(paths.socketPath(projectRoot));
+  safeUnlinkSync(paths.pidFilePath(projectRoot));
+  safeUnlinkSync(paths.handlePath(projectRoot));
+}
+
+async function main() {
+  const projectRoot = process.env.MAUTO_SESSION_PROJECT_ROOT;
+  if (!projectRoot) {
+    process.stderr.write('mauto-session-daemon: MAUTO_SESSION_PROJECT_ROOT is required\n');
+    process.exit(3);
+  }
+  const device = process.env.MAUTO_SESSION_DEVICE || null;
+  const idleRaw = process.env.MAUTO_SESSION_IDLE_MS;
+  const idleMs = idleRaw ? Number(idleRaw) : undefined;
+
+  let daemon = null;
+
+  // Crash guards: this is the real, single-daemon process, so a best-effort
+  // teardown on a crash keeps a leaked mobile-mcp child / stale files from
+  // wedging the next spawn. (Kept OUT of startDaemon so in-process tests that
+  // start many daemons don't accumulate global listeners.)
+  // 'exit' allows only synchronous work — drop the lock + socket + pidfile so
+  // the next spawn isn't wedged by leftovers from this process.
+  const onExit = () => cleanupWorkspaceIfOwned(projectRoot);
+  process.on('exit', onExit);
+  process.on('uncaughtException', (err) => {
+    process.stderr.write(`mauto-session-daemon: uncaught ${err && err.stack ? err.stack : err}\n`);
+    // Tear the daemon down (closes the mobile-mcp child) then let 'exit' clean
+    // the files.
+    if (daemon && typeof daemon.stop === 'function') {
+      daemon.stop().catch(() => {});
+    }
+    process.exit(1);
+  });
+  process.on('unhandledRejection', (err) => {
+    process.stderr.write(`mauto-session-daemon: unhandled rejection ${err && err.stack ? err.stack : err}\n`);
+    // Same teardown as uncaughtException: a rejected promise must not leave a
+    // leaked mobile-mcp child / stale files wedging the next spawn.
+    if (daemon && typeof daemon.stop === 'function') {
+      daemon.stop().catch(() => {});
+    }
+    process.exit(1);
+  });
+
+  daemon = await startDaemon({ projectRoot, device, idleMs });
+  // Keep the event loop alive until the daemon stops (idle reap / signal /
+  // shutdown frame), then exit cleanly.
+  await daemon.whenStopped;
+  process.exit(0);
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`mauto-session-daemon: ${err.message || err}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = { main, cleanupWorkspaceIfOwned };

package/bin/mauto.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+
+const { run, emitFatal } = require('../src/cli');
+
+// Final safety net for the envelope contract (#120): a stray async rejection
+// that escapes the in-program boundary still becomes one JSON envelope + the
+// mapped exit code instead of a raw stack trace. Registered here, at the
+// process entry point, so importing/testing the CLI never installs a global
+// exit-on-reject listener.
+process.on('unhandledRejection', emitFatal);
+
+run(process.argv);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "mobile-automator",
+  "version": "0.23.8",
+  "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
+  "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sh3lan93/mobile-automator.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sh3lan93/mobile-automator/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Mobile QA Skills Contributors",
+  "bin": {
+    "mauto": "bin/mauto.js",
+    "mobile-automator": "bin/mauto.js",
+    "mauto-session-daemon": "bin/mauto-session-daemon.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "scripts": {
+    "test": "jest",
+    "prepublishOnly": "npm test",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "lint:guides": "jest tests/lint/guide-no-mcp-tool-leak.test.js tests/lint/guide-no-placeholder-leak.test.js tests/lint/guide-agnostic-no-os.test.js tests/lint/guide-artifact-reuse.test.js tests/lint/skill-invariants.test.js tests/lint/skill-no-placeholder-leak.test.js tests/lint/skill-frontmatter-valid.test.js tests/lint/config-schema.test.js tests/lint/result-coverage.test.js",
+    "lint:schema-additive": "jest tests/lint/schema-additive.test.js",
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest tests/integration",
+    "test:all": "jest"
+  },
+  "dependencies": {
+    "@mobilenext/mobile-mcp": "0.0.55",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ajv": "^8.20.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "toml": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/assertion/evaluator.js

@@ -0,0 +1,285 @@
+'use strict';
+
+// Pure assertion evaluator.
+//
+// The `mauto guide execute` reasoning floor splits the 27 assertion types into
+// two tiers:
+//
+//   Tier 1 — element-list-powered. These are purely MECHANICAL: a deterministic
+//            check over the agnostic element list (+ captured variables / a
+//            previous snapshot). The CLI owns them.
+//
+//   Tier 2 — screenshot + AI visual analysis. These require an agent to judge a
+//            screenshot, so the CLI cannot decide pass/fail. We surface them as
+//            needs_agent with pass = null.
+//
+// MECHANICAL_TYPES is the verbatim Tier-1 list from that guide section,
+// minus `element_state` whose per-attribute state
+// inspection is not represented in the agnostic element model (no enabled/
+// focused/checked fields survive normalization), so it cannot be decided
+// mechanically here and falls through to needs_agent.
+const MECHANICAL_TYPES = new Set([
+  'element_exists',
+  'element_not_exists',
+  'element_visible',
+  'element_text',
+  'text_contains',
+  'text_not_empty',
+  'element_hint',
+  'pattern_match',
+  'element_count',
+  'list_item_count',
+  'list_is_empty',
+  'content_description',
+  'has_accessibility_label',
+  'value_matches_variable',
+  'text_changed',
+]);
+
+function labelOf(e) {
+  return (e && typeof e.accessibility_label === 'string') ? e.accessibility_label : '';
+}
+
+// The element's displayed content for content assertions. A real text node
+// wins; when an element carries none (common in agnostic UIs that expose
+// content through Semantics/accessibility labels rather than text), fall back
+// to the accessibility label so content assertions work on label-driven apps
+// instead of always seeing an empty string.
+function textOf(e) {
+  if (e && typeof e.text === 'string' && e.text.length > 0) return e.text;
+  return labelOf(e);
+}
+
+// An element "matches" a target string if the target appears (case-insensitive)
+// in its text or its accessibility label. A null/empty target matches all.
+function matches(e, target) {
+  if (target === undefined || target === null || target === '') return true;
+  const needle = String(target).toLowerCase();
+  return (
+    textOf(e).toLowerCase().includes(needle) ||
+    labelOf(e).toLowerCase().includes(needle)
+  );
+}
+
+function findFirst(elements, target) {
+  return elements.find((e) => matches(e, target)) || null;
+}
+
+function countMatching(elements, target) {
+  return elements.filter((e) => matches(e, target)).length;
+}
+
+function compare(actual, operator, expected) {
+  switch (operator) {
+    case '>':
+      return actual > expected;
+    case '>=':
+      return actual >= expected;
+    case '<':
+      return actual < expected;
+    case '<=':
+      return actual <= expected;
+    case '!=':
+      return actual !== expected;
+    case '==':
+    case '=':
+    case undefined:
+    case null:
+    default:
+      return actual === expected;
+  }
+}
+
+function boolFromFlag(v, dflt = true) {
+  if (v === undefined || v === null || v === '') return dflt;
+  if (typeof v === 'boolean') return v;
+  return String(v).toLowerCase() !== 'false';
+}
+
+function result(type, mechanical, pass, message) {
+  return {
+    type,
+    mechanical,
+    pass,
+    needs_agent: !mechanical,
+    message,
+  };
+}
+
+function needsAgent(type) {
+  return result(
+    type,
+    false,
+    null,
+    `Assertion '${type}' is a Tier-2 visual check; the agent must judge it from a screenshot.`
+  );
+}
+
+// Evaluate a single assertion.
+//   assertion: { type, target?, expected?, operator?, count?, pattern?, variable_name? }
+//   ctx:       { elements, variables = {}, previous = null }
+function evaluate(assertion = {}, ctx = {}) {
+  const type = assertion.type;
+  const elements = Array.isArray(ctx.elements) ? ctx.elements : [];
+  const variables = ctx.variables || {};
+  const previous = Array.isArray(ctx.previous) ? ctx.previous : null;
+
+  if (!MECHANICAL_TYPES.has(type)) {
+    return needsAgent(type);
+  }
+
+  const target = assertion.target;
+  let pass = false;
+  let message = '';
+
+  switch (type) {
+    case 'element_exists': {
+      const found = findFirst(elements, target);
+      pass = Boolean(found);
+      message = pass
+        ? `Element matching '${target}' is present.`
+        : `No element matching '${target}' found on screen.`;
+      break;
+    }
+    case 'element_not_exists': {
+      const found = findFirst(elements, target);
+      pass = !found;
+      message = pass
+        ? `Element matching '${target}' is absent, as expected.`
+        : `Element matching '${target}' is present but expected to be absent.`;
+      break;
+    }
+    case 'element_visible': {
+      const wantVisible = boolFromFlag(assertion.expected, true);
+      const found = Boolean(findFirst(elements, target));
+      pass = found === wantVisible;
+      message = pass
+        ? `Element '${target}' visibility=${found} matches expected=${wantVisible}.`
+        : `Element '${target}' visibility=${found} but expected=${wantVisible}.`;
+      break;
+    }
+    case 'element_text': {
+      const found = findFirst(elements, target);
+      const actual = found ? textOf(found) : null;
+      pass = actual !== null && actual === assertion.expected;
+      message = pass
+        ? `Element '${target}' text equals '${assertion.expected}'.`
+        : `Element '${target}' text is '${actual}', expected '${assertion.expected}'.`;
+      break;
+    }
+    case 'text_contains': {
+      const needle = String(assertion.expected == null ? '' : assertion.expected);
+      const scope = assertion.target ? elements.filter((e) => matches(e, assertion.target)) : elements;
+      const hit = scope.find((e) => textOf(e).includes(needle));
+      pass = Boolean(hit);
+      message = pass
+        ? `Found text containing '${needle}'.`
+        : `No element text contains '${needle}'.`;
+      break;
+    }
+    case 'text_not_empty': {
+      const found = findFirst(elements, target);
+      pass = Boolean(found) && textOf(found).length > 0;
+      message = pass
+        ? `Element '${target}' has non-empty text.`
+        : `Element '${target}' has empty or missing text.`;
+      break;
+    }
+    case 'element_hint': {
+      const found = findFirst(elements, target);
+      // The agnostic model has no dedicated hint field; treat text/label as the
+      // best available surface for a hint/placeholder match.
+      const surface = found ? `${textOf(found)} ${labelOf(found)}` : '';
+      const expected = String(assertion.expected == null ? '' : assertion.expected);
+      pass = Boolean(found) && surface.includes(expected);
+      message = pass
+        ? `Element '${target}' hint matches '${expected}'.`
+        : `Element '${target}' hint does not match '${expected}'.`;
+      break;
+    }
+    case 'pattern_match': {
+      let re;
+      try {
+        re = new RegExp(assertion.pattern);
+      } catch (err) {
+        return result(type, true, false, `Invalid regex pattern: ${err.message}`);
+      }
+      const scope = assertion.target ? elements.filter((e) => matches(e, assertion.target)) : elements;
+      pass = scope.some((e) => re.test(textOf(e)));
+      message = pass
+        ? `At least one element text matches /${assertion.pattern}/.`
+        : `No element text matches /${assertion.pattern}/.`;
+      break;
+    }
+    case 'element_count':
+    case 'list_item_count': {
+      const actual = countMatching(elements, target);
+      const expected = Number(assertion.count);
+      const operator = assertion.operator || '==';
+      pass = compare(actual, operator, expected);
+      message = pass
+        ? `Count ${actual} ${operator} ${expected} for '${target}'.`
+        : `Count ${actual} does not satisfy ${operator} ${expected} for '${target}'.`;
+      break;
+    }
+    case 'list_is_empty': {
+      const actual = countMatching(elements, target);
+      pass = actual === 0;
+      message = pass
+        ? `No items matching '${target}' (list empty).`
+        : `${actual} item(s) matching '${target}' present (list not empty).`;
+      break;
+    }
+    case 'content_description': {
+      const found = findFirst(elements, target);
+      const label = found ? labelOf(found) : '';
+      const expected = String(assertion.expected == null ? '' : assertion.expected);
+      pass = Boolean(found) && (expected === '' ? label.length > 0 : label === expected);
+      message = pass
+        ? `Element '${target}' content-description matches.`
+        : `Element '${target}' content-description '${label}' did not match '${expected}'.`;
+      break;
+    }
+    case 'has_accessibility_label': {
+      const found = findFirst(elements, target);
+      const label = found ? labelOf(found) : '';
+      pass = Boolean(found) && label.length > 0;
+      message = pass
+        ? `Element '${target}' has a non-empty accessibility label.`
+        : `Element '${target}' is missing an accessibility label.`;
+      break;
+    }
+    case 'value_matches_variable': {
+      const varName = assertion.variable_name;
+      const expected = variables[varName];
+      const found = findFirst(elements, target);
+      const actual = found ? textOf(found) : null;
+      pass = expected !== undefined && actual !== null && actual.includes(String(expected));
+      message = pass
+        ? `Element '${target}' contains variable '${varName}'=${expected}.`
+        : `Element '${target}' text '${actual}' does not match variable '${varName}'=${expected}.`;
+      break;
+    }
+    case 'text_changed': {
+      if (!previous) {
+        return result(type, true, false, `No previous snapshot to compare '${target}' against.`);
+      }
+      const curr = findFirst(elements, target);
+      const prev = findFirst(previous, target);
+      const currText = curr ? textOf(curr) : null;
+      const prevText = prev ? textOf(prev) : null;
+      pass = currText !== prevText;
+      message = pass
+        ? `Element '${target}' text changed from '${prevText}' to '${currText}'.`
+        : `Element '${target}' text unchanged ('${currText}').`;
+      break;
+    }
+    default:
+      // Should be unreachable given the MECHANICAL_TYPES guard above.
+      return needsAgent(type);
+  }
+
+  return result(type, true, pass, message);
+}
+
+module.exports = { MECHANICAL_TYPES, evaluate };