# xSwarm CLI Testing Plan

## Overview

This document outlines the comprehensive testing strategy for the xSwarm CLI. All tests are run via npm scripts and are organized into categories based on their purpose and execution model.

## Directory Structure

```
src/tests/
├── README.md           # This testing plan
├── scripts/            # Test scripts for manual/interactive testing
│   ├── test-cli-chat.js       # Automated UI mode tests
│   ├── test-interactive.js    # Interactive UI tests
│   └── test-main-cli.js       # CLI integration tests
├── unit/               # Unit tests (coming soon)
└── *.test.js          # Vitest unit tests
```

## Test Categories

### 1. Unit Tests
Run with Vitest for fast, isolated testing of individual functions and modules.

**NPM Scripts:**
```bash
npm test                # Run all unit tests
npm run test:watch      # Run tests in watch mode  
npm run test:coverage   # Run tests with coverage report
```

**Current Unit Tests:**
- `agents.test.js` - Tests agent loading functionality
- `example.test.js` - Example test file (template)

**Planned Unit Tests:**
- [ ] Session management functions
- [ ] Agent loading and caching
- [ ] Configuration handling
- [ ] Utility functions

### 2. UI Library Tests
Tests for the three UI modes: basic, simple (ANSI), and ink (React).

**NPM Scripts:**
```bash
# Automated tests (non-interactive)
npm run test:cli-chat           # Test auto-detection
npm run test:cli-chat:basic     # Test basic text mode
npm run test:cli-chat:simple    # Test ANSI terminal mode
npm run test:cli-chat:ink       # Test Ink React mode (requires TTY)
npm run test:cli-chat:auto      # Test auto-detection logic
```

**Test File:** `scripts/test-cli-chat.js`
- Tests all three UI modes
- Verifies message display
- Checks status updates
- Validates auto-detection logic

### 3. Interactive Tests
Manual tests that require user interaction in a real terminal.

**NPM Scripts:**
```bash
npm run test:interactive         # Interactive test with auto-detection
npm run test:interactive:basic   # Force basic mode
npm run test:interactive:simple  # Force simple ANSI mode
npm run test:interactive:ink     # Force Ink React mode
```

**Test File:** `scripts/test-interactive.js`
- Simulates real conversation flow
- Tests user input handling
- Verifies UI updates in real-time
- Must be run in a real terminal (not CI)

### 4. Conversation Simulation Tests
Automated long conversation simulation to test scrolling, performance, and multi-agent interactions.

**NPM Scripts:**
```bash
npm run test:conversation         # Auto-detect UI mode
npm run test:conversation:basic   # Force basic mode
npm run test:conversation:simple  # Force simple ANSI mode
npm run test:conversation:ink     # Force Ink React mode
```

**Test File:** `scripts/test-conversation.js`
- Simulates multi-agent conversation with 5 different agents
- Tests scrolling with 40+ messages
- Updates status bar (cost, agents, phase)
- Runs for ~2 minutes with new messages every 2 seconds
- Tests UI performance with rapid updates
- Allows user interaction during simulation

### 5. Integration Tests
Tests the complete CLI application with all commands.

**NPM Scripts:**
```bash
npm run test:integration    # Test CLI commands (automated)
npm run test:main          # Test main conversation flow
npm run test:main:basic    # Test with forced basic UI
```

**Test File:** `scripts/test-main-cli.js`
- Tests CLI flags: `-v`, `--config`, `-h`, `--init`
- Verifies proper exit codes
- Validates output format
- Runs without user interaction

### 6. End-to-End Tests

**NPM Scripts:**
```bash
npm run test:npx           # Test npx compatibility
npm run test:npx:simple    # Simple npx test
```

## Test Environments

### Terminal Requirements
- **Basic Mode**: Works everywhere (pipes, CI, non-TTY)
- **Simple Mode**: Requires TTY with ANSI support
- **Ink Mode**: Requires real TTY with raw mode support

### Environment Variables
- `XSWARM_UI` - Force specific UI mode: `basic`, `simple`, or `ink`
- `NO_COLOR` - Disable colors (forces basic mode)
- `CI` - Set in CI environments (forces basic mode)

## Adding New Tests

When adding new tests:

1. **Unit Tests**: Add to `src/tests/` with `.test.js` suffix
2. **Test Scripts**: Add to `src/tests/scripts/`
3. **Update this README** with:
   - Test description
   - NPM script command
   - What the test validates
4. **Add NPM script** to `package.json`

## CI/CD Testing

For CI environments, use these tests:
```bash
npm test                    # Unit tests
npm run test:cli-chat:basic # Basic UI mode
npm run test:integration    # CLI integration
```

## Known Limitations

1. Ink mode cannot be tested in CI/pipes (requires real TTY)
2. Interactive tests require manual execution
3. Some ANSI features may not work in all terminals

## Debugging Tests

To debug failing tests:
1. Check `.xswarm/debug.log` for application logs
2. Run with `DEBUG_NPX=1` for npx debugging
3. Use `--verbose` flag for detailed output
4. Check terminal capabilities with `npm run test:cli-chat:auto`

## Test Coverage Goals

- Unit test coverage: 80%+
- All UI modes tested
- All CLI commands tested
- Error scenarios covered
- Edge cases documented

## Maintenance

- Remove obsolete tests when refactoring
- Update test scripts when adding features
- Keep this README in sync with actual tests
- Run full test suite before releases