Documentation Docs version: dev (Pre-release: Gitoodo has not been released yet)

For developers · App internals

Test access: driving the app without a human

On this page
  1. Build and start
  2. Address elements by test ID
  3. Showcase data for screenshots
  4. Optional native navigation measurements (#337)
  5. The installed store preview (#235)
  6. Check that every element has a test ID
  7. Flows
  8. Known gap: the global shortcut
  9. Restore the desktop after a test
  10. Agent skill lifecycle verification (#545)

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 windows lists it as Gitoodo 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, user tester) and an in-memory token store. No real token, no network, no keychain. The account keeps the fixed id acc-fixture across restarts, so per-account state such as folded groups persists; other accounts are removed.
  • Test IDs in the accessibility tree: each data-testid is mirrored into the DOM id (shown as #id in the cu snapshot) and into aria-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 above

Every 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-root

With 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 name

It 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 in seen.json of the test config dir (~/Library/Application Support/de.gitoodo.app.testaccess/).
  • Share: click questions-share-… (the system share sheet) or questions-copy-….
  • Deadline reminder: the first sync arms it (reminders.json, "fired": false). With GITOODO_TEST_CLOCK_HOURS=40 set at start, the clock runs 40 h ahead from the second check on, so clicking shell-sync makes it fall due. The log then has a test_notification event (~/Library/Logs/de.gitoodo.app.testaccess/gitoodo.log).
  • Notification permission: always Granted in 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/skills is a fixture folder. Install, remove, the folder panel (it starts in the fixture folder) and the copyable Terminal command work against it; the real ~/.claude is untouched. The folder bookmark exists only in the store build: build with --features test-access,store to 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-j and settings-shortcut-test-press-escape. Click settings-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:notification scope to check.
  • Detached window (#197): click shell-detach. The window gets its title bar and the button turns into shell-attach; clicking it (or closing the window) returns to the popover. The frame is stored in detached-window.json of 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-send posts 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), then detail-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.

Docs version: dev