🐳 Docker Usage Guide

TestPig now includes a built-in CLI utility that makes running tests in Docker containers seamless. No more unknown values for git information!

Game Changer

The testpig-git-env command automatically detects your CI environment and provides proper git information to Docker containers. It's included with any TestPig reporter!

Quick Start

If you have any TestPig reporter installed, you automatically get the testpig-git-env command:

# Replace your docker run command:
docker run --rm my-test-image

# With this:
docker run --rm $(npx testpig-git-env) my-test-image

That's it! TestPig will automatically:

• ✅ Detect your CI environment (GitHub Actions, GitLab CI, etc.)
• ✅ Fall back to local git commands when not in CI
• ✅ Work on Windows, macOS, and Linux
• ✅ Provide consistent git information to your tests

Choose Your Workflow

TestPig's testpig-git-env supports multiple workflows to fit your needs:

Use Case	Format	Command Example
Docker Run	docker (default)	docker run --rm $(npx testpig-git-env) my-image
Docker Compose	env	npx testpig-git-env --format=env > .env && docker compose --env-file .env run tests
Shell Export	export	eval "$(npx testpig-git-env --format=export)" && docker compose run tests
Debugging	json	npx testpig-git-env --format=json --verbose

Pick What Works for You

• Docker Run: Use the default format
• Docker Compose: Use --format=env for environment files or --format=export for shell variables
• CI/CD: Any format works - choose based on your pipeline setup

How It Works

The testpig-git-env utility:

1. Detects CI Environment: Automatically recognizes GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis CI, and more
2. Extracts Git Information: Gets branch, commit, author, and email from CI variables or git commands
3. Outputs Docker Flags: Provides properly formatted -e flags for Docker

Example Output

$ npx testpig-git-env
-e TESTPIG_GIT_BRANCH="main" -e TESTPIG_GIT_COMMIT="abc123..." -e TESTPIG_GIT_AUTHOR="John Doe" -e TESTPIG_GIT_EMAIL="[email protected]" -e TESTPIG_CI_PROVIDER="github"

Output Formats

The CLI supports multiple output formats for different use cases:

# Docker flags (default)
npx testpig-git-env
# Output: -e TESTPIG_GIT_BRANCH="main" -e TESTPIG_GIT_COMMIT="abc123..."

# Environment file format
npx testpig-git-env --format=env
# Output: TESTPIG_GIT_BRANCH=main
#         TESTPIG_GIT_COMMIT=abc123...

# Shell export format
npx testpig-git-env --format=export
# Output: export TESTPIG_GIT_BRANCH="main"
#         export TESTPIG_GIT_COMMIT="abc123..."

# JSON format
npx testpig-git-env --format=json
# Output: {"branch": "main", "commit": "abc123..."}

Usage Examples by Format

Docker Run (Default Format)

Perfect for docker run commands:

# macOS/Linux
docker run --rm $(npx testpig-git-env) my-test-image

# Windows PowerShell
$env_vars = npx testpig-git-env
docker run --rm $env_vars my-test-image

# Windows Command Prompt
for /f "delims=" %i in ('npx testpig-git-env') do docker run --rm %i my-test-image

Docker Compose Workflows

Environment File Approach

# Step 1: Generate environment file
npx testpig-git-env --format=env > .testpig.env

# Step 2: Use with any Docker Compose command
docker compose --env-file .testpig.env run tests
docker compose --env-file .testpig.env up cypress

Shell Export Approach

# Export to current shell and run
eval "$(npx testpig-git-env --format=export)" && docker compose run tests

# Or export once, run multiple times
eval "$(npx testpig-git-env --format=export)"
docker compose run unit-tests
docker compose run integration-tests

Local Development Examples

Choose the method that fits your workflow:

CI/CD Examples

GitHub Actions

name: Test
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          
      - name: Install dependencies
        run: npm ci
        
      - name: Run tests in Docker
        run: |
          docker run --rm $(npx testpig-git-env) my-test-image

GitLab CI

test:
  image: docker:latest
  services:
    - docker:dind
  before_script:
    - apk add --no-cache nodejs npm
    - npm ci
  script:
    - docker run --rm $(npx testpig-git-env) my-test-image

