# Sandbox Test Harness

Standalone testing tools for validating ACP contract and sandbox execution.
Works with any sandbox executor (local bwrap, sidecar, etc.).

Extracted from PR #241 (sandbox-sidecar-mvp) - preserving reusable test patterns.

## Components

### `scripts/acp_probe.py`

Direct ACP JSON-RPC probe for testing the agent contract:
- `task/create` - Create a new task
- `event/send` - Send an event to a task
- `task/cancel` - Cancel a task

```bash
python3 scripts/acp_probe.py \
  --acp-url http://127.0.0.1:8000/api \
  --agent-api-key <key> \
  --event-text "test message"
```

Outputs shell-friendly markers for downstream assertions:
```
PROBE_ID=abc123
PROBE_TASK_ID=sandbox-sidecar-probe-abc123
PROBE_STATUS=ok
```

### `scripts/run_acp_smoke.sh`

End-to-end smoke test against a running agent pod:

```bash
AGENT_API_KEY=<key> ./scripts/run_acp_smoke.sh
```

What it does:
1. Auto-detects agent pod in namespace
2. Sets up port-forward to pod
3. Verifies healthz endpoint
4. Tests auth failure (invalid key rejected)
5. Runs full ACP probe (create → event → cancel)
6. Checks agent logs for handler failures

Environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `AGENT_API_KEY` | required | API key for auth |
| `KUBE_CONTEXT` | `minikube` | Kubernetes context |
| `NAMESPACE` | `platform-ns-test` | Namespace to search |
| `POD_NAME` | auto-detect | Specific pod name |
| `LOCAL_PORT` | `18080` | Port-forward local port |
| `RUN_AUTH_FAILURE_CHECK` | `true` | Test invalid auth |
| `ALLOW_NON_MINIKUBE` | `false` | Allow non-minikube contexts |

### `prompts/chaos_prompts.py`

Library of chaos test prompts for stress-testing sandbox execution:

```python
from tests.harness.prompts.chaos_prompts import (
    SUBAGENT_LOAD,    # Parallel worker stress test
    IO_STRESS,        # Filesystem I/O stress test
    TIMEOUT_TRIGGER,  # Handler timeout test
    MEMORY_PRESSURE,  # Memory allocation test
    PROCESS_ISOLATION,# PID namespace verification
    FILESYSTEM_BOUNDARY,  # Read-only mount verification
)
```

## Usage Examples

### Quick smoke test against local minikube

```bash
# Start minikube with agent deployed
make dev

# Run smoke test
cd sdks/python/tests/harness
AGENT_API_KEY=test-key ./scripts/run_acp_smoke.sh
```

### Programmatic ACP testing

```python
import subprocess
import json

result = subprocess.run([
    "python3", "scripts/acp_probe.py",
    "--acp-url", "http://127.0.0.1:8000/api",
    "--agent-api-key", "test-key",
], capture_output=True, text=True)

# Parse markers
markers = dict(line.split("=", 1) for line in result.stdout.strip().split("\n") if "=" in line)
assert markers["PROBE_STATUS"] == "ok"
```

### Chaos testing with Claude

```python
from tests.harness.prompts.chaos_prompts import IO_STRESS

# Send chaos prompt via event/send
# Verify sandbox handles I/O load without failure
```

## Design Principles

1. **Executor-agnostic**: Tests work with any sandbox backend
2. **Minimal dependencies**: Only kubectl, curl, python3
3. **Shell-friendly output**: Markers parseable by downstream scripts
4. **Safe by default**: Requires explicit opt-in for non-minikube contexts
