Testing

Do not use your everyday configuration, socket, state directory or provider credentials as test fixtures. A green unit suite is not proof of compositor support or of current vendor response formats.

The fast gateCopy Anchor Link

python3 -B -m unittest discover -s tests
bash tests/test_mux_status.sh && bash tests/test_socket_lib.sh
git diff --check

Also run bash -n and shellcheck -S error on changed shell files, and python3 -m py_compile on changed Python. Continuous integration must call each shell test explicitly: passing a script as an argument to another script does not run it.

The real-kitty rigsCopy Anchor Link

Each rig starts its own kitty, usually in a virtual display (Xvfb) with a private configuration, socket and state directory. They skip when a tool is missing. SKIP is not a pass. Record the reason and the kitty version.

Run display-sharing rigs one after another. Use SMOKE_SHOT=<absolute path prefix> with smoke_sidebar.sh to keep screenshots. To look at a visual change, render the bar with tests/shot_bar.sh in dark and light and at the narrowest width, then read the picture. For the panel use tests/shot_panel.sh dark|light OUT_DIR [COLS] [LINES] (KITTYMUX_USAGE_HOME=DIR points the usage collectors at the synthetic home it builds; unset, they read yours): it runs the real panel in a private kitty on a synthetic world (tools/demo_world.py), drives it with real key events, checks the text of the Agents, Usage and Inbox views and saves a PNG of each. Unit tests did not catch a hue palette of four near-identical greens.

The rules a rig must followCopy Anchor Link

• Never touch another kitty on the machine. The author is usually typing in a live kitty while tests run, and kitty @ launch follows focus. A rig once spawned fake agents, and through a different PATH the real claude, into the live kitty. Set KITTYMUX_SOCKET_DIRS to the rig's own directory and end with a tripwire that compares the window count of every other kitty.
• Run under socket-only. Never write a rig or a doc that needs allow_remote_control yes.
• Use real events. A perfect scripted click hides whole bug classes. Click with wobble.
• Keep modules as real copies in one configuration directory. A rig that mixes repository and configuration directories hides real bugs.
• Remove only your own instances in cleanup. Never kill processes by name.

The docs gateCopy Anchor Link

python3 -m unittest tests.test_docs checks the published pages: frontmatter, navigation, links and anchors, the feature status table, that every ctrl+alt chord a page names is really bound, and that the CLI reference covers every command. See Docs maintenance.

Edge casesCopy Anchor Link

Tests use fake credentials, temporary state and synthetic provider responses. Never turn a mocked response or a virtual-display run into a claim of live-provider or compositor verification.

Before applying a tested branchCopy Anchor Link

1. Check main and the worktree for unrelated edits. Do not stash or overwrite another person's work.
2. Bring new main commits into your branch, resolve conflicts there and repeat the gates.
3. A local edit to a file the branch changes is a blocker. Have its owner reconcile it first.
4. Record the OS window, tab and pane counts for every live kitty socket you own, without dumping pane text.
5. After a clean fast-forward, run the main checkout's bin/kittymux upgrade. Never restart.
6. Compare the counts and check ~/.local/state/kittymux/tab_bar-error.log. If the counts differ, investigate. Do not close or recreate windows to make the numbers match.