v0.6.0 multi-user game support with longpoll, tests and doc updated

test/README.md

@@ -1,84 +1,146 @@
 # Chess API Test Suite
 
-This directory contains comprehensive test suites for the Chess API server, covering both API functionality and database persistence.
+This directory contains comprehensive test suites for the Chess API server, covering API functionality, database operations, authentication, and real-time updates.
 
 ## Prerequisites
 
 - `jq` - JSON processor
 - `curl` - HTTP client
-- `sqlite3` - SQLite CLI (for database tests only)
-- Compiled `chessd` binary in parent directory
+- `sqlite3` - SQLite CLI (for database tests)
+- `base64` - Base64 encoder (for JWT tests)
+- Compiled `chessd` binary in accessible path
 
-## Test Suites
-
-### 1. API Functionality Tests (`test-api.sh`)
-
-Tests all API endpoints, error handling, rate limiting, and game logic.
-
-**Running the test:**
+## Running the test server
 ```bash
-# Start server in development mode (required for tests to pass)
-../chessd -dev
-
-# In another terminal, run tests
-./test-api.sh
+./run-test-server.sh
 ```
 
-**Coverage:**
-- Game creation and management (HvH, HvC, CvC)
-- Move validation and execution
-- Computer move triggering with "cccc"
-- Undo functionality
-- Player configuration changes
-- Rate limiting (dev mode: 20 req/s)
-- Security hardening and input validation
+Pass binary path as first argument of the script if it's not placed in current directory `./chessd`.
+Server will run with '-dev' option, enabling db WAL mode and relaxing rate limiting.
+Will clean up test database and temporary files, so it's preferred for clean testing.
+Can be used for all the tests.
 
-### 2. Database Persistence Tests (`test-db.sh`)
-**Outdated: test-db.sh and test-db-server.sh currently focus on user operations.**
+### Pre-configured Users
+| Username | Password | Email |
+|----------|----------|-------|
+| alice | AlicePass123 | alice@example.com |
+| bob | BobPass456 | bob@example.com |
+| charlie | CharliePass789 | - |
 
-Tests database storage, async writes, and data integrity.
+### Features
+- Automatically initializes database schema
+- Creates three test users
+- Runs on port 8080 (API) and 9090 (Web UI)
+- Development mode with relaxed rate limits
+- Fixed JWT secret for consistent tokens
+- Graceful shutdown on Ctrl+C
 
-**Running the test:**
+### Manual Testing Examples
 ```bash
-# Terminal 1: Start server with database
-./run-server-with-db.sh ../chessd
+# Login as alice
+curl -X POST http://localhost:8080/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"username":"alice","password":"AlicePass123"}'
 
-# Terminal 2: Run database tests
-./test-db.sh
-
-# When done, press Ctrl+C in Terminal 1
+# Create authenticated game
+TOKEN="<jwt-from-login>"
+curl -X POST http://localhost:8080/games \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"white":{"type":1},"black":{"type":2,"level":10}}'
 ```
 
-**Coverage:**
-- Game and move persistence
-- Async write buffer behavior
-- Multi-game isolation
-- Undo effects on database
-- WAL mode verification
-- Foreign key constraints
+## Test Suite Overview
 
-## Important Notes
+| Test Suite | File | Coverage |
+|------------|------|----------|
+| API Functionality | `test-api.sh` | Game operations, moves, undo, rate limiting |
+| Database & Auth | `test-db.sh` | User registration, login, JWT tokens, persistence |
+| Long-Polling | `test-longpoll.sh` | Real-time updates, wait behavior, timeouts |
+| Test Server | `test-db-server.sh` | Pre-populated test environment |
 
-1. **Development Mode Required**: The server MUST be started with `-dev` flag for tests to pass. This enables:
-    - Relaxed rate limiting (20 req/s instead of 10)
-    - WAL mode for SQLite (better concurrency)
+## 1. API Functionality Tests (`test-api.sh`)
 
-2. **Database Tests**: The `run-server-with-db.sh` script automatically:
-    - Creates a temporary test database
-    - Initializes the schema
-    - Cleans up on exit (Ctrl+C)
+Tests core game mechanics and API endpoints.
 
-3. **Test Isolation**: Each test suite can be run independently. The database tests use a separate `test.db` file that doesn't affect production data.
+### Running the test
+```bash
+# Terminal 1: Start server in development mode
+test/run-test-server.sh ./chessd
+# Direct (no cleanup required): ./chessd -dev
 
-## Troubleshooting
+# Terminal 2: Run API tests
+test/test-api.sh
+```
 
-**Rate limiting failures:** Ensure server is running with `-dev` flag  
-**Database test failures:** Check that no other instance is using `test.db`  
-**Port conflicts:** Default port is 8080, ensure it's available
+### Coverage
+- **Game Creation**: Human vs Human, Human vs Computer, Computer vs Computer
+- **Move Validation**: Legal/illegal moves, UCI notation
+- **Computer Play**: Async engine moves with "cccc" trigger
+- **Undo System**: Single and multiple move reversal
+- **Player Configuration**: Dynamic player type changes
+- **Rate Limiting**: 20 req/s in dev mode
+- **Error Handling**: Invalid inputs, missing games, wrong content-types
+- **Security**: Input validation, FEN injection prevention
 
-## Exit Codes
+## 2. Database & Authentication Tests (`test-db.sh`)
 
-- `0` - All tests passed
-- `1` - One or more tests failed
+Tests user management, authentication, and persistence via API integration.
+**Requires Running Server Script**
 
-Check colored output for detailed pass/fail information for each test case.
+### Running the test
+```bash
+# Terminal 1: Start test server with database
+# Server is running with -dev option (WAL mode db)
+test/test-db-server.sh ./chessd
+
+# Terminal 2: Run API integration tests
+test/test-db.sh ./chessd
+```
+
+### Coverage
+- **User Registration**: Account creation, password hashing
+- **Duplicate Prevention**: Username/email uniqueness
+- **Authentication**: Login with JWT generation
+- **Token Validation**: JWT parsing and claims verification
+- **Password Security**: Argon2id hashing, complexity requirements
+- **Case Sensitivity**: Case-insensitive username/email matching
+- **Database Schema**: Table creation, constraints, indexes
+
+### Test Flow
+1. Creates temporary `test.db` with schema
+2. Registers test users (alice, bob, charlie)
+3. Tests authentication endpoints
+4. Validates JWT tokens and claims
+5. Tests duplicate user prevention
+6. Cleans up test database
+
+## 3. Long-Polling Tests (`test-longpoll.sh`)
+
+Tests real-time game updates via HTTP long-polling.
+
+### Running the test
+```bash
+# Terminal 1: Start server with storage
+test/run-test-server.sh ./chessd
+# Direct (test.db cleanup required): ./chessd -dev -storage-path test.db
+
+# Terminal 2: Run long-polling tests
+test/test-longpoll.sh
+```
+
+### Coverage
+- **Basic Long-Polling**: Wait for game state changes
+- **Multi-Client**: Multiple simultaneous waiters
+- **Timeout Behavior**: 25-second timeout verification
+- **Immediate Response**: No wait when state already changed
+- **Connection Handling**: Client disconnect cleanup
+- **Game Deletion**: Notification on game removal
+- **Move Detection**: Accurate move count tracking
+
+### Test Scenarios
+1. **Single Waiter**: Client waits, receives update after move
+2. **Multiple Waiters**: 3 clients wait, all receive notification
+3. **Timeout**: Verify 25-second timeout with valid response
+4. **Skip Wait**: Immediate return when moveCount outdated
+5. **Disconnection**: Proper cleanup on client disconnect