For developers · App internals
Test access: driving the app without a human
On this page
The normal app is a tray panel: no window until a tray click, dismissed on blur, hidden from the
accessibility tree. The test access build removes those obstacles so a worker can operate it
with the lan-computer-use CLI (cu, see below). It is a separate Cargo feature (test-access); release and store builds
contain none of it.
What the test build changes:
- Window mode: a regular, decorated window, visible at start, never dismissed on blur. The app
is a Dock app, so
cu windowslists it asGitoodo Test. It opens in the detached window's frame (remembered, else 900 x 700 centred, clamped to the screen; #363), not in the popover size (docs/window-frame.md, "Test build"). - Own identity: bundle ID
de.gitoodo.app.testaccess, own config and log directory. It runs next to the installed app and never touches it (single instance, keychain, settings). - Test account: a fixture forge (
fixture/demo, usertester) and an in-memory token store. No real token, no network, no keychain. The account keeps the fixed idacc-fixtureacross restarts, so per-account state such as folded groups persists; other accounts are removed. - Test IDs in the accessibility tree: each
data-testidis mirrored into the DOM id (shown as#idin thecusnapshot) and intoaria-roledescription(shown in place of the role). An element that already has its own id (label association) keeps it. - Notifications: the permission reads as granted; posts are logged as
test_notification. - Usage statistics: hard stop. The test build, like any run with
GITOODO_UI_AUTOMATION=1, records, writes and sends nothing, whatever the onboarding switch says (docs/privacy.md).
Build and start#
VITE_TEST_ACCESS=1 npx tauri build --debug --bundles app \
--features test-access --config src-tauri/tauri.test-access.conf.json
open -n "target/debug/bundle/macos/Gitoodo Test.app"The panel is open right away. Nothing needs a tray click.
Address elements by test ID#
Scripts and workers use the lan-computer-use CLI. Point GITOODO_CU at it (default: cu on
PATH); the scripts in this repo never hardcode its location. LCU_TARGET selects a remote target
(for example a Windows PC) instead of this Mac.
"${GITOODO_CU:-cu}" find -a "Gitoodo Test" --id shell-settings # exact test ID
"${GITOODO_CU:-cu}" click e<n> # ref from the line aboveEvery line reads [e<n>] <role> "<name>" #<testid>, for example
[e6] button "Einstellungen" #shell-settings. Refs change with every snapshot or find; the test ID
does not. snapshot -a "Gitoodo Test" prints the whole tree. Look again after each action.
Fixture content: three questions in fixture/demo. #1 has a question block with a deadline
(tomorrow), #2 is free text, #3 has a deadline two days in the past (the overdue label of the
list, #73). GITOODO_TEST_EXTRA_QUESTIONS=<n> at start adds n free-form questions
(#4 on, at most 200) to check many open questions (#237). Rows are questions-row-…, copy and share buttons are
questions-copy-… and questions-share-…, the detail screen uses detail-….
For long-string layout checks (#337), set GITOODO_TEST_LONG_TEXT=1. Every fixture title
(default and scale mode) gains a long sentence and one long word without break opportunities, so
wrapping, clipping and ellipses show at the minimum window size. Bodies, numbers and labels stay
unchanged.
For large-list navigation (#337), set both GITOODO_TEST_REPOS=300 and
GITOODO_TEST_ISSUES_PER_REPO=5 in the test app's launch environment. This replaces
the default fixture with 300 repositories (fixture/scale-001 through fixture/scale-300)
and 1,500 distinct issues. Each issue is assigned to tester, has needs-human and a
cycling ready, in-progress, in-review or blocked status label. Question bodies
reuse the three default question types. Each repo also has two fixture pulls, with the
green pull linked to that repo's first issue. Dashboard groups and counts come through
the normal Rust adapter and sync path.
Both values must be positive integers; missing, invalid or zero input keeps the default
fixture and its existing extra-question behavior. Valid scale inputs are capped at 300
repos and 20 issues per repo (6,000 issues total); GITOODO_TEST_EXTRA_QUESTIONS is
ignored in scale mode. The scale dataset is seeded once at startup. Repo names, forge
IDs and issue URLs are unique; issue numbers are globally unique within this fixture.
Comments and closures are scoped to their repository and remain in memory until exit.
Other unsupported adapter mutations stay unsupported. This creates test data, not a
performance result; navigation and responsiveness still need an explicit runtime check.
Showcase data for screenshots#
GITOODO_TEST_FIXTURE_LANG=de or =en replaces the fixture with an invented open-source team in
that language (src-tauri/src/test_showcase.rs): two repositories (kiezwerk/pegelstand and
kiezwerk/radkeller, in English harborlight/tidewatch and harborlight/trailkit), four
questions to the user (one with a deadline tomorrow, one free text, one overdue, one approval),
the board with three running workers, pull requests (one with a failing ci/test), a week of
closed issues and merged pulls for the weekly review, eight weeks of throughput, the readiness
checklist of a well kept repo and a scripted orchestrator chat that proposes one comment. Workers,
usage, setup checks and the chat are answered by the fixture, never by a running classifier,
dispatcher or agent, and steering a worker only acknowledges. Any other value keeps the plain
fixture above.
GITOODO_TEST_WEEKLY_REVIEW=1 (with the showcase) makes the weekly review due at start. The status
bar shows the version only in every build; commit and build time are on the About page.
The landing page's shots in site/shots/ come from the browser demo (scripts/site-shots.mjs).
The test build still reads services and files outside its config dir (the classifier socket, the
dispatcher, state_dir). For recordings, point GITOODO_STATE_DIR, GITOODO_CONFIG_DIR and
GITOODO_BIN_DIR at an empty temporary folder so nothing of an installed Gitoodo shows up or is
touched.
Optional native navigation measurements (#337)#
Add VITE_TEST_PERFORMANCE=1 alongside VITE_TEST_ACCESS=1 to the build command.
Both build flags are required; the dynamically imported probe is excluded from normal
builds. Runtime automation alone does not enable it. Launch the scale fixture as above.
Before the actual run, calibrate accessibility visibility in the real test app: use
cu snapshot -a "Gitoodo Test" --all and reconstruct the readonly report fields
as described below, then perform one native input and read them after a quiet pause. If the platform omits this offscreen field or its value, the measurement is not
validated. Restart the test process after calibration; only a fresh process resets it.
The probe counts trusted keydown, pointerdown, wheel and actual scroll events.
Scroll includes browser-generated scroll events, including programmatic scrolling;
trust alone does not prove a human caused a scroll. Non-trusted events and non-finite,
zero, negative or future timestamps are rejected. Timestamps must share the
performance.now() time origin. It records event timestamp to next animation callback
scheduling latency, and gaps between animation callbacks during an input/scroll
burst and its 250 ms quiet tail. These are neither pixel-paint/full-response latency
nor displayed FPS. A delayed callback can extend that tail; no idle loop runs afterward.
Use a foreground, visible window and record the native actions, dataset and environment
with the result. No pass/fail threshold is inferred from these numbers.
Read the fields only after the burst is quiet: reporting updates values and creates any
additional fragment fields after sampling stops, without live announcements, focus
changes or page layout changes. The JSON contains accepted counts by event type, rejected counts, pending queue
overflow, burst count, elapsed process window and accumulated active window in milliseconds.
eventToNextRafSchedulingMs and frameGapMs each include observed/retained/dropped
counts and nearest-rank p50/p95/max of the first 4,096 retained samples (zero when empty).
Pending event timestamps also cap at 4,096; overflow events are counted but not measured.
Results are cumulative until process exit. No targets, key values, content, account data,
network requests or logs are collected. The probe adds measurement overhead; corroborate
the numbers with native navigation observations, rather than treating them as paint proof.
The accessibility helper caps individual values at 120 characters. Read the header
test-performance and test-performance-part-0 through parts - 1 using a full
--all snapshot. Each part is sequence:index:fragment with at most 96 characters
of JSON. Require every sequence to match the header, join fragments by index and
check the header character count before parsing. Discard mixed or incomplete reads;
do not focus the fields to read them. The report is published only after a quiet burst.
The installed store preview (#235)#
The signed, sandboxed store preview has no test build features, but it has one runtime switch: start
it with GITOODO_UI_AUTOMATION=1 in its environment. Without the variable nothing differs from a
normal start (no visible change, no permission prompt).
osascript -e 'quit app "Gitoodo"' # single instance: a running app ignores the variable
open -n --env GITOODO_UI_AUTOMATION=1 /Applications/Gitoodo.app
"${GITOODO_CU:-cu}" find -a Gitoodo --id shell-rootWith the switch on, the app is a regular (Dock) app so the accessibility API lists it, the real
borderless popover opens at start (no tray click) and stays open on blur or the shortcut, and
every data-testid is mirrored into the accessibility tree as in the test build. Accounts, keychain,
settings and the skill folder are the real ones (no fixture): use it for what the fixture cannot
show (#222). Snapshot, find and click work as above; python3 -I scripts/check-test-ids.py Gitoodo
lists elements without a test ID.
The ids the #222 checks need are fixed by tests/popover-test-ids.test.ts (it fails if one
disappears): shell-root, shell-tab-questions, shell-tab-dashboard, shell-settings,
shell-sync, questions-row-…, questions-share-…, questions-copy-… (#71),
…-repos-<repo> repo switches and …-toggle filter (#135, multi-select), dashboard-quiet-toggle,
dashboard-row-… (#85), settings-shortcut-recorder (#83), settings-skill-install,
settings-skill-confirm-yes, settings-skill-copy-command (#160).
The dashboard opens grouped by status (#193): dashboard-groupby-{status,repo,account,counts}
switch the grouping, dashboard-groups is the grouped list, headers are
dashboard-group-<kind>-<key> (repo keys read <account>-<owner>/<repo>) and items
dashboard-item-<account>-<owner>/<repo>-<number>. The table with dashboard-row-… and
dashboard-quiet-toggle is the "Numbers" view: click dashboard-groupby-counts first. The
choice is remembered, so a later run may start in any grouping.
"Braucht dich" (#194): dashboard-signals is the counter area at the top with one
dashboard-signal-{question,blocked,ci,stale} toggle per signal (pressed = list filtered to it),
dashboard-signal-clear removes the filter and dashboard-signals-quiet replaces the toggles when
nothing needs the user. dashboard-groupby-signal groups by signal (dashboard-group-signal-<kind>,
dashboard-no-signals when empty). Row markers read dashboard-item-signal-<kind>-<item>.
Check that every element has a test ID#
python3 -I scripts/check-test-ids.py # optional first argument: app nameIt reads the live tree through cu (GITOODO_CU) for the screen that is open and lists every
button, link, tab, field, toggle and heading that has no test ID as its #id. Exit code 1 if any is missing
(2 if the tree cannot be read). Run it once per screen: main, settings, detail, onboarding.
Flows#
- Mark as read: click a
questions-row-…element. The question lands inseen.jsonof the test config dir (~/Library/Application Support/de.gitoodo.app.testaccess/). - Share: click
questions-share-…(the system share sheet) orquestions-copy-…. - Deadline reminder: the first sync arms it (
reminders.json,"fired": false). WithGITOODO_TEST_CLOCK_HOURS=40set at start, the clock runs 40 h ahead from the second check on, so clickingshell-syncmakes it fall due. The log then has atest_notificationevent (~/Library/Logs/de.gitoodo.app.testaccess/gitoodo.log). - Notification permission: always
Grantedin this build; no system dialog appears. - Skill install (#160): the "home folder" of this build is
fixture-home/in the test config dir, recreated empty at every start, so the skill is not installed and.claude/skillsis a fixture folder. Install, remove, the folder panel (it starts in the fixture folder) and the copyable Terminal command work against it; the real~/.claudeis untouched. The folder bookmark exists only in the store build: build with--features test-access,storeto drive it (not verified in the sandbox). - Shortcut recording (#83): synthetic key events do not reliably reach the recorder, so
the test build adds two buttons below it,
settings-shortcut-test-press-alt-meta-jandsettings-shortcut-test-press-escape. Clicksettings-shortcut-recorder(recording starts, the global shortcut is released), then click a test key button: it goes through the same handler as a real key press (save, or cancel and resume the shortcut). They are enabled only while recording. - Mark as read on the forge (#159): obsolete. The Eingang and forge notifications were removed
(#189), so there is nothing left to mark and no
write:notificationscope to check. - Detached window (#197): click
shell-detach. The window gets its title bar and the button turns intoshell-attach; clicking it (or closing the window) returns to the popover. The frame is stored indetached-window.jsonof the test config dir. The test build is always decorated and never hides, so the visible change is the button and, after attaching, a hidden window that the tray icon reopens. - Reply:
detail-sendposts a comment to the fixture forge; it shows up in the thread until the app exits. - Open the next question (#245): tick
detail-next-toggle(kept across cards and restarts), thendetail-send: the card of the next open question of the list opens; after the last one the list returns with the "all answered" toast.
Known gap: the global shortcut#
Recording a new shortcut is covered by the test key buttons (see Flows). Triggering the registered shortcut system-wide (outside the app) cannot be done reliably with UI automation and is not covered. In the test build the panel never hides, so the shortcut has nothing to toggle anyway.
Restore the desktop after a test#
Record the installed app’s running and visible state before using the separate test app. Afterward, quit the test app and restore its isolated Application Support and WebKit stores. Do not open or activate an already-running normal Gitoodo app: macOS sends a reopen event and Gitoodo intentionally shows its main window. Preserve the user's previous visibility instead. Only restart a production instance when the test actually started that instance with automation enabled, and restore its previous visibility.
Agent skill lifecycle verification (#545)#
The macOS test app at code revision 70cd885 was exercised with isolated skill
folders on 2026-11-14. Explicit Codex/shared radio selections produced matching
confirmation destinations; selection survived transitions between split and compact
settings layouts. Installation, a simulated older managed package update, removal,
local-change protection and recovery after a folder write error passed. Updated skill
content and the package manifest matched the current bundled bytes. Use fresh
accessibility refs after target changes, because the package rows rerender.
Test Application Support and WebKit data were restored byte-for-byte. The normal production instance remained running and hidden. Store permission/bookmark runtime, Windows runtime and VoiceOver were not verified by this test; store compilation alone does not establish those results.