# Example Tests

This directory contains CI tests for all examples in the `synqed-samples` repository.

## Overview

These tests ensure that all example code works correctly and can be used as a reference for:
- Pre-commit validation
- CI/CD pipelines
- Documentation validation
- API compatibility checks

## Test Categories

### Intro Examples (`intro/`)
- **test_workspace.py** - Tests workspace-based multi-agent collaboration
- **test_synqed_agent.py** - Tests agent creation and server hosting
- **test_synqed_client.py** - Tests client connection and communication
- **test_agent_card.py** - Tests agent card metadata endpoint

### Email Examples (`email/`)
- **test_single_workspace.py** - Tests email-based agent coordination
- **test_parallel_workspaces.py** - Tests parallel workspace execution
- **test_dynamic_agents.py** - Tests dynamic agent creation and registry
- **test_email_comprehensive.py** - Comprehensive email example tests

### Multi-Agentic Examples (`multi_agentic/`)
- **test_parallel_three_teams.py** - Tests parallel team execution with hierarchy
- **test_sequential_two_teams.py** - Tests sequential team workflows

### Universal Demo Examples (`universal_demo/`)
- **test_universal_substrate.py** - Tests universal substrate and A2A compatibility

### Complex Examples
- **test_maker_hanoi.py** - Tests Tower of Hanoi multi-agent solver

## Running Tests

### Run all example tests:
```bash
pytest tests/examples/ -v
```

### Run specific category:
```bash
pytest tests/examples/intro/ -v
pytest tests/examples/email/ -v
pytest tests/examples/multi_agentic/ -v
```

### Run with test script:
```bash
./scripts/run_example_tests.sh
```

### Run with coverage:
```bash
./scripts/run_example_tests.sh --coverage
```

### Run integration tests (requires API keys):
```bash
export ANTHROPIC_API_KEY="your-key"
export OPENAI_API_KEY="your-key"
./scripts/run_example_tests.sh --integration
```

## Test Markers

- `@pytest.mark.integration` - Tests that may call external APIs (mocked by default)
- `@pytest.mark.slow` - Tests that take longer to run
- `@pytest.mark.asyncio` - Async tests

## CI Integration

These tests run automatically on:
- Every push to `main` or `develop`
- Every pull request
- Before releases

See `.github/workflows/test-examples.yml` for CI configuration.

## Writing New Example Tests

When adding a new example to `synqed-samples`, create a corresponding test:

1. Create test file: `tests/examples/category/test_example_name.py`
2. Import required modules
3. Create test functions with proper markers
4. Mock external API calls when possible
5. Assert expected behavior
6. Clean up resources (workspaces, registries, etc.)

Example template:
```python
import asyncio
import pytest
import synqed

@pytest.mark.asyncio
@pytest.mark.integration
async def test_my_example():
    """Test that my example works correctly."""
    # Setup
    async def agent_logic(context):
        return '{"send_to": "USER", "content": "done"}'
    
    agent = synqed.Agent(name="Test", logic=agent_logic)
    
    # Test
    assert agent.name == "Test"
    
    # Cleanup
    print("✅ Test passed!")
```

## Troubleshooting

### Tests fail with "ANTHROPIC_API_KEY not set"
- Tests use mock API keys by default (`test-key`)
- Integration tests require real keys (run with `--integration`)

### Import errors
- Ensure `synqed` is installed: `pip install -e .`
- Check Python path includes `src/`

### Async errors
- All async tests need `@pytest.mark.asyncio`
- Check `asyncio_mode = auto` in `pytest.ini`

### Port binding errors
- Tests use unique ports (8901, 8902, 8903, etc.)
- Ensure ports are not in use
- Tests include cleanup delays

## Maintenance

These tests should be updated when:
- Example code changes
- API signatures change
- New features are added
- Breaking changes occur

Run tests before every commit to ensure examples stay current.

