# Test: `ps`
Integration test planning for the `ps` command. See [command/06_ps.md](../../../../docs/cli/command/06_ps.md) for specification.
`ps` lists running Claude Code processes and queued `clr` waiters in two plain-style
tables. Tests run in the container where 0 live `claude` processes are present. The
≥1-session tests spawn a fake `claude` background process using the
`fake_claude_binary_dir` helper and prepend it to PATH. Gate file tests create a
temp dir as `CLR_GATE_DIR` and write a fake JSON state file to exercise the
queued-sessions table path without a live `gate.rs` waiter.
## Test Case Index
| IT-1 | `clr ps` with 0 sessions → exit 0, no-sessions message | No-sessions |
| IT-2 | `clr ps` with ≥1 session → exit 0, plain table (no `┌` border) | Sessions present |
| IT-3 | `clr --help` lists `ps` | Help listing |
| IT-4 | `clr p` (typo) → exit 1, stderr: Did you mean | Typo guard |
| IT-5 | `clr ps` table contains `PID`, `Elapsed`, `Absolute Path`, `Task` headers | Column presence |
| IT-6 | `clr pss` (typo) → exit 1, stderr: Did you mean | Typo guard |
| IT-7 | `clr ps` PID not in own output | Self-exclusion |
| IT-8 | `clr ps --unknown` → exit 1 | Error handling |
| IT-9 | `$PRO` prefix replaced by `"$PRO"` in Absolute Path column | Path shortening |
| IT-10 | Gate file present → queued table with `PID`, `CWD`, `Waiting` headers | Queued present |
| IT-11 | No gate files → no queued table in output | Queued absent |
| IT-12 | Active table caption contains `Active Sessions` and `running` | Caption presence |
## Test Coverage Summary
- No-sessions: 1 test (IT-1)
- Sessions present: 1 test (IT-2)
- Help listing: 1 test (IT-3)
- Typo guard: 2 tests (IT-4, IT-6)
- Column presence: 1 test (IT-5)
- Self-exclusion: 1 test (IT-7)
- Error handling: 1 test (IT-8)
- Path shortening: 1 test (IT-9)
- Queued present: 1 test (IT-10)
- Queued absent: 1 test (IT-11)
- Caption presence: 1 test (IT-12)
**Total:** 12 tests
---
### IT-1: 0 sessions → no-sessions message
- **Command:** `clr ps` (container has 0 live `claude` processes)
- **Expected behavior:** stdout = `No active Claude Code sessions.`; exit 0
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-2: ≥1 sessions → plain-style table
- **Setup:** fake `claude` binary placed in temp dir; PATH prepended; binary sleeps 30s to stay alive during test
- **Command:** `clr ps`
- **Expected behavior:** Exit 0; stdout contains `PID` header; stdout does NOT contain `┌` (plain style, no borders)
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-3: `clr --help` lists `ps`
- **Command:** `clr --help`
- **Expected behavior:** stdout contains `ps`
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-4: Typo `clr p` triggers guard
- **Command:** `clr p`
- **Expected behavior:** stderr contains `Did you mean`; exit 1
- **Exit:** 1
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-5: Table headers present
- **Setup:** ≥1 fake `claude` process running
- **Command:** `clr ps`
- **Expected behavior:** stdout contains `PID`, `Elapsed`, `Absolute Path`, and `Task`; exit 0
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-6: Typo `clr pss` triggers guard
- **Command:** `clr pss`
- **Expected behavior:** stderr contains `Did you mean`; exit 1
- **Exit:** 1
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-7: `clr ps` not listed in own output
- **Setup:** ≥1 fake `claude` process running; capture PID of `clr ps`
- **Command:** `clr ps`
- **Expected behavior:** The `clr ps` process PID is not present in stdout; exit 0
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
- **Note:** `find_claude_processes()` excludes the caller's PID; this test verifies end-to-end exclusion
---
### IT-8: Unknown flag → exit 1
- **Command:** `clr ps --unknown`
- **Expected behavior:** stderr contains an error message; exit 1
- **Exit:** 1
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-9: `$PRO` prefix shortened in Absolute Path column
- **Setup:** temp dir created as fake `$PRO`; subdirectory `my/project` created within it; fake `claude` ELF spawned with `current_dir = $PRO/my/project`; `PRO` set to temp dir path when running `clr ps`
- **Command:** `clr ps` (with `PRO=<temp_dir>` in env)
- **Expected behavior:** stdout contains `"$PRO"` (literal); stdout does NOT contain the full temp dir path; exit 0
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-10: Gate file present → queued table with headers
- **Setup:** temp dir used as `CLR_GATE_DIR`; write `{arbitrary_pid}.json` with valid gate JSON (`cwd`, `since`, `attempt`, `message`)
- **Command:** `clr ps` (with `CLR_GATE_DIR=<temp_dir>` in env)
- **Expected behavior:** Exit 0; stdout contains `PID`, `CWD`, and `Waiting` column headers (queued table)
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
- **Note:** No live `clr` waiter needed — the test writes the state file directly to exercise the read path
---
### IT-11: No gate files → no queued table
- **Setup:** temp dir used as `CLR_GATE_DIR`; directory is empty (no JSON files)
- **Command:** `clr ps` (with `CLR_GATE_DIR=<temp_dir>` in env, 0 live sessions)
- **Expected behavior:** Exit 0; stdout = `No active Claude Code sessions.`; stdout does NOT contain `Waiting` or `Attempt` headers
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
---
### IT-12: Active table caption contains `Active Sessions` and `running`
- **Setup:** fake `claude` binary placed in temp dir; PATH prepended; binary sleeps 30s
- **Command:** `clr ps`
- **Expected behavior:** Exit 0; stdout contains `Active Sessions` (caption title) and `running` (count suffix)
- **Exit:** 0
- **Source:** [command/06_ps.md](../../../../docs/cli/command/06_ps.md)
- **Note:** The caption rule line (e.g., `─── Active Sessions · 1 running ──────`) appears above the column header row in the rendered table