---
name: docker-testing
description: Guidance for running and debugging tests in Docker environments for FastAPI + Vue/Tailwind projects.
---

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