orca/tests/AGENTS.md

Keep Automated Runs Out of the Foreground

Tests and agent-driven app launches share the developer's machine. They may use it; they must never take the foreground — no window raised over the editor, no focus stolen, no Dock tile churn.

src/main/window/foreground-activation-policy.ts enforces this in the main process. It is on whenever ORCA_E2E_HEADLESS=1, ORCA_E2E_HEADFUL=1, or ORCA_BACKGROUND_LAUNCH=1:

• headless / explicit background → the window never reaches the screen (Playwright drives it via CDP)
• headful without explicit background → showInactive(), no app.focus({ steal: true }), no moveTop()/always-on-top reinforcement
• macOS headless / explicit background → accessory activation policy, so no Dock tile and no menu-bar takeover

Rules when adding tests or scripts:

• Launch through tests/e2e/helpers/orca-app.ts (or orca-restart.ts) — they already set the env.
• A raw electron.launch() outside those helpers must pass ORCA_BACKGROUND_LAUNCH: '1'.
• Do not reveal windows in explicit background or headless runs. Only an explicitly headful run may call showInactive(); never call show() or bringToFront() in automated background checks.
• Tag a spec @headful only when it needs real pixels; it still runs in the background.
• Native-focus tests belong on an isolated display or CI. Do not set ORCA_E2E_FOREGROUND=1 on the user’s desktop; it cannot override explicit background mode.

Isolated terminal performance presentation

The Terminal Perf workflow has one explicit exception to the no-reveal rule: after windowless startup, terminal-perf-presentation.ts presents the benchmark window without focus on its isolated Xvfb display. Chromium otherwise throttles undrawn frames to one per second and makes typing measurements invalid. This exception requires all of:

• ORCA_E2E_TERMINAL_PERF_XVFB=1, set inside xvfb-run by that workflow;
• Linux, GITHUB_ACTIONS=true, RUNNER_ENVIRONMENT=github-hosted, and a nonempty DISPLAY;
• the page fixture to finish loading before presentation, and confirmed native window visibility.

Keep ORCA_BACKGROUND_LAUNCH=1: the application must still suppress automatic reveals and focus. isWindowlessLaunch describes that automatic launch policy, not the window's current visibility. This exception belongs only to this benchmark fixture; do not generalize it to local or self-hosted runs, paired-client helpers, native-focus tests, or production window policy. Background terminal panes remain hidden. Evidence: docs/reference/terminal-perf-latency-investigation.md.