updated docs

docs/data/en/station-tester.md

@@ -0,0 +1,99 @@
+# 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.