Defining Services

Services are Docker containers that Spark starts before your test runs. If your test needs a database, an API server, or any other process — that's a service. Each test gets its own isolated Docker network, so services from different tests never interfere with each other.

services:
  - name: api
    image: myapp:latest
    environment:
      DATABASE_URL: postgres://db:5432/test
    healthcheck:
      test: "curl -f http://localhost:8080/health"
      retries: 30

  - name: db
    image: postgres:15
    environment:
      POSTGRES_DB: test
      POSTGRES_PASSWORD: secret
    healthcheck:
      test: "pg_isready"
      retries: 30

The service name is the hostname. When you set name: api, other services and your test can reach it at http://api:8080. This is how Docker networking works — the name becomes the DNS entry inside the test's network.

Fields

Field	Required	Description
`name`	yes*	Service name and hostname in the Docker network
`image`	yes*	Docker image to run
`ref`	no	Reference to a shared service from config file
`command`	no	Override the image's default command
`workingDir`	no	Working directory inside the container
`environment`	no	Map of environment variables
`healthcheck`	no	Health check configuration
`artifacts`	no	Files or directories to collect from the container after test execution
`containerName`	no	Override the auto-generated container name

* Required when not using ref. See Shared Services for the ref approach.

Command format

The command field supports both string and array formats:

# Parsed with shell-like tokenization
command: "sh -c 'echo hello && sleep 3600'"

# Passed directly to Docker — no shell parsing
command: ["sh", "-c", "echo hello && sleep 3600"]

Artifacts

You can collect files or directories from service containers after the test finishes. This is useful for grabbing database dumps, application logs, exception files, or any other data produced during the test.

services:
  - name: api
    image: myapp:latest
    artifacts:
      - path: /var/log/app/error.log
      - name: app-logs
        path: /var/log/app/

Each artifact entry has:

Field	Required	Description
`path`	yes	Path inside the container (file or directory)
`name`	no	Custom artifact name. Defaults to the filename or last directory component.

Zero overhead during test execution. Files are extracted from containers using Docker's copy API only after the test completes, while containers are still running. Nothing is mounted or copied during the actual test.

When path points to a directory, all files inside are collected recursively. The artifact name becomes a prefix — for example, a directory artifact named app-logs containing error.log and access.log produces artifacts app-logs/error.log and app-logs/access.log.

If a path doesn't exist in the container, it's silently skipped with a warning in the logs. This means you can safely define artifacts for files that are only created on failure.