Comprehensive testing suite for the Codebuff CLI using tmux for interactive terminal emulation.

IMPORTANT: Follow these patterns for automatic tmux detection:

• Unit tests: *.test.ts (e.g., cli-args.test.ts)
• E2E tests: e2e-*.test.ts (e.g., e2e-cli.test.ts)
• Integration tests: integration-*.test.ts (e.g., integration-tmux.test.ts)

Files matching *integration*.test.ts or *e2e*.test.ts trigger automatic tmux availability checking in .bin/bun.

cd cli
bun test

Install tmux for interactive CLI testing:

# macOS
brew install tmux

# Ubuntu/Debian
sudo apt-get install tmux

# Windows (via WSL)
wsl --install
sudo apt-get install tmux

Build the SDK first:

cd sdk
bun run build
cd ../cli

bun test

# Unit tests
bun test cli-args.test.ts

# E2E tests (requires SDK)
bun test e2e-cli.test.ts

# Integration tests (requires tmux)
bun test integration-tmux.test.ts

bun run test:tmux-poc

The .bin/bun wrapper automatically checks for tmux when running integration/E2E tests:

• Detects test files matching *integration*.test.ts or *e2e*.test.ts
• Checks if tmux is installed
• Shows installation instructions if missing
• Skips tests gracefully if tmux unavailable

Benefits:

• ✅ Project-wide (works in any package)
• ✅ No hardcoded paths
• ✅ Clear test categorization
• ✅ Automatic dependency validation

Test individual functions in isolation:

import { describe, test, expect } from 'bun:test'

describe('CLI Arguments', () => {
  test('parses --agent flag', () => {
    // Test implementation
  })
})

Test interactive CLI with full terminal emulation:

import { describe, test, expect } from 'bun:test'
import { isTmuxAvailable } from './test-utils'

const tmuxAvailable = isTmuxAvailable()

describe.skipIf(!tmuxAvailable)('CLI Integration Tests', () => {
  test('handles user input', async () => {
    // Create tmux session
    // Send commands
    // Verify output
  })
})

Test complete CLI workflows:

import { describe, test, expect } from 'bun:test'
import { isSDKBuilt } from './test-utils'

const sdkBuilt = isSDKBuilt()

describe.skipIf(!sdkBuilt)('CLI E2E Tests', () => {
  test('runs --help command', async () => {
    // Test CLI behavior
  })
})

Shared utilities in test-utils.ts:

import { isTmuxAvailable, isSDKBuilt, sleep } from './test-utils'

// Check for tmux
if (isTmuxAvailable()) {
  // Run tmux tests
}

// Check for SDK
if (isSDKBuilt()) {
  // Run E2E tests
}

// Async delay
await sleep(1000)

See ../../tmux.knowledge.md for comprehensive tmux documentation, including:

• Why standard send-keys doesn't work (must use bracketed paste mode)
• Helper functions for Bash and TypeScript
• Complete example scripts
• Debugging and troubleshooting tips

Quick reference:

// ❌ Broken:
await tmux(['send-keys', '-t', session, 'hello'])

// ✅ Works:
await tmux(['send-keys', '-t', session, '-l', '\x1b[200~hello\x1b[201~'])

# Verbose test output
bun test --verbose

# Watch mode
bun test --watch

When adding new tests:

1. Follow naming convention (*integration*.test.ts or *e2e*.test.ts)
2. Use test-utils.ts for shared functionality
3. Add graceful skipping for missing dependencies
4. Clean up resources (tmux sessions, temp files)
5. Document test purpose clearly in test descriptions

⚠️  tmux not found but required for integration/E2E tests

Solution: Install tmux (see Prerequisites above)

✓ Build SDK for E2E tests: cd sdk && bun run build [skip]

Solution: Build the SDK first (see Prerequisites above)

• Check tmux session isn't waiting for input
• Ensure proper cleanup in finally blocks
• Use timeouts for tmux operations

• Use unique session names (e.g., timestamp suffix)
• Clean up sessions in beforeEach/afterEach

• Unit tests: ~100ms total
• Integration tests: ~2-5s per test (tmux overhead)
• E2E tests: ~3-10s per test (full CLI startup)

For CI environments:

# Install tmux in CI
- name: Install tmux
  run: |
    sudo apt-get update
    sudo apt-get install -y tmux

# Run tests
- name: Run tests
  run: bun test