docker-smoke-test

Docker Smoke Test

Automatically build Docker image, run smoke tests via docker-compose, and verify changes are working correctly. Supports any Docker project with auto-detection.

Configuration

Auto-Detection

The skill automatically detects:

• Project Directory: Current directory or parent with docker-compose.yml
• Container Name: From docker-compose.yml (first service) or --container flag
• Port: From docker-compose.yml exposed ports or --port flag
• Credentials: From .env file (AUTH_PASSWORD, DB_PASSWORD, etc.)

Manual Override

# Override specific values
--container my-app
--port 3000
--project-dir /path/to/project
--env-key PASSWORD

Workflow

1. Find Project Directory

# Find docker-compose.yml in current or parent directory
find . -maxdepth 3 -name "docker-compose.yml" -o -name "docker-compose.yaml" 2>/dev/null | head -1

2. Build Docker Image

cd <PROJECT_DIR> && docker compose build --no-cache

Check for build errors. Report success or failure immediately.

3. Start Container

cd <PROJECT_DIR> && docker compose up -d && sleep 8

Wait for container to be ready.

4. Get Container Info

# Get container IP
docker inspect <CONTAINER> --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}'

# Get exposed port from compose
docker compose port <SERVICE> <EXPOSED_PORT>

5. Run Smoke Tests

Execute these tests in order:

Test 1: Health Check

docker exec <CONTAINER> wget -q --spider -O /dev/null http://127.0.0.1:<PORT>
echo "Health check: $?"

Test 2: Public Endpoint

curl -s http://<CONTAINER_IP>:<PORT>/api/health | grep -q "ok"
echo "Public endpoint: $?"

Test 3: Protected POST - No Auth (Should return 401)

result=$(curl -s -w "%{http_code}" -o /dev/null -X POST http://<CONTAINER_IP>:<PORT>/api/data -H "Content-Type: application/json" -d '{}')
[ "$result" = "401" ]
echo "Protected endpoint (no auth): $?"

Test 4: Test with Credentials (if applicable)

# Login if auth endpoint exists
TOKEN=$(curl -s -X POST http://<CONTAINER_IP>:<PORT>/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"password":"'"${AUTH_PASSWORD:-password}"'"}' \
  -c - | grep auth_token | awk '{print $7}')

# Test protected endpoint with valid token
result=$(curl -s -w "%{http_code}" -o /dev/null -X POST \
  http://<CONTAINER_IP>:<PORT>/api/data \
  -H "Content-Type: application/json" \
  -H "Cookie: auth_token=$TOKEN" \
  -d '{"name":"test"}')
echo "Authenticated request: $result"

6. Cleanup

cd <PROJECT_DIR> && docker compose down

7. Provide Report

Format the report as:

## Docker Smoke Test Results

### Build: ✅ PASS / ❌ FAIL
[summary]

### Container Start: ✅ PASS / ❌ FAIL
[container status]

### Smoke Tests:
| Test | Status |
|------|--------|
| Health Check | ✅/❌ |
| Public Endpoint | ✅/❌ |
| Protected POST (no auth) | ✅/❌ |
| Authenticated Request | ✅/❌ |

## Summary
[overall assessment]

Error Handling

If any step fails:

1. Report the failure immediately with error message
2. Run docker compose down to cleanup
3. Ask user if they want to fix before continuing

Common Issues

Port Not Exposed

If container port is not exposed to host, use:

docker exec <CONTAINER> curl localhost:<INTERNAL_PORT>

Credentials Not Found

If .env doesn't have credentials, prompt user or skip authenticated tests.

Container Name Conflicts

Use full container name:

docker compose ps -q | xargs docker inspect --format '{{.Name}}'

Integration

GitHub Actions

name: Docker Smoke Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Smoke Test
        uses: ./ # or reference your skill