CircleCI

version: 2.1
jobs:
  test:
    docker:
      - image: cimg/node:18
    steps:
      - checkout
      - setup_remote_docker
      - run:
          name: Install dependencies
          command: npm ci
      - run:
          name: Run Docker tests
          command: docker run --rm $(npx testpig-git-env) my-test-image

Docker Compose

With Docker Compose, you have multiple convenient options:

Method 1: Environment File (Recommended 👍)

Generate an environment file and use it with Docker Compose:

# Generate environment file
npx testpig-git-env --format=env > .testpig.env

# Use with Docker Compose
docker compose --env-file .testpig.env run tests

# docker-compose.yml
version: '3.8'
services:
  tests:
    image: my-test-image
    environment:
      # These will be automatically loaded from .testpig.env
      - TESTPIG_GIT_BRANCH
      - TESTPIG_GIT_COMMIT
      - TESTPIG_GIT_AUTHOR
      - TESTPIG_GIT_EMAIL
      - TESTPIG_CI_PROVIDER

Method 2: Shell Export

Export variables to your shell environment:

# Export variables to current shell
eval "$(npx testpig-git-env --format=export)"

# Now run Docker Compose (variables are available)
docker compose up tests

# docker-compose.yml
version: '3.8'
services:
  tests:
    image: my-test-image
    environment:
      # These will be picked up from the shell environment
      - TESTPIG_GIT_BRANCH=${TESTPIG_GIT_BRANCH}
      - TESTPIG_GIT_COMMIT=${TESTPIG_GIT_COMMIT}
      - TESTPIG_GIT_AUTHOR=${TESTPIG_GIT_AUTHOR}
      - TESTPIG_GIT_EMAIL=${TESTPIG_GIT_EMAIL}
      - TESTPIG_CI_PROVIDER=${TESTPIG_CI_PROVIDER}

Method 3: One-liner Shell Export

# Generate and apply environment variables in one command
eval "$(npx testpig-git-env --format=export)" && docker compose run tests

Method 4: Manual Override (When Needed)

Only specify environment variables if you want to override the automatic detection:

# Generate base environment file
npx testpig-git-env --format=env > .testpig.env

# Add custom overrides to the file
echo "TESTPIG_GIT_AUTHOR=Release Bot" >> .testpig.env

# Use with Docker Compose
docker compose --env-file .testpig.env run tests

Advanced Usage

Debug Mode

See exactly what's being detected:

# Debug with JSON output
npx testpig-git-env --verbose --json

# Debug with any format
npx testpig-git-env --verbose --format=env

Example debug output:

{
  "branch": "feature/docker-support",
  "commit": "abc123def456789...",
  "author": "John Doe",
  "email": "[email protected]",
  "provider": "github",
  "isCI": true
}

CLI Options

The testpig-git-env command supports these options:

Option	Description	Example
--format=FORMAT	Output format: docker, env, export, json	--format=env
--json	JSON output (shorthand for --format=json)	--json
--verbose	Show debug information	--verbose
--help	Show help message	--help

Manual Overrides

The testpig-git-env utility automatically detects git information, but you can override specific values when needed:

# Override just the branch (other values auto-detected)
export TESTPIG_GIT_BRANCH="custom-branch"
docker run --rm $(npx testpig-git-env) my-test-image

# Override multiple values (remaining values auto-detected)
export TESTPIG_GIT_BRANCH="hotfix"
export TESTPIG_GIT_AUTHOR="Release Bot"
docker run --rm $(npx testpig-git-env) my-test-image

Automatic + Override

You only need to set environment variables for values you want to override. All other git information will be automatically detected and provided by testpig-git-env.

Available Override Variables

Variable	Description	Example
TESTPIG_GIT_BRANCH	Git branch name	main, feature/auth
TESTPIG_GIT_COMMIT	Full commit SHA	abc123def456789...
TESTPIG_GIT_AUTHOR	Author name	John Doe
TESTPIG_GIT_EMAIL	Author email	[email protected]
TESTPIG_CI_PROVIDER	CI provider name	github, gitlab, local

