con-cli E2E & con-test

Use this skill when the task is to verify that Con's CLI/control plane works against a live app window, or when writing/fixing integration tests in crates/con-test/testdata/.

Primary reference:

• Read docs/impl/con-cli-e2e.md for the full workflow and current live limitations.

con-cli manual E2E

Default workflow:

1. Build the relevant crates.
2. Launch cargo run -p con.
3. Wait for /tmp/con.sock.
4. Use con-cli --json identify, tabs list, and panes list before acting.
5. Only use panes exec on panes that expose exec_visible_shell.
6. Use tree / surfaces list only for pane-local surface validation.
7. After surfaces create or surfaces split, use surfaces wait-ready --surface-id <id> --timeout 10 before sending input that assumes an initialized shell.
8. Use agent ask to verify the real in-tab built-in agent session.

Rules:

• Prefer --json for every command in automated evaluation.
• Prefer pane_id over pane_index for follow-up actions.
• Prefer surface_id for follow-up actions only when testing the explicit surfaces.* API.
• Keep existing pane and agent benchmarks on panes.*; surfaces are additive and must not change the built-in agent's pane model.
• After visible execution, confirm the pane still reports shell_prompt and keeps exec_visible_shell.
• If agent ask fails, check provider config/env before blaming the socket layer.

Known current limit:

• panes create now reports surface_ready, is_alive, and has_shell_integration, but startup-command panes can still be in a non-shell foreground state immediately after creation. Treat them as provisional until panes list confirms the capabilities you need for the next step.

con-test integration tests

con-test is the E2E test runner for integration and interactive behavior. It launches a real con session, runs .test files against it via con-cli, and checks output.

Running tests

# Build first
cargo build

# Run all tests
./target/debug/con-test crates/con-test/testdata/

# Run a single file
./target/debug/con-test crates/con-test/testdata/panes/split.test

Test file format

Test files live in crates/con-test/testdata/<group>/<name>.test. Each step is a con-cli command followed by an assertion block:

# comment
con-cli --json <command>   # step description
---- <assertion>
<expected>

Assertion types:

The json-subset assertion only checks the keys you specify — extra fields in the actual output are ignored. Use it to assert specific fields without coupling to the full response shape.

Writing new tests

• Unit-test functions in Rust (#[cfg(test)]) for logic. Use con-test only for integration and interactive behavior that requires a live session.
• No low-value tests — don't write tests just to hit coverage. Every test should catch a real bug or document a real contract.
• Group tests by domain: panes/, tabs/, agent/, system/.
• After panes create, always add a panes wait step before asserting is_alive — the new pane's surface may not be ready immediately.
• For agent panel tests, use agent open-panel-for-request to drive the motion state, then agent panel-state to assert the result.

Example test

# panes/split.test
con-cli --json panes list --tab 1  # start with 1 pane
---- json-subset
{"panes":[{"index":1}]}

con-cli --json panes create --tab 1 --location right  # split right
---- ok

con-cli --json panes wait --tab 1 --pane-index 2 --timeout 5  # wait for new pane
---- ok

con-cli --json panes list --tab 1  # both panes alive
---- json-subset
{"panes":[{"is_alive":true},{"is_alive":true}]}

Fixing failures

When a test fails with expected JSON is not a subset of actual JSON, the actual output is printed in full. Check:

1. Is the command missing (unrecognized subcommand)? → Add the subcommand to con-cli and the ControlCommand handler.
2. Is a field wrong/missing? → Fix the handler's response shape.
3. Is the assertion racing (e.g. is_alive: false right after create)? → Add a panes wait or surfaces wait-ready step before the assertion.