{"id":50105272,"url":"https://github.com/rock3r/spectre","last_synced_at":"2026-05-23T10:05:40.054Z","repository":{"id":355296812,"uuid":"1205215229","full_name":"rock3r/spectre","owner":"rock3r","description":"Programmatically drive your real Compose UI on the desktop.","archived":false,"fork":false,"pushed_at":"2026-05-18T18:32:44.000Z","size":2567,"stargazers_count":9,"open_issues_count":7,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T18:34:59.436Z","etag":null,"topics":["compose","compose-desktop","compose-multiplatform","kotlin","ui-automation","vibe-coded"],"latest_commit_sha":null,"homepage":"https://spectre.sebastiano.dev","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rock3r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-08T18:44:32.000Z","updated_at":"2026-05-18T16:37:52.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rock3r/spectre","commit_stats":null,"previous_names":["rock3r/spectre"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/rock3r/spectre","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rock3r%2Fspectre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rock3r%2Fspectre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rock3r%2Fspectre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rock3r%2Fspectre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rock3r","download_url":"https://codeload.github.com/rock3r/spectre/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rock3r%2Fspectre/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33390977,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compose","compose-desktop","compose-multiplatform","kotlin","ui-automation","vibe-coded"],"created_at":"2026-05-23T10:05:39.193Z","updated_at":"2026-05-23T10:05:40.046Z","avatar_url":"https://github.com/rock3r.png","language":"Kotlin","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/spectre-logo.png\" alt=\"Spectre\" width=\"200\" /\u003e\n  \u003cbr /\u003e\n  Spectre\n\u003c/h1\u003e\n\nA Kotlin library for driving Compose Desktop UIs from automated tests. Reads the semantics\ntree, drives mouse and keyboard input — either real OS-level events via `java.awt.Robot` or\nsynthetic AWT events dispatched straight into the window hierarchy (`RobotDriver.synthetic(...)`,\nuseful when tests run in parallel and can't fight over OS focus) — and records the screen,\nagainst IDE-hosted Compose surfaces (IntelliJ, Jewel) and standalone desktop apps alike.\n\n\u003e [!IMPORTANT]\n\u003e Spectre is pre-1.0. Stable APIs are covered by the compatibility policy in\n\u003e [`docs/STABILITY.md`](docs/STABILITY.md); experimental APIs, especially the HTTP transport,\n\u003e may change between releases. Read [`docs/SECURITY.md`](docs/SECURITY.md) before enabling\n\u003e cross-JVM control or recording in environments that handle untrusted input.\n\nmacOS, Windows, Linux Xorg, and Linux Wayland. The Wayland path goes through a small\nout-of-process Rust helper (`recording/native/linux/`) that owns the xdg-desktop-portal\nhandshake, the PipeWire FD lifetime, and the `gst-launch-1.0` subprocess; the JVM-side\nrecorder talks to it over stdin/stdout via a tiny JSON protocol. Same out-of-process\narchitecture as the macOS Swift helper.\n\n\u003e [!NOTE]\n\u003e **Linux support is best-effort.** Routine validation runs on one machine: Ubuntu 22.04,\n\u003e exercising the Xorg session (input + popup + HiDPI + `x11grab`) and the GNOME / mutter\n\u003e Wayland session (the portal-based recording path). Other distros, compositors (KDE /\n\u003e Plasma, sway, wlroots), window managers, and Ubuntu versions aren't covered. Reports\n\u003e and PRs widening the coverage are very welcome — open an issue with your distro /\n\u003e compositor / session combo and we'll work through it.\n\n## Documentation\n\nUser guide and API documentation: **\u003chttps://spectre.sebastiano.dev\u003e**.\n\nInstall released versions from Maven Central, or consume the current checkout as a\nGradle composite build while working ahead of a release:\n[Installation](https://spectre.sebastiano.dev/guide/installation/).\n\nStart at [Getting started](https://spectre.sebastiano.dev/guide/getting-started/) for the\nshape of a Spectre test, or [The automator](https://spectre.sebastiano.dev/guide/automator/)\nfor the mental model.\n\nAgent skill:\n\n```shell\nnpx skills add rock3r/spectre --skill spectre\n```\n\n## Modules\n\n- `core` — semantics tree, selectors, coordinate mapping, Robot-backed input.\n- `server` — embedded HTTP transport (Ktor) for cross-JVM access. **Experimental**; see\n  [`docs/SECURITY.md`](docs/SECURITY.md) for the trust model.\n- `recording` — region capture via `ffmpeg`, window-targeted video capture, and native still\n  window screenshots where available (ScreenCaptureKit on macOS, `gdigrab` on Windows, X11\n  region fallback on Linux). `AutoRecorder` / `AutoScreenshotter` pick per call. See\n  [`docs/RECORDING-LIMITATIONS.md`](docs/RECORDING-LIMITATIONS.md).\n- `testing` — JUnit 5 extension and JUnit 4 rule.\n- `sample-desktop` — Compose Desktop app for manual smokes.\n- `sample-intellij-plugin` — in-tree IntelliJ plugin hosting a Jewel tool window. Unpublished;\n  serves as the IDE-hosted test bed.\n\n## Run the samples\n\nStandalone Compose Desktop app:\n\n```shell\n./gradlew :sample-desktop:run\n```\n\nIntelliJ plugin — then `Tools → Run Spectre Against the Sample Tool Window`, or pass\n`-PspectreAutorun=true` to fire the action on project open:\n\n```shell\n./gradlew :sample-intellij-plugin:runIde\n```\n\n## Quality checks\n\n```shell\n./gradlew check        # tests + Detekt + Compose Rules + ktfmt\n./gradlew ktfmtFormat  # rewrite Kotlin / .gradle.kts in place\n```\n\nTwo heavier checks live outside `:check`:\n\n- `:sample-intellij-plugin:uiTest` — boots IntelliJ via `intellij-ide-starter`, installs the\n  plugin, fires `RunSpectreAction`, and asserts every tagged Compose node shows up in\n  `idea.log`.\n- `:recording:check` on macOS — covers the Swift ScreenCaptureKit helper.\n\n## Supported JVMs\n\nJBR 21 is the dev-loop default. JBR 25 also gets exercised via the IDE-hosted test (bundled\nwith IntelliJ 2026.1). Any JDK 21+ works for the non-IDE modules. CI runs on Temurin 21.\n\n## CI\n\n- [`ci.yml`](.github/workflows/ci.yml) — `:check` on Linux, every PR.\n- [`macos-check.yml`](.github/workflows/macos-check.yml) — `:check` on macOS, broad path filter.\n- [`windows.yml`](.github/workflows/windows.yml) — `:check` on Windows, broad path filter.\n- [`macos.yml`](.github/workflows/macos.yml) — Swift helper build + `:recording:check`, gated\n  on `recording/**`.\n- [`ide-uitest.yml`](.github/workflows/ide-uitest.yml) — IDE-hosted UI test on macOS + Windows,\n  gated on plugin / core / recording changes. `out/ide-tests/{installers,cache}` is cached\n  between runs.\n- [`validation-windows.yml`](.github/workflows/validation-windows.yml) —\n  `:sample-desktop:validationTest*` on Windows, gated on `sample-desktop/**`. JUnit-XML-driven\n  verifier so a Gradle/Compose protocol flake on shutdown can't hide a real failure.\n- [`validation-linux.yml`](.github/workflows/validation-linux.yml) — same validation matrix\n  on Linux under `xvfb-run` (real Xorg, no compositor in the loop), gated on the same\n  `sample-desktop/**` filter shape.\n\nFor consumer projects, see [Running on CI](docs/guide/ci.md) for the required test-JVM flags:\n`java.awt.headless=false` for AWT, `skiko.renderApi=SOFTWARE_COMPAT` on GPU-less Linux runners,\nand the macOS `apple.awt.UIElement=true` trade-offs for synthetic typing vs. clipboard paste.\n\n## Reference docs\n\nThe user guide and these reference pages are also published as a single browseable site\nat \u003chttps://spectre.sebastiano.dev\u003e.\n\n- [Architecture](docs/ARCHITECTURE.md)\n- [Testing](docs/TESTING.md)\n- [Conventions](docs/CONVENTIONS.md)\n- [Static analysis](docs/STATIC-ANALYSIS.md)\n- [Recording limitations](docs/RECORDING-LIMITATIONS.md)\n- [Spike gist](https://gist.github.com/rock3r/8e520bb3fe8fe5886367d5e22cefbab8) — original\n  design notes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frock3r%2Fspectre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frock3r%2Fspectre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frock3r%2Fspectre/lists"}