Supported CI Providers

The utility automatically detects these CI environments:

• GitHub Actions (GITHUB_ACTIONS, GITHUB_RUN_ID)
• GitLab CI (GITLAB_CI, CI_PIPELINE_ID)
• CircleCI (CIRCLECI, CIRCLE_WORKFLOW_ID)
• Jenkins (JENKINS_URL, BUILD_NUMBER)
• Travis CI (TRAVIS, TRAVIS_JOB_ID)
• Generic CI (CI=true, CONTINUOUS_INTEGRATION=true)

Troubleshooting

Issue: Command not found

npx testpig-git-env
# Error: command not found

Solution: Make sure you have a TestPig reporter installed:

npm install @testpig/jest-reporter
# or
npm install @testpig/cypress-reporter
# or any other @testpig/* package

Issue: Permission denied on Windows

# Use PowerShell instead of CMD
$env_vars = npx testpig-git-env
docker run --rm $env_vars my-test-image

Issue: Git commands fail in container

The utility detects git information on the host machine, not inside the container. This is intentional and correct behavior.

Issue: All values show as "unknown"

Enable debug mode to see what's happening:

npx testpig-git-env --verbose --json

Common causes:

• Not in a git repository
• Git not installed on host
• CI environment variables not set properly

Issue: Environment file not working with Docker Compose

# Check the generated environment file
cat .testpig.env

# Verify Docker Compose can read it
docker compose --env-file .testpig.env config

Issue: Shell export not persisting

# Make sure to use eval with quotes
eval "$(npx testpig-git-env --format=export)"

# Verify variables are set
echo $TESTPIG_GIT_BRANCH

Best Practices

1. Use in npm scripts

{
  "scripts": {
    "test:docker": "docker run --rm $(npx testpig-git-env) my-test-image",
    "test:docker:debug": "npx testpig-git-env --verbose && npm run test:docker",
    "test:compose": "npx testpig-git-env --format=env > .testpig.env && docker compose --env-file .testpig.env run tests",
    "test:compose:export": "eval \"$(npx testpig-git-env --format=export)\" && docker compose run tests"
  }
}

2. Create shell aliases

# Add to your .bashrc or .zshrc
alias docker-test='docker run --rm $(npx testpig-git-env)'
alias compose-test='eval "$(npx testpig-git-env --format=export)" && docker compose run tests'

# Usage:
docker-test my-test-image
compose-test

3. Environment file workflow

# Create a reusable environment file
npx testpig-git-env --format=env > .testpig.env

# Add to .gitignore (contains current git state)
echo ".testpig.env" >> .gitignore

# Use across multiple compose commands
docker compose --env-file .testpig.env run tests
docker compose --env-file .testpig.env run integration-tests

4. CI Pipeline Templates

Create reusable CI templates with TestPig Docker support built-in.

Migration Guide

Before (manual environment variables)

docker run --rm \
  -e GIT_BRANCH="$(git rev-parse --abbrev-ref HEAD)" \
  -e GIT_COMMIT="$(git rev-parse HEAD)" \
  -e GIT_AUTHOR="$(git config user.name)" \
  my-test-image

After (automatic detection)

docker run --rm $(npx testpig-git-env) my-test-image

The new approach:

• ✅ Works across all supported CI providers (GitHub, GitLab, Jenkins, Travis, CircleCI - More coming soon!)
• ✅ Handles edge cases (PRs, detached HEAD, etc.)
• ✅ Provides consistent variable names
• ✅ Includes debug and override capabilities
• ✅ Works on all platforms

Framework-Specific Examples

For specific examples with your testing framework, see:

• Jest with Docker
• Cypress with Docker
• Mocha with Docker
• Playwright with Docker
• WebdriverIO with Docker
• Vitest with Docker

Getting Help

If you encounter issues with Docker usage:

• Check the Node Reporters GitHub repository for Docker-specific issues
• Visit support.testpig.io for all bugs, feature requests, account or technical issues

Ready to run your tests in Docker with proper git information? Let's go! 🚀