Przejdź do treści
Biblioteka skilli
DevOps i chmura · Testowanie

docker-compose-tests

/docker-compose-tests

Tworzy compose.test.yaml dla testów: deklaruje testowany system z prawdziwymi usługami zaplecza, ustawia start po healthcheckach, izoluje równoległe joby CI przez --project-name i deterministycznie zdejmuje stos.

Repozytorium
qa ↗
Licencja
MIT
Ostatnia zmiana repozytorium
20.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
8
Przestarzałość

Brak sygnałów. Repozytorium zmienione 20.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Tworzy compose.test.yaml dla testów: deklaruje testowany system z prawdziwymi usługami zaplecza, ustawia start po healthcheckach, izoluje równoległe joby CI przez --project-name i deterministycznie zdejmuje stos.

Oryginalny opis (EN)

Authors a `compose.test.yaml` for tests - declares the SUT plus its real backing services as one declarative topology, wires healthcheck-driven `depends_on: condition: service_healthy` start ordering, isolates parallel CI jobs via per-job `--project-name`, gates the test step on `--wait` / `--wait-timeout` / `--exit-code-from`, and tears the stack down deterministically with `down --volumes --remove-orphans`. Use when the test environment is multi-service (app + db + cache + queue) and the topology is best expressed in YAML rather than imperative test code.

Jak działa

  1. Step 1 - Author compose.test.yaml
  2. Step 2 - Healthchecks are load-bearing
  3. Step 3 - Migrations as one-shot dependencies
  4. Step 4 - Per-job isolation in CI
  5. Step 5 - Gate the test step on readiness
  6. Step 6 - Tear down deterministically
  7. Step 7 - Profiles for selective enablement
  8. Anti-patterns
  9. Limitations
  10. References
Sekcje z nagłówków SKILL.md, w oryginale · 306 linii, 1 234 słów
Podgląd SKILL.md
---
name: docker-compose-tests
description: "Authors a `compose.test.yaml` for tests - declares the SUT plus its real backing services as one declarative topology, wires healthcheck-driven `depends_on: condition: service_healthy` start ordering, isolates parallel CI jobs via per-job `--project-name`, gates the test step on `--wait` / `--wait-timeout` / `--exit-code-from`, and tears the stack down deterministically with `down --volumes --remove-orphans`. Use when the test environment is multi-service (app + db + cache + queue) and the topology is best expressed in YAML rather than imperative test code."
---

# docker-compose-tests

Reach for Compose in tests when the SUT has two or more real backing
services that must see each other (app -> db -> cache -> queue), the
same topology must run locally and in CI without imperative drift, or
parallel CI jobs each need an isolated stack. For a single dependency
wired into one test, `testcontainers` is lighter - it lives inside the
test process with no separate `docker compose up` step.

[compose]: https://docs.docker.com/compose/

## Step 1 - Author `compose.test.yaml`

Compose's default file lookup is `compose.yaml` or `docker-compose.yaml`
in the working directory or any parent ([compose-cli][cli]); using
the explicit `compose.test.yaml` filename + `-f` flag keeps test
topology separate from local-dev topology.

[cli]: https://docs.docker.com/reference/cli/docker/compose/

```yaml
# compose.test.yaml
name: orders-tests

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: ${PG_PASSWORD:?set PG_PASSWORD}
      POSTGRES_DB: orders_test
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d orders_test"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 5s

  cache:
    image: redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 2s
      timeout: 3s
      retries: 30

  app:
    build:
      context: .
      target: test
    environment:
      DATABASE_URL: postgres://postgres:${PG_PASSWORD}@db:5432/orders_test
      REDIS_URL: redis://cache:6379/0
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 2s
      timeout: 3s
      retries: 30
      start_period: 10s

  e2e:
    image: mcr.microsoft.com/playwright:v1.50.0-noble
    working_dir: /work
    volumes:
      - .:/work
    environment:
      BASE_URL: http://app:3000
    depends_on:
      app:
        condition: service_healthy
    command: npx playwright test
```

The `name:` top-level key sets the project name (which Compose
normally derives from the working directory) - important for CI
isolation, see Step 4.

Even a throwaway test database gets its password from the environment
(a CI secret, or a git-ignored `.env` locally), never a literal in the
compose file. Per [Compose interpolation][compose-interp], `${VAR}` is read
from the shell or `.env`, and `${VAR:?error}` stops Compose when it is unset.

[compose-interp]: https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/

