Skip to content

Spectre

Spectre

Spectre lets Kotlin tests control a running Compose Desktop application. It reads the Compose semantics tree and sends mouse and keyboard events. The default driver sends synthetic AWT events into the window hierarchy. Tests can select real operating system input when they need it. Spectre also records the screen in standalone apps and IntelliJ or Jewel hosts.

A test finds a node, performs an action, and checks the result.

Pre-1.0

Spectre is pre-1.0. The stability policy covers stable APIs. Experimental HTTP, agent attach, and desktop input coordination APIs may change between releases. Read the security notes before enabling cross-JVM control or recording where the application handles untrusted input.

Why Spectre

  • Inspect running windows. Spectre reads live semantics, layout, focus, popups, and HiDPI coordinates.
  • Choose a process boundary. ComposeAutomator.inProcess() runs with the application. The server module controls a UI in another JVM, such as an IDE under test.
  • Use synthetic input by default. ComposeAutomator.inProcess() uses RobotDriver.synthetic() to send AWT events into the window hierarchy. Pass RobotDriver() when a test needs real cursor motion, global focus, or system shortcuts.
  • Coordinate shared input. Participating real-input test JVMs can serialise focus, pointer, keyboard, and clipboard operations. Query and synthetic tests can still run in parallel. See desktop input coordination.
  • Capture video and still images. Spectre supports region capture and platform-specific window capture. macOS uses ScreenCaptureKit; Windows uses Windows Graphics Capture. Linux uses helpers for Xorg/Xvfb and portal/PipeWire capture. AutoRecorder and AutoScreenshotter select a backend for each call.
  • Run JUnit tests. The JUnit 5 extension and JUnit 4 rule create an automator for each test. They can save a failure screenshot and semantics tree or launch and attach to an application.
  • Inspect an app interactively. The spectre CLI and MCP tools work without a JUnit test. Agent attach also works from another JVM. It prefers preinstalled spectre-core and can inject core when the target does not include it.

Where to start

  • Getting started — Install Spectre and write a first test.
  • The automator — Concepts: semantics surfaces, queries vs. interactions, why there is no auto-wait.
  • Finding nodes — findByTestTag, findByText, hasTag/hasText, 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.
  • Experimental input coordination — FIFO leases, JUnit isolation, diagnostics, and explicit forced recovery.
  • Recording and screenshots — Region, window-targeted video, and native still-window screenshots across macOS, Windows, and Linux.
  • Atomic capture — Window PNG + versioned capture.json for agents, CLI, and JUnit failure artefacts.
  • CLI — Attach, inspect, click, capture, and record from the spectre command (and MCP).
  • Agent attach — Drive a running Compose JVM from another process (experimental; inject when core is not preinstalled).
  • Compose Hot Reload — Optional waitForReloadSettled when the target runs under Hot Reload (CLI/MCP).
  • Cross-JVM — Drive a UI hosted in another JVM process via the embedded HTTP transport (experimental; see Security notes).