echoes-of-the-ash/docs/TESTING_GUIDE.md

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:

# 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:

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:

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():

await self.test_my_feature()