env vars

docs/TESTS.md

@@ -273,60 +273,49 @@ This pattern applies equally to integration tests (with real database operations
 
 ---
 
-## Docker E2E Setup
+## Docker-Based Tests (Website ↔ API Wiring)
 
-### Architecture
+This repo uses Docker in two different ways:
 
-E2E tests run against a full stack orchestrated by `docker-compose.test.yml`:
+1) **Website ↔ API smoke (wiring validation)**
+   - Orchestrated by [`docker-compose.test.yml`](docker-compose.test.yml:1) at the repo root.
+   - Runs:
+     - Website in Docker (Next.js dev server)
+     - An API mock server in Docker (Node HTTP server)
+   - Goal: catch misconfigured hostnames/ports/env vars and CORS issues that only show up in Dockerized setups.
 
-```yaml
-services:
-  postgres:
-    image: postgres:16
-    environment:
-      POSTGRES_DB: gridpilot_test
-      POSTGRES_USER: test
-      POSTGRES_PASSWORD: test
+2) **Hosted-session automation E2E (fixture-driven automation)**
+   - Orchestrated by `docker/docker-compose.e2e.yml` (separate stack; documented later in this file).
+   - Goal: validate Playwright-driven automation against HTML fixtures.
 
-  redis:
-    image: redis:7-alpine
+### Website ↔ API smoke: how to run
 
-  web-api:
-    build: ./src/apps/web-api
-    depends_on:
-      - postgres
-      - redis
-    environment:
-      DATABASE_URL: postgres://test:test@postgres:5432/gridpilot_test
-      REDIS_URL: redis://redis:6379
-    ports:
-      - "3000:3000"
-```
+Run:
+- `npm run test:docker:website` (see [`package.json`](package.json:92))
 
-### Execution Flow
+What it does (in order):
+- Installs deps in a dedicated Docker volume (`npm run docker:test:deps`)
+- Starts the test stack (`npm run docker:test:up`)
+- Waits for readiness (`npm run docker:test:wait`)
+- Runs Playwright smoke tests (`npm run smoke:website:docker`)
 
-1. **Start Services:** `docker compose -f docker-compose.test.yml up -d`
-2. **Run Migrations:** `npm run migrate:test` (seeds database)
-3. **Execute Tests:** Playwright targets `http://localhost:3000`
-4. **Teardown:** `docker compose -f docker-compose.test.yml down -v`
+Ports used:
+- Website: `http://localhost:3100`
+- API mock: `http://localhost:3101`
 
-### Environment Setup
+Key contract:
+- Website must resolve the API base URL via [`getWebsiteApiBaseUrl()`](apps/website/lib/config/apiBaseUrl.ts:6).
+- The website’s HTTP client uses `credentials: 'include'`, so the API must support CORS-with-credentials (implemented for the real API in [`bootstrap()`](apps/api/src/main.ts:14)).
 
-```bash
-# tests/e2e/setup.ts
-export async function globalSetup() {
-  // Wait for web-api to be ready
-  await waitForService('http://localhost:3000/health');
-  
-  // Run database migrations
-  await runMigrations();
-}
+### “Mock vs Real” (Website & API)
 
-export async function globalTeardown() {
-  // Stop Docker Compose services
-  await exec('docker compose -f docker-compose.test.yml down -v');
-}
-```
+- The Website does **not** have a runtime flag like `AUTOMATION_MODE`.
+- “Mock vs real” for the Website is **only** which API base URL it uses:
+  - Browser: `NEXT_PUBLIC_API_BASE_URL`
+  - Server: `API_BASE_URL` (preferred in Docker) or `NEXT_PUBLIC_API_BASE_URL` fallback
+
+In the Docker smoke stack, “mock API” means the Node HTTP server in [`docker-compose.test.yml`](docker-compose.test.yml:24).
+In Docker dev/prod, “real API” means the NestJS app started from [`bootstrap()`](apps/api/src/main.ts:14), and “real vs in-memory” persistence is controlled by `GRIDPILOT_API_PERSISTENCE` in [`AppModule`](apps/api/src/app.module.ts:25).
 
 ---