Docker Testing Skill
Use this skill whenever you need to run the project’s test suite or
diagnose issues inside Docker containers. It provides a summary of
common commands and troubleshooting steps.
Running the test suite
- Build and start services: Use
docker compose -f docker/docker-compose.yaml up --build to build all images and start the services in development mode.
- Run backend tests: Execute
docker compose -f docker/docker-compose.yaml exec backend python -m pytest to run the backend test suite.
- Run frontend tests: For frontend unit tests, run
docker compose -f docker/docker-compose.yaml exec frontend npm run test or use the appropriate Vitest command.
- Check logs: View logs for all services with
docker compose -f docker/docker-compose.yaml logs -f or for a specific service with docker compose -f docker/docker-compose.yaml logs -f backend or frontend.
- Stop services: Shut down all running containers with
docker compose -f docker/docker-compose.yaml down. Include the -v flag to remove volumes for a clean start.
Troubleshooting tips
- Port conflicts: If services fail to start, check that the default ports (backend 8000, frontend 8080) are free. Modify port mappings in the compose file if necessary.
- Database issues: Ensure that the database service is healthy by running
docker compose -f docker/docker-compose.yaml ps and looking for the “(healthy)” status. Check docker compose -f docker/docker-compose.yaml logs db for errors.
- API connection errors: Test the backend directly with
curl http://localhost:8000/docs to confirm it’s running. Verify the Nginx configuration in client/nginx.conf if the frontend cannot reach /api/* endpoints.
Best practices
- Run tests in a clean environment. Stop containers and remove volumes if you suspect stale state.
- Use relative paths and environment variables. Avoid hard‑coded host dependencies so your setup is portable.
- When debugging, read container logs before rerunning tests. This saves time and surfaces issues like missing migrations or syntax errors.
