# ACP Integration Test Environment

This directory contains utilities and fixtures for integration testing with the `dirigent_acp_mocker`.

## Structure

- **mocker_utils.rs** - Utilities for spawning and managing mocker processes
- **golden_transcripts.rs** - Golden transcript fixtures for common ACP flows
- **README.md** - This file

## Running Tests

### Basic Tests (No Process Spawning)

```bash
# Run all tests
cargo test --package dirigent_core --test acp_mocker_test

# Run specific test
cargo test --package dirigent_core --test acp_mocker_test test_golden_transcripts_available
```

### Integration Tests (With Process Spawning)

These tests spawn actual mocker processes and are ignored by default.

```bash
# Run all ignored tests (spawns processes)
cargo test --package dirigent_core --test acp_mocker_test -- --ignored

# Run specific ignored test
cargo test --package dirigent_core --test acp_mocker_test test_spawn_stdio_mocker -- --ignored

# Run all tests (including ignored ones)
cargo test --package dirigent_core --test acp_mocker_test -- --include-ignored
```

## Mocker Utilities

### Spawning a Mocker in Stdio Mode

```rust
use dirigent_core::tests::acp_integration::MockerProcess;

#[tokio::test]
#[ignore]
async fn test_with_stdio_mocker() {
    let mocker = MockerProcess::spawn_stdio().await.unwrap();

    // Use mocker via stdin/stdout...

    mocker.kill().await.unwrap();
}
```

### Spawning a Mocker in HTTP Mode

```rust
use dirigent_core::tests::acp_integration::MockerProcess;

#[tokio::test]
#[ignore]
async fn test_with_http_mocker() {
    let port = 18888;
    let mocker = MockerProcess::spawn_http(port).await.unwrap();

    // Connect to mocker at http://localhost:18888

    mocker.kill().await.unwrap();
}
```

### Using Configuration Presets

```rust
use dirigent_core::tests::acp_integration::{MockerProcess, MockerConfig};

#[tokio::test]
#[ignore]
async fn test_with_configured_mocker() {
    let config = MockerConfig::with_preset("basic");
    let args: Vec<&str> = config.to_args().iter().map(|s| s.as_str()).collect();

    let mocker = MockerProcess::spawn_stdio_with_args(&args).await.unwrap();

    // Use mocker...

    mocker.kill().await.unwrap();
}
```

## Golden Transcripts

Golden transcripts represent expected request/response sequences for testing.

```rust
use dirigent_core::tests::acp_integration::load_golden_transcript;

#[test]
fn test_with_golden_transcript() {
    let transcript = load_golden_transcript("initialize").unwrap();

    let request = &transcript["request"];
    let response = &transcript["response"];

    // Validate against actual mocker responses...
}
```

### Available Transcripts

- **initialize** - Initialize handshake with capabilities exchange
- **new_session** - Create a new session
- **prompt** - Send a simple prompt and receive streaming response
- **tool_call_read** - Tool call flow for reading a file
- **cancel** - Cancel a running session

## Windows-Specific Notes

- Process spawning uses `cargo run` to build and run the mocker
- Paths are handled cross-platform by default
- Process cleanup is automatic via Drop implementation
- If tests hang, check for orphaned mocker processes in Task Manager

## Troubleshooting

### Mocker Won't Start

1. Ensure `dirigent_acp_mocker` package builds:
   ```bash
   cargo build --package dirigent_acp_mocker
   ```

2. Try running the mocker manually:
   ```bash
   cargo run --package dirigent_acp_mocker -- serve --stdio
   ```

3. Check for port conflicts (HTTP mode):
   ```bash
   netstat -ano | findstr :18888
   ```

### Tests Timeout

- Increase the timeout duration in the test
- Check mocker logs for errors (stderr is inherited)
- Verify mocker is actually starting (add debug logging)

### Process Cleanup Issues

- The `Drop` implementation should clean up automatically
- If orphaned processes remain, kill them manually:
  ```bash
  # Windows
  taskkill /F /IM dirigent_acp_mocker.exe

  # Linux/macOS
  pkill -f dirigent_acp_mocker
  ```

## Future Work

This infrastructure is ready for:

- **TEST-01**: Protocol validation tests (stdio mode)
- **TEST-02**: Protocol validation tests (HTTP mode)
- **TEST-03**: Session update rendering tests
- **TEST-04**: Permission prompt flow tests
- **TEST-05**: File operations sandbox tests
- **TEST-06**: Terminal lifecycle tests
- **TEST-07**: Search operations tests

See `docs/building/04_acp_client/04_tasks_00_scaffolding_and_finishing.md` for the full test plan.
