clide/.claude/skills/testmode/SKILL.md

name, description

name

description

testmode

Run and interpret the ClideTestApp platform integration harness. Use after modifying toolchain resolution, IPC dispatch, extension lifecycle, theme loading, or native platform code. Also use when the user says "run testmode", "test the app", "smoke test", or "verify the build". Triggers on changes to: lib/kernel/src/toolchain.dart, lib/src/daemon/dispatcher.dart, lib/src/ipc/, lib/extension/, lib/kernel/src/theme/, lib/builtin/*/src/extension.dart, linux/CMakeLists.txt, macos/, Makefile (run targets), lib/main.dart.

Testmode harness

ClideTestApp is a lightweight Flutter app that boots the real platform layer, runs structured tests, prints results, and exits. It catches regressions that unit tests cannot see: missing binaries, broken subprocess wiring, IPC dispatch failures, extension activation order, and theme parse errors.

Running

make run-testmode                             # all categories, 60s timeout
make run-testmode TESTMODE_CATEGORY=toolchain
make run-testmode TESTMODE_CATEGORY=ipc
make run-testmode TESTMODE_CATEGORY=extensions
make run-testmode TESTMODE_TIMEOUT=120        # longer timeout for slow builds

Results go to stdout and /tmp/clide-testmode.log. The last line of testmode output is machine-readable:

[testmode:json] {"passed":33,"failed":0,"total":33,"failures":[]}

Exit code is non-zero when any test fails. The Makefile verifies "failed":0 in the log via grep -q.

When to run which category

Changed area	Category	Why
Toolchain, PATH, dugite, ptyc, shell	toolchain	Binary resolution + exec
IPC envelope, dispatcher, schema	ipc	Round-trip + error contract
Extension manifest, activate, contributions	extensions	Register + activate lifecycle
Theme YAML, loader, palette	extensions	Theme parse is in this category
Platform config (CMakeLists, pbxproj, Makefile)	all	Full rebuild validates everything
Any doubt	all	~30s, cheap insurance

Interpreting output

• [testmode] exec | ... | OK — subprocess ran, exit 0 or 1.
• [testmode] PASS | ... — assertion passed (IPC / extension tests).
• [testmode] FAIL | ... — assertion failed. The output column says why.
• [testmode] exec | ... | EXCEPTION — binary not found or not executable.
• [testmode] exec | ... | TIMEOUT — subprocess hung (5s limit).

If the app never prints [testmode] lines, the testmode gate in main.dart didn't fire — check that CLIDE_TESTMODE is set to a non-empty string (not a bare bool).

Adding tests

All test logic lives in lib/test_app.dart. Pattern:

// In the appropriate _run*Tests method:
await _testExec('label', binary, ['args'], workDir);
// or
_addResult('label', boolCondition, 'detail string');

New categories: add a runFoo bool from the category string, gate a new _runFooTests method, and add the category name to the Makefile help comment and this skill's table above.

Extension tests must include transitive dependencies — e.g. GitExtension requires DiffExtension to activate first.

Source files

• lib/test_app.dart — all test logic and UI
• lib/main.dart:54 — testmode gate (String.fromEnvironment)
• Makefile:42–56 — run-testmode target with category variable