Run Integration Tests

Run Integration Tests

Execute the integration test suite inside cmux, then introspect every spawned session to verify the full subagent lifecycle worked end-to-end.

Step 1: Preflight Checks

Verify the environment is ready:

echo "CMUX_SOCKET_PATH=$CMUX_SOCKET_PATH"
echo "TMUX=$TMUX"
node --version

• At least one of CMUX_SOCKET_PATH or TMUX must be set
• Node 22+ required

If neither mux is available, stop and tell the user to run inside cmux or tmux.

Step 2: Run Unit Tests

Run the fast unit tests first — if these fail, skip integration tests:

cd /Users/haza/Projects/pi-interactive-subagents && node --test test/test.ts

All 114 unit tests must pass. If any fail, stop and fix them before proceeding.

Step 3: Run Integration Tests

Use cmux to run the integration tests in a dedicated surface so the main session stays responsive.

SURFACE=$(cmux new-surface --type terminal | awk '{print $2}')
sleep 0.5
cmux send --surface $SURFACE 'cd /Users/haza/Projects/pi-interactive-subagents && node --test --test-concurrency=1 test/integration/mux-surface.test.ts test/integration/subagent-lifecycle.test.ts 2>&1; echo __TESTS_DONE_$?__\n'

--test-concurrency=1 is required: the focus-preservation test asserts global mux state and would race against parallel suites.

Poll until the sentinel appears:

cmux read-screen --surface $SURFACE --lines 200

Look for __TESTS_DONE_0__ (success) or __TESTS_DONE_1__ (failure). Poll every 15 seconds. Timeout after 10 minutes.

Once done, capture the full output and close the surface:

cmux read-screen --surface $SURFACE --scrollback --lines 500
cmux close-surface --surface $SURFACE

Expected results

All 15 tests must pass. If any fail, report the failure output and stop.

The long-running keeps a long active tool call from surfacing false stalled status test in subagent-lifecycle runs ~100s on its own — total wall time is ~3:30.

Configuration

Override defaults with environment variables:

Step 4: Introspect Sessions

After tests pass, verify the sessions created during the test run are well-formed. Find them by looking for session directories matching the temp dir pattern:

# Find session dirs created in the last 15 minutes
find ~/.pi/agent/sessions -type d -name '--private-var-*pi-integ*' -mmin -15 2>/dev/null

If no directory is found, widen the search:

find ~/.pi/agent/sessions -type d -name '*pi-integ*' 2>/dev/null | tail -5

Once found, analyze every session file in that directory:

SESSION_DIR="<the directory found above>"
for f in "$SESSION_DIR"/*.jsonl; do
  echo "=== $(basename $f) ==="
  head -1 "$f" | python3 -c "
import sys, json
d = json.loads(sys.stdin.readline())
print(f\"  type: {d.get('type')}  id: {d.get('id','?')[:12]}  parent: {'YES' if d.get('parentSession') else 'no'}\")
"
  python3 -c "
import sys, json
roles = {}
for line in open('$f'):
    line = line.strip()
    if not line: continue
    try:
        d = json.loads(line)
        t = d.get('type','?')
        if t == 'message':
            r = d.get('message',{}).get('role','?')
            roles[r] = roles.get(r,0)+1
        else:
            roles[t] = roles.get(t,0)+1
    except: pass
print('  entries:', ' '.join(f'{k}:{v}' for k,v in sorted(roles.items())))
"
done

What to verify

Check each session against these criteria:

Run a comprehensive validation:

python3 -c "
import json, os, sys, glob

session_dir = '$SESSION_DIR'
files = sorted(glob.glob(os.path.join(session_dir, '*.jsonl')))
print(f'Found {len(files)} session files\n')

parents = []
children = []
errors = []

for f in files:
    name = os.path.basename(f)
    lines = [json.loads(l) for l in open(f) if l.strip()]
    if not lines:
        errors.append(f'{name}: empty file')
        continue

    header = lines[0]
    if header.get('type') != 'session':
        errors.append(f'{name}: first entry is {header.get(\"type\")}, not session')
        continue

    is_child = bool(header.get('parentSession'))
    msgs = [l for l in lines if l.get('type') == 'message']
    user_msgs = [m for m in msgs if m.get('message',{}).get('role') == 'user']
    asst_msgs = [m for m in msgs if m.get('message',{}).get('role') == 'assistant']
    tool_results = [m for m in msgs if m.get('message',{}).get('role') == 'toolResult']
    error_entries = [l for l in lines if l.get('type') == 'error']

    info = {
        'name': name,
        'entries': len(lines),
        'users': len(user_msgs),
        'assistants': len(asst_msgs),
        'tools': len(tool_results),
        'errors': len(error_entries),
        'is_child': is_child,
    }

    if is_child:
        children.append(info)
    else:
        parents.append(info)

    # Validate
    if not user_msgs:
        errors.append(f'{name}: no user messages')
    if not asst_msgs:
        errors.append(f'{name}: no assistant messages')
    if error_entries:
        errors.append(f'{name}: has {len(error_entries)} error entries')

    # Check for aborted final assistant
    for m in reversed(msgs):
        if m.get('message',{}).get('role') == 'assistant':
            if m.get('message',{}).get('stopReason') == 'aborted':
                errors.append(f'{name}: final assistant message was aborted')
            break

print(f'Parent sessions: {len(parents)}')
for p in parents:
    print(f'  {p[\"name\"][:40]}  entries:{p[\"entries\"]}  user:{p[\"users\"]}  asst:{p[\"assistants\"]}  tools:{p[\"tools\"]}')

print(f'\nChild sessions (parentSession set): {len(children)}')
for c in children:
    print(f'  {c[\"name\"][:40]}  entries:{c[\"entries\"]}  user:{c[\"users\"]}  asst:{c[\"assistants\"]}  tools:{c[\"tools\"]}')

fork_count = sum(1 for c in children if c['is_child'])
print(f'\nFork sessions: {fork_count}')

if errors:
    print(f'\n❌ ERRORS ({len(errors)}):')
    for e in errors:
        print(f'  - {e}')
    sys.exit(1)
else:
    print(f'\n✅ All {len(files)} sessions are well-formed')
    print(f'   {len(parents)} parent + {len(children)} child sessions')
    print(f'   {fork_count} fork-linked session(s)')
"

Step 5: Report

Print a final summary:

╭─────────────────────────────────────────────╮
│ Integration Test Results                    │
├─────────────────────────────────────────────┤
│ Unit tests:        114/114 ✅               │
│ Mux surface:       8/8  ✅                  │
│ Subagent lifecycle: 7/7  ✅                 │
│ Session validation: X sessions verified ✅  │
│ Fork linkage:      verified ✅              │
╰─────────────────────────────────────────────╯

If any step failed, summarize what broke and suggest next steps.

Source: HazAT/pi-interactive-subagents — distributed by TomeVault.