What a mess

docs/TESTING_GUIDE.md

@@ -0,0 +1,121 @@
+# API Testing Suite
+
+## Comprehensive Test Suite
+
+The API includes a comprehensive test suite that validates all major functionality:
+
+- **System Health**: Health check, image serving
+- **Authentication**: Registration, login, user info
+- **Game State**: Profile, location, inventory, full game state
+- **Gameplay**: Inspection, movement, interactables
+
+### Running Tests from Inside the API Container
+
+The test suite is designed to run **inside the Docker container** to avoid network issues:
+
+```bash
+# Run comprehensive tests
+docker exec echoes_of_the_ashes_api python test_comprehensive.py
+```
+
+### Test Coverage
+
+The suite tests:
+
+1. **Health & Infrastructure**
+   - API health endpoint
+   - Static image file serving
+
+2. **Authentication Flow**
+   - Web user registration
+   - Login with credentials
+   - JWT token authentication
+   - User profile retrieval
+
+3. **Game State**
+   - Player profile (HP, level, stats)
+   - Current location with directions
+   - Inventory management
+   - Complete game state snapshot
+
+4. **Gameplay Mechanics**
+   - Area inspection
+   - Player movement between locations
+   - Interacting with objects (searching, using)
+
+### Test Output
+
+The test suite provides:
+- ✅ Green checkmarks for passing tests
+- ❌ Red X marks for failing tests
+- Detailed error messages
+- Summary statistics with success rate
+- Response samples for debugging
+
+### Expected Result
+
+With all systems working correctly, you should see:
+```
+Total Tests: 12
+Passed: 12
+Failed: 0
+Success Rate: 100.0%
+```
+
+### Setup
+
+The test file `test_comprehensive.py` is **automatically included** in the API container during build. The `httpx` library is also included in `api/requirements.txt`, so no additional setup is needed.
+
+To rebuild the container with the latest tests:
+
+```bash
+docker compose build echoes_of_the_ashes_api
+docker compose up -d echoes_of_the_ashes_api
+```
+
+## Test Data
+
+The tests automatically:
+- Create unique test users (timestamped)
+- Register and login
+- Perform actual game actions
+- Clean up after themselves
+
+No manual test data setup is required.
+
+## Troubleshooting
+
+If tests fail:
+
+1. **Check API is running**: `docker ps` should show `echoes_of_the_ashes_api`
+2. **Check database connection**: View logs with `docker logs echoes_of_the_ashes_api`
+3. **Check game data**: Ensure `gamedata/` directory has `locations.json`, `interactables.json`, `items.json`
+4. **Check images**: Ensure `images/locations/` contains image files
+
+## Adding New Tests
+
+To add new test cases, edit `test_comprehensive.py` and add methods to the `TestRunner` class:
+
+```python
+async def test_my_feature(self):
+    """Test description"""
+    try:
+        response = await self.client.post(
+            f"{BASE_URL}/api/my-endpoint",
+            headers={"Authorization": f"Bearer {self.test_token}"},
+            json={"data": "value"}
+        )
+        
+        if response.status_code == 200:
+            self.log_test("My Feature", True, "Success message")
+        else:
+            self.log_test("My Feature", False, f"Error: {response.text}")
+    except Exception as e:
+        self.log_test("My Feature", False, f"Error: {str(e)}")
+```
+
+Then add it to `run_all_tests()`:
+
+```python
+await self.test_my_feature()
+```