Skip to content

Spectre

Spectre

Spectre is a Kotlin library for driving live Compose Desktop UIs from automated tests. It reads the Compose semantics tree, drives mouse and keyboard input either through real OS-level events or through synthetic AWT events dispatched straight into the window hierarchy, and records what happens on screen — against IDE-hosted Compose surfaces (IntelliJ, Jewel) and standalone desktop apps alike.

If you've used UI Automator on Android or Espresso for that matter, the shape will feel familiar — Spectre brings the same "find a node, do a thing, assert" loop to Compose Desktop.

Pre-1.0

Spectre is pre-1.0. Stable APIs are covered by the project's compatibility policy; experimental APIs, especially the HTTP transport, may change between releases. See Stability policy and Security notes before depending on cross-JVM control or recording in environments that handle untrusted input.

Why Spectre

  • Real Compose Desktop, not a simulator. Spectre runs against your actual application windows. Semantics, layout, focus, popups, and HiDPI all come from the running UI rather than a parallel test harness.
  • In-process or cross-JVM. Use ComposeAutomator.inProcess() for the simple case, or use the server module to drive a UI hosted in a different JVM (e.g., an IDE under test).
  • Real or synthetic input. ComposeAutomator.inProcess() defaults to OS-level java.awt.Robot events. Swap in RobotDriver.synthetic(...) and AWT events go directly into the window hierarchy — useful when tests run in parallel and can't fight over OS focus.
  • Recording and screenshots built in. Region capture, plus window-targeted recording and still screenshots where the platform exposes them (ScreenCaptureKit on macOS, Windows Graphics Capture on Windows, helper-driven Xorg/Xvfb and portal/PipeWire capture on Linux). The AutoRecorder and AutoScreenshotter pick the right backend.
  • JUnit-friendly. Drop-in extension and rule for JUnit 5 and JUnit 4 manage a per-test automator instance for you.

Where to start

  • Getting started — Install Spectre and write your first test.
  • The automator — Concepts: semantics surfaces, queries vs. interactions, why there is no auto-wait.
  • Finding nodes — findByTestTag, findByText, findByContentDescription, findByRole, and the printTree() debugger.
  • Synchronization — waitForIdle, waitForVisualIdle, waitForNode, and the EDT rule.
  • Running on CI — xvfb, required test-JVM flags, macOS helper mode, and recording test tags.
  • Recording and screenshots — Region, window-targeted video, and native still-window screenshots across macOS, Windows, and Linux.
  • Cross-JVM — Drive a UI hosted in another JVM process via the embedded HTTP transport (experimental; see Security notes).