# Tester - HTTP Contract Test Runner

Web UI for discovering and running contract tests.

## Quick Start

```bash
# Sync tests from production repo (local dev)
/home/mariano/wdir/ama/core_nest/pawprint/ctrl/sync-tests.sh

# Run locally
cd /home/mariano/wdir/ama/pawprint/ward
python -m tools.tester

# Open in browser
http://localhost:12003/tester
```

## Architecture

**Test Definitions** → **Tester (Runner + UI)** → **Target API**

```
amar_django_back_contracts/
└── tests/contracts/          ← Test definitions (source of truth)
    ├── mascotas/
    ├── productos/
    └── workflows/

ward/tools/tester/
├── tests/                    ← Synced from contracts (deployment)
│   ├── mascotas/
│   ├── productos/
│   └── workflows/
├── base.py                   ← HTTP test base class
├── core.py                   ← Test discovery & execution
├── api.py                    ← FastAPI endpoints
└── templates/                ← Web UI

```

## Strategy: Separation of Concerns

1. **Tests live in production repo** (`amar_django_back_contracts`)
   - Developers write tests alongside code
   - Tests are versioned with the API
   - PR reviews include test changes

2. **Tester consumes tests** (`ward/tools/tester`)
   - Provides web UI for visibility
   - Runs tests against any target (dev, stage, prod)
   - Shows test coverage to product team

3. **Deployment syncs tests**
   - `sync-tests.sh` copies tests from contracts to tester
   - Deployment script includes test sync
   - Server always has latest tests

## Configuration

### Single Environment (.env)

```env
CONTRACT_TEST_URL=https://demo.amarmascotas.ar
CONTRACT_TEST_API_KEY=your-api-key-here
```

### Multiple Environments (environments.json)

Configure multiple target environments with individual tokens:

```json
[
  {
    "id": "demo",
    "name": "Demo",
    "url": "https://demo.amarmascotas.ar",
    "api_key": "",
    "description": "Demo environment for testing",
    "default": true
  },
  {
    "id": "dev",
    "name": "Development",
    "url": "https://dev.amarmascotas.ar",
    "api_key": "dev-token-here",
    "description": "Development environment"
  },
  {
    "id": "prod",
    "name": "Production",
    "url": "https://amarmascotas.ar",
    "api_key": "prod-token-here",
    "description": "Production (use with caution!)"
  }
]
```

**Environment Selector**: Available in UI header on both Runner and Filters pages. Selection persists via localStorage.

## Web UI Features

- **Filters**: Advanced filtering by domain, module, status, and search
- **Runner**: Execute tests with real-time progress tracking
- **Multi-Environment**: Switch between dev/stage/prod with per-environment tokens
- **URL State**: Filter state persists via URL when running tests
- **Real-time Status**: See test results as they run

## API Endpoints

```
GET  /tools/tester/                        # Runner UI
GET  /tools/tester/filters                 # Filters UI
GET  /tools/tester/api/tests               # List all tests
GET  /tools/tester/api/environments        # List environments
POST /tools/tester/api/environment/select  # Switch environment
POST /tools/tester/api/run                 # Start test run
GET  /tools/tester/api/run/{run_id}        # Get run status (polling)
GET  /tools/tester/api/runs                # List all runs
```

## Usage Flow

### From Filters to Runner

1. Go to `/tools/tester/filters`
2. Filter tests (domain, module, search)
3. Select tests to run
4. Click "Run Selected"
5. → Redirects to Runner with filters applied and auto-starts execution

### URL Parameters

Runner accepts URL params for deep linking:

```
/tools/tester/?run=abc123&domains=mascotas&search=owner
```

- `run` - Auto-load results for this run ID
- `domains` - Filter by domains (comma-separated)
- `modules` - Filter by modules (comma-separated)
- `search` - Search term for test names
- `status` - Filter by status (passed,failed,skipped)

## Deployment

Tests are synced during deployment:

```bash
# Full deployment (includes test sync)
cd /home/mariano/wdir/ama/pawprint/deploy
./deploy.sh

# Or sync tests only
/home/mariano/wdir/ama/core_nest/pawprint/ctrl/sync-tests.sh
```

## Why This Design?

**Problem**: Tests scattered, no visibility, hard to demonstrate value

**Solution**:
- Tests in production repo (developer workflow)
- Tester provides visibility (product team, demos)
- Separation allows independent evolution

**Benefits**:
- Product team sees test coverage
- Demos show "quality dashboard"
- Tests protect marketplace automation work
- Non-devs can run tests via UI

## Related

- Production tests: `/home/mariano/wdir/ama/amar_django_back_contracts/tests/contracts/`
- Sync script: `/home/mariano/wdir/ama/core_nest/pawprint/ctrl/sync-tests.sh`
- Ward system: `/home/mariano/wdir/ama/pawprint/ward/`