## Step 2 - Healthchecks are load-bearing

**`service_started` (the `depends_on` default) is almost never what a
test wants.** Postgres "started" doesn't mean "accepting connections".
Always pair a real dependency with a `healthcheck` and gate its
dependents with `condition: service_healthy`. The three `depends_on`
conditions are tabulated in [references/compose-flags.md](references/compose-flags.md).

The `healthcheck` syntax per [compose-services][compose-svc]:

[compose-svc]: https://docs.docker.com/reference/compose-file/services/

```yaml
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost"]
  interval: 1m30s
  timeout: 10s
  retries: 3
  start_period: 40s
```

For tests, use **shorter** intervals (2s vs the 1m30s default) and
**more retries** so the gate trips quickly when the service is up
but waits long enough for cold starts.

## Step 3 - Migrations as one-shot dependencies

Database migrations belong in their own service that the app
`depends_on` with `service_completed_successfully`:

```yaml
services:
  db:
    image: postgres:15
    healthcheck: { test: ["CMD-SHELL", "pg_isready"], interval: 2s, retries: 30 }

  migrate:
    image: orders-app:test
    command: npm run db:migrate
    depends_on:
      db:
        condition: service_healthy
    environment:
      DATABASE_URL: postgres://postgres:${PG_PASSWORD}@db:5432/orders_test

  app:
    image: orders-app:test
    depends_on:
      db: { condition: service_healthy }
      migrate: { condition: service_completed_successfully }
    environment:
      DATABASE_URL: postgres://postgres:${PG_PASSWORD}@db:5432/orders_test
```

The chain - db healthy → migrate runs → migrate exits 0 → app starts - 
ensures the app never connects to an unmigrated database.

## Step 4 - Per-job isolation in CI

Per [compose-cli][cli], the project name controls the namespace of
**every** resource Compose creates (containers, networks, volumes).
Two parallel jobs that use the same project name fight each other.

Set the project name from a unique-per-job value:

```yaml
# .github/workflows/integration.yml
jobs:
  e2e:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        shard: [1, 2, 3, 4]
    env:
      COMPOSE_PROJECT_NAME: orders-${{ github.run_id }}-${{ matrix.shard }}
    steps:
      - uses: actions/checkout@v5
      - name: Compose up
        run: docker compose -f compose.test.yaml up --build --wait --wait-timeout 180
      - name: Run tests
        run: docker compose -f compose.test.yaml run --rm e2e
      - name: Compose down
        if: always()
        run: docker compose -f compose.test.yaml down --volumes --remove-orphans
```

The `-p` / `--project-name` resolution order is:
**flag > `COMPOSE_PROJECT_NAME` env var > top-level `name:` > directory
basename**. Using the env var keeps the YAML clean while overriding
the in-file `name:` per CI job.

> "Project names must contain only lowercase letters, decimal digits,
> dashes, and underscores, and must begin with a lowercase letter or
> decimal digit." ([compose-cli][cli])

## Step 5 - Gate the test step on readiness

