Docs · Beta

Product documentation

What Lighthouse is, how to install and activate a beta key, how to inspect · record · script · play on Windows and Android, and how to run suites from the headless CLI. For a short walkthrough see the user guide; for edge cases see FAQ and limits.

Overview

Lighthouse Tests Suite is a Windows desktop app for UI test automation. Attach to a running Windows process (UIA) or an Android device/emulator (Appium), inspect a live visual map, record steps, and play them back.

Credo: write once, test everywhere — give controls a shared AutomationId (Flutter, .NET MAUI, and similar stacks) so the same suite can run on Windows and Android. iOS is not available yet.

  • Inspect — tree + screenshot map with overlays and properties
  • Record — clicks, text, asserts, waits (platform-specific extras on Android)
  • Script — text editor (tapOn, startApp, …) synced with the step list
  • Play — run a test or the whole suite; review results on the Dashboard

Install

  1. Download the Windows Setup from the home page when the Download button is enabled.
  2. If SmartScreen appears: More info → Run anyway (unsigned beta).
  3. Framework-dependent builds need the .NET 10 Desktop Runtime unless you have a self-contained (R2) build — the download hint on the home page says which you have.
  4. Open Lighthouse Tests Suite from the Start menu.

Requirements: Windows 10/11 x64. No Visual Studio required for Setup users.

Beta license

Installed Setup builds auto-activate a free 30-day device trial on first launch. No key paste is required for that first period. Remaining time appears in Settings → Beta license (“Free beta — N days left”).

  1. Install and open Lighthouse — Workspace unlocks for the free trial.
  2. When the free period ends, an activation panel asks for a renewal key (or open Settings → Beta license anytime).
  3. Request a key via Contact, paste it (starts with LH1.), and choose Activate.
  • Reinstalling or clearing only one local store does not mint a new free trial on the same PC.
  • Issued renewal keys are bound to this PC/user and expire after the issued window (usually 30 days).
  • Entitlement is stored under LocalAppData, ProgramData, and HKCU (DPAPI-protected).
  • Developer / unpackaged runs bypass the gate with LIGHTHOUSE_LICENSING=0 — not for public Setup.

Workspace layout

The main window has three columns:

  • Tests — project name (caption), suite list, search, new/rename/delete
  • Test — steps, script panel, Run / Export, run console
  • Inspector — visual map, recording toolbar, element properties

Use the header to switch Platform (Windows UIA / Android), pick an application or device, and open Dashboard or Settings. Rename the project via the Tests column ⋯ → Rename project… — that name is what lighthouse run --project uses (see CLI).

Lighthouse Script

Open the script pane with Ctrl+E. The header shows {Test name} script, plus Run, ? Help (full command reference), and Hide. The same command list is under Settings → Script commands…. Steps are plain text — prefer #AutomationId targets. The step list above the editor stays in sync with the cursor line; a status strip under the editor shows hints or parse errors. 

startApp "MyApp"
tapOn #login_button
inputText "user@example.com" into #email
assertVisible #welcome
assertText #status "*saved*"
waitFor #submit visible 5s
wait 1
takeScreenshot "after-login"
assertScreenshot "after-login" moderate
  • startApp launches if needed; restartApp always kill+relaunch (same as editing the first step).
  • Gestures: tapOn, longPressOn, doubleTapOn, rightClick (Windows only), scrollUntilVisible.
  • Asserts: assertVisible, assertNotVisible, assertText #id "*pattern*" (wildcards */?), checkColor #id #RRGGBB (Windows only).
  • waitFor conditions: visible, clickable, enabled, gone (optional timeout, e.g. 5s). Default find/wait timeout is under Settings.
  • wait 2 (bare number = seconds) pauses like delay; also wait 500ms / wait 2s.
  • Variables: inputText "${USER}" into #email — define under Tests ⋯ → Variables… (or YAML env:). Expanded at Run. CLI: --var USER=demo / LIGHTHOUSE_VAR_USER.
  • Screenshots: see Screenshots.
  • Insert tapOn — Inspector ⋯ → Insert tapOn into script, or the script header tapOn button when a map element is selected (prefers #AutomationId).
  • On failure: script opens, console docks under it (Copy + drag to resize), and the cursor jumps to the failed line (also Show in script on the failure chip). Messages distinguish Did not find #id within 10s from wrong content (assertText failed for #id: expected '…' but found '…').
  • Completions: Ctrl+Space synonyms (click/press/tap → tapOn; write/fill → inputText; scrollTo → scrollUntilVisible); element suggestions inside tapOn "".
  • Ctrl+Z / Ctrl+Y — undo / redo (~30 coalesced steps in the editor).
  • Legacy keywords (CLICK, TYPE … INTO, …) still parse.
  • F5 / Ctrl+Enter — flush the buffer and run the current test (also the script header Run button).
  • Ctrl+Shift+Enter — run only the selected / cursor step.
  • While the script pane is open, the run console docks under the editor. Closing the pane restores the step list height.

Screenshots

Capture and compare app screenshots from the Inspector toolbar (camera / assert icons) or from script. Works on Windows and Android. 

takeScreenshot "home"
takeScreenshot #Panel "panel-region"
assertScreenshot "home" high
assertScreenshot #Panel "panel-region" moderate
  • Sensitivity: high / moderate / low (about 1% / 20% / 50% pixel tolerance).
  • Optional #AutomationId crops to that element’s region.
  • Compare tolerates size/DPI differences by aspect-safe resize before differencing.
  • On assert failure, the run bundle includes baseline.png, actual.png, and diff.png.
  • For CI: Settings → Export suite JSON + screenshots… writes suite.json plus a sibling screenshots/ folder for lighthouse run --script.

Settings

Open Settings from the header. Useful groups:

  • Appearance — theme, UI style, language (English, Hebrew, Russian, German, Spanish, French).
  • Inspector — properties layout (beside / under / hidden), Live Watch, AutomationId-only filter.
  • Playback — restart app before each test; default find/wait timeout (1–60 seconds).
  • Script editor — open script pane when a suite loads; Monaco font size.
  • Export & screenshots — preferred export format (C# / NUnit), Export suite…, Export suite JSON + screenshots…, open baselines folder.
  • Help — Script commands… (includes ${vars} and failure wording), Keyboard shortcuts…, Show tutorial; About links (guide, changelog, contact).
  • Beta license — remaining free days; paste an LH1. renewal key.
  • Updates / diagnostics — Check for updates…, open logs, copy diagnostics.

Suite variables are edited from the Workspace Tests column ⋯ → Variables… (not inside Settings). CLI overrides: --var KEY=value / LIGHTHOUSE_VAR_KEY.

Windows workflow

  1. Platform → Windows UIA.
  2. Choose the target process from Application (refresh if it just started).
  3. Create or select a test → Start Recording in the Inspector (F9) → left-click the Inspector map (the app follows). Stay on the map — no need to switch to the target window.
  4. Right-click the map (or use Actions) for Enter Text, asserts, and waits. Or open the script pane (Ctrl+E) and type script steps.
  5. Optional: enable Research click (right of Properties) to select on the map without driving the app.
  6. Run Test to replay. Prefer elements with a stable AutomationId or name.

Elevation: if attach fails against an Administrator app, run Lighthouse elevated or run the target without elevation. See limits.

Android workflow

Not bundled: the Lighthouse Setup does not include Appium, Node, or the Android SDK. Install host tools yourself (same model as adb on PATH). Windows UIA works out of the box.

  1. Install adb (Android SDK platform-tools) on PATH. Optional: winget install Google.PlatformTools.
  2. Install Appium 2 separately (npm i -g appium) and the uiautomator2 driver (appium driver install uiautomator2). Connect auto-starts appium from PATH when needed (or set LIGHTHOUSE_APPIUM_URL).
  3. Platform → Android → pick device → optional package → Connect. If tools are missing, use Setup Android… (checklist, copy install commands, open docs).
  4. Start Recording in the Inspector (F9), then left-click the Inspector map (device follows). Live taps via adb and EnterText from focused fields may also record when available.
  5. Use toolbar actions for Back / Swipe when needed.
  6. Run Test uses Android playback (click / long press / double tap, text, assert + assertText, wait, delay, back, swipe, scrollUntilVisible, screenshots). Windows-only: rightClick, checkColor.

Refresh Inspector after navigation if the map looks stale; live hierarchy watch also refreshes when connected.

Manual smoke checklist

  1. Emulator or device online (adb devices).
  2. Platform → Android → Connect (tree + screenshot in Inspector).
  3. Create a test → Start Recording → left-click a control on the map → Stop Recording.
  4. Run Test — step passes on the device.
  5. Optional: Check portability… / Verify AutomationIds when sharing steps with Windows.

Headless CLI

Run the same suites outside the desktop UI — for local automation or CI. The CLI uses the same playback engine as Run / Dashboard. Build lighthouse.exe from the product source with ./scripts/publish-cli.ps1 (output: artifacts/cli/lighthouse.exe).

Local projects

Suites you recorded in the app live under %LocalAppData%\Lighthouse.Tests.Suite\apps\. List them, then run by the project display name (Tests column caption): 

lighthouse projects
lighthouse run --project Calculator
lighthouse run --project Calculator --test "Login" --report junit

If a Store / UWP host was named after the process (e.g. ApplicationFrameHost), use Rename project… in the app first so --project matches a short name.

Console & reports

  • Stdout shows per-test progress only ([RUN] / [PASS] / [FAIL], colored).
  • Step-level detail is in the JSON report (tests[].steps[]), not the console.
  • Every run ends with SUMMARY (passed / failed / total / duration / result) and REPORT (path).
  • Default report: ./lighthouse-results.json. Override with --output.
  • --report junit also writes JUnit XML (JSON is still written).
  • Disable colors with NO_COLOR=1 (or when output is redirected).
  • Exit codes: 0 all passed · 1 one or more failed · 2 bad args / infrastructure error.

CI / portable scripts

Check in an exported suite JSON (and sibling screenshots/ if you use screenshot asserts). From the app: Settings → Export suite JSON + screenshots…. 

lighthouse run --app "C:\Build\MyApp.exe" --script "tests\checkout.json" --report junit
lighthouse run --platform android --device emulator-5554 --package com.example.app --script tests\android.json

Helpers: lighthouse android-devices, lighthouse android-inspect. Optional: --restart-app (same idea as Settings → Restart app before each test); --var KEY=value (repeatable) for suite ${vars}. Optional env: LIGHTHOUSE_PROJECT, LIGHTHOUSE_PLATFORM, LIGHTHOUSE_ANDROID_DEVICE, LIGHTHOUSE_ANDROID_PACKAGE, LIGHTHOUSE_APPIUM_URL, LIGHTHOUSE_VAR_<KEY>, NO_COLOR.

Import YAML flows

Import tests… accepts .yaml / .yml flows as a one-way conversion into Lighthouse steps (mapped command subset). Unsupported commands are skipped with warnings in the import dialog.

  • env: → suite Variables… (${NAME} expanded at Run).
  • runFlow — nested file (path relative to the imported YAML) or inline commands: are inlined into the imported test. Cycles and missing files are skipped with a warning.
  • runFlow.env merges into suite Variables (same as flow-header env:).
  • Still skipped: JS (runScript / evalScript), when: conditions, AI asserts, clipboard, device toggles.

AutomationId & portability

Steps with an AutomationId can resolve on Android by id only (no Windows class/bounds fallthrough). That is the contract for portable Flutter / MAUI suites.

  • Set the same id in shared UI code on each platform.
  • Use Import / Check portability in the app when moving a suite between Windows and Android.
  • Windows-only today: rightClick, checkColor, DragDrop. Android-only extras: Back / Swipe.
  • Screenshot baselines can travel with the suite via {suiteDir}/screenshots/ when you export JSON + screenshots for CLI.

Updates

Installed Setup builds can check for updates from Settings → Check for updates… when a public feed is configured. Force / minimum-version policies may block Workspace until you update.

Unpackaged dotnet run builds do not self-update.

Data & logs

  • Projects / tests: %LocalAppData%\Lighthouse.Tests.Suite\apps\ (also what lighthouse projects lists)
  • Screenshot baselines (local): under the app data tree; portable export uses a sibling screenshots/ next to the suite JSON
  • User preferences (timeouts, script font, …): LocalAppData preferences store
  • Beta license activation: under the same LocalAppData folder (sealed)
  • Logs: %LocalAppData%\Lighthouse.Tests.Suite\logs\

Nothing in those folders is uploaded unless you choose to send feedback. See Privacy.

Beta Download Quick start guide