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.