Two `up` flags pair for "block until everything is healthy": `--wait`
("Wait for services to be running|healthy. Implies detached mode.")
and `--wait-timeout <seconds>` ("Maximum duration in seconds to wait
for the project to be running|healthy") ([compose-up][up]). The full
flag table (`--abort-on-container-exit`, `--abort-on-container-failure`,
`--exit-code-from`) is in [references/compose-flags.md](references/compose-flags.md).

[up]: https://docs.docker.com/reference/cli/docker/compose/up/

Two valid CI shapes:

### Shape A - `up --wait` then `run` the test service

```bash
docker compose -f compose.test.yaml up --build --wait --wait-timeout 180
docker compose -f compose.test.yaml run --rm e2e
EXIT=$?
docker compose -f compose.test.yaml down --volumes --remove-orphans
exit $EXIT
```

The `up --wait` step blocks until every service is healthy or the
180s budget elapses. The `run` step executes the test container; its
exit code is the build verdict.

### Shape B - `up --abort-on-container-exit --exit-code-from <test-service>`

```bash
docker compose -f compose.test.yaml up \
  --build \
  --abort-on-container-exit \
  --exit-code-from e2e
```

Compose returns the test container's exit code as its own. Cleaner
when the test runs as a Compose service rather than via `run`.

## Step 6 - Tear down deterministically

`down` stops and removes containers and networks ([compose-cli][cli]).
Two flags matter for tests: `--volumes` / `-v` (remove named volumes,
else DB state persists across runs and the next run sees stale data)
and `--remove-orphans` (remove containers for services no longer in the
file). The full table is in [references/compose-flags.md](references/compose-flags.md).

```bash
docker compose -f compose.test.yaml down --volumes --remove-orphans
```

Always run `down` in an `if: always()` step (GitHub Actions) or
trap-on-EXIT (shell) - leaked containers consume CI runner disk and
poison the next run.

## Step 7 - Profiles for selective enablement

When the test compose file has services that aren't always needed
(seeded fixtures, a debugging admin UI, a heavyweight observability
stack), gate them behind a profile:

```yaml
services:
  db: { image: postgres:15, healthcheck: { ... } }

  pgadmin:
    image: dpage/pgadmin4
    profiles: [debug]
    ports: ["5050:80"]
    depends_on: { db: { condition: service_healthy } }
```

Run with the profile when needed:

```bash
docker compose -f compose.test.yaml --profile debug up
# or via env:
COMPOSE_PROFILES=debug docker compose -f compose.test.yaml up
```

Per [compose-cli][cli]: "Specify a profile to enable" - multiple
profiles via repeating `--profile` or comma-separated
`COMPOSE_PROFILES`.

## Anti-patterns

Common failure modes and their fixes - missing `service_healthy` gates,
shared project names across parallel jobs, `down` without `--volumes`,
foreground `up` without `--abort-on-container-exit`, migrations in the
app entrypoint, host bind mounts in CI, reusing the dev compose file,
and hard-coded host ports - are cataloged in
[references/anti-patterns.md](references/anti-patterns.md).

## Limitations

- **Compose is not a scheduler.** It runs on one Docker daemon. For
  multi-host or k8s-shaped tests, use the orchestrator's native test
  primitive (kind, k3d, helm test) instead.
- **No native parallelism within one project.** Compose runs services
  in topological order; "parallel" tests come from running multiple
  Compose projects per CI matrix shard.
- **Healthcheck images need the probe binary.** Minimal/distroless
  images often don't ship `curl` / `pg_isready` - either switch to a
  slim variant or use a TCP probe via `nc` / `wget`.
- **Per-test reset is coarse.** The Compose stack is per-suite; for
  per-test DB reset, layer a snapshot/restore step on
  top.

## References

- [compose-overview][compose] - overview, "tool for defining and
  running multi-container applications".
- [compose-cli][cli] - `docker compose` subcommand list, `-f`,
  `--project-name`, `--profile`, project-name resolution rules.
- [compose-up][up] - `up` flags: `--wait`, `--wait-timeout`,
  `--abort-on-container-exit`, `--exit-code-from`, `--build`.
- [compose-svc][compose-svc] - `services` schema: `healthcheck`,
  `depends_on` conditions (`service_started` / `service_healthy` /
  `service_completed_successfully`).
- `testcontainers` - alternative when
  the topology is one container per test, expressed in test code.
Pliki w paczce (4)
  • SKILL.md 10 KB
  • .tessl-plugin/plugin.json 1 KB
  • references/anti-patterns.md 3 KB
  • references/compose-flags.md 2 KB

Wersje

W bazie nie ma innych skilli o nazwie docker-compose-tests.

Migawka bazy z 13.11.2026 · wersja paczki 6c426bc322e4 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100docker-compose-healthcheck-injector
    Dopilnowuje, by każda usługa w pliku Docker Compose miała blok healthcheck, a depends_on używało warunku service_healthy, przy generowaniu i edycji compose.yaml.
  • 90docker-compose-helper
    Tworzy i naprawia pliki Docker Compose: zależności usług, healthchecki, porty, wolumeny, sieci i zmienne środowiskowe.
  • 100docker-compose
    Prowadzi przez orkiestrację aplikacji wielokontenerowych w jednym compose.yaml: usługi, sieci, wolumeny, porty, env_file, depends_on z healthcheckami, profile i limity zasobów w Docker Compose v5.6.1.
  • 100docker-compose-basics
    Pomaga definiować i uruchamiać aplikacje wielokontenerowe w Docker Compose za pomocą konfiguracji YAML.
  • 100docker-compose
    Konfiguruje Docker Compose dla aplikacji wielokontenerowych: usługi, sieci i wolumeny, zależności usług oraz lokalne środowiska deweloperskie.
  • 100generating-docker-compose-files
    Generuje pliki Docker Compose dla aplikacji wielokontenerowych.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.