# Tester

HTTP contract test runner with web UI and CLI. Tests API endpoints against configurable environments with support for multiple auth types.

**Status:** live

---

## What It Does

Tester runs HTTP requests against real endpoints and validates responses. It is not a unit test runner. It tests contracts -- does this endpoint return what the spec says it should?

Tests are written as Python classes extending `ContractTestCase`. They run via pytest or through the soleprint web UI.

## Configuration

### Environments

Defined in `environments.json`:

```json
{
  "environments": [
    {
      "name": "local",
      "url": "http://localhost:8000",
      "auth_type": "none"
    },
    {
      "name": "staging",
      "url": "https://staging.example.com",
      "auth_type": "bearer",
      "token_endpoint": "/api/token/"
    },
    {
      "name": "external",
      "url": "https://api.example.com",
      "auth_type": "api-key"
    }
  ]
}
```

Auth types: `bearer`, `api-key`, `none`.

## Base Class

All tests extend `ContractTestCase`:

```python
from station.tools.tester.base import ContractTestCase

class TestUserEndpoints(ContractTestCase):
    AUTH_TYPE = "bearer"
    TOKEN_ENDPOINT = "/api/token/"

    def test_list_users(self):
        response = self.get("/api/users/")
        self.assertEqual(response.status_code, 200)
```

`ContractTestCase` handles auth negotiation, environment selection, and base URL resolution.

## Test Discovery

Tests live in two places:

- **Core tests:** `soleprint/station/tools/tester/tests/` -- shared across all rooms
- **Room tests:** `cfg/<room>/soleprint/station/tools/tester/tests/` -- room-specific

Room tests import from core:

```python
from station.tools.tester.base import ContractTestCase
```

After build, both are merged into `gen/<room>/station/tools/tester/tests/`.

## Helpers

Built-in test helpers:

- `unique_email()` -- generates a unique email address
- `unique_id()` -- generates a unique identifier

These are generic helpers available to all rooms. Room-specific helpers stay in `cfg/<room>/` and are not part of core.

## Running

**Web UI:** navigate to `/station/tools/tester/` in soleprint.

**CLI:**

```bash
cd gen/<room>
pytest station/tools/tester/tests/
```

Environment selection is handled via config or CLI flags.