tranquil
Docs

Run the Test Suite

Once Local Dev Setup is working, you can run Tranquil’s automated GUI tests. They live in a separate repo — tranquil-test-suite — and are deterministic smoke tests with no LLM in the loop: each one launches a fully isolated Tranquil instance, drives it over the Chromium DevTools Protocol, asserts real UI behaviour, and tears the app down.

This page is the quick runbook. For what each test covers, how the harness works, and how to add one, see Smoke Tests.

The suite opens a real window, so it needs a display — fine locally on macOS. There is no headless CI setup yet, so the run model today is on-demand: run it whenever you touch UI or owned-package code.

Prerequisites

  • A working local dev checkout — you completed Local Dev Setup, so ../tranquil-client sits alongside the other repos with node_modules installed. The suite spawns that checkout’s Electron binary directly; no Node is invoked.

  • Deno — all tooling in tranquil-test-suite is Deno (never yarn/npm/node). Install it if you don’t have it:

    curl -fsSL https://deno.land/install.sh | sh

    It lands at ~/.deno/bin/deno; make sure that’s on your PATH. Confirm with deno --version.

Clone the suite

Clone tranquil-test-suite as a sibling of tranquil-client — the harness locates the app checkout at ../tranquil-client:

cd ~/Documents/Tranquil/Repos
git clone https://github.com/tranquillabs/tranquil-test-suite.git

Run

cd ~/Documents/Tranquil/Repos/tranquil-test-suite
deno task test

That launches one isolated Tranquil instance (a throwaway ATOM_HOME and --user-data-dir, with TRANQUIL_VERIFY=1 so only the test-suite repo opens as the project — never your tranquil-client source), runs every suite as a step, and tears it down. A green run reports each suite as ok and exits 0; any failed assertion fails its step and exits non-zero.

Set SMOKE_DEBUG=1 to see the launched app’s stdout/stderr while it runs:

SMOKE_DEBUG=1 deno task test

Keep it clean

Before pushing changes to the suite, keep Deno’s own checks green:

deno fmt
deno lint
deno check smoke/

Next steps

  • Smoke Tests — what each suite asserts, how the isolated-launch and CDP harness works, and how to add a new test.
  • Agent Debugging — the interactive, LLM-driven counterpart: inspect and script a live instance over CDP by hand.