Add Docker-based test infrastructure for e2e tests

Add Docker test infrastructure to catch container-specific issues like #406
where filesystem-based agents may silently fail in Docker environments.

Changes:
- Add Dockerfile.test: Python 3.12 image with Claude Code CLI installed
- Add scripts/test-docker.sh: Local script to run tests in Docker
- Add test-e2e-docker job to CI workflow
- Add .dockerignore to speed up Docker builds

Usage:
  ./scripts/test-docker.sh unit    # Run unit tests in Docker
  ./scripts/test-docker.sh e2e     # Run e2e tests (needs ANTHROPIC_API_KEY)
  ./scripts/test-docker.sh all     # Run all tests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ashwin-ant

.dockerignore

@@ -0,0 +1,49 @@
+# Git
+.git
+.gitignore
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing/Coverage
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+
+# Misc
+*.log
+.DS_Store

.github/workflows/test.yml

@@ -81,6 +81,24 @@ jobs:
         run: |
           python -m pytest e2e-tests/ -v -m e2e
 
+  test-e2e-docker:
+    runs-on: ubuntu-latest
+    needs: test # Run after unit tests pass
+    # Run e2e tests in Docker to catch container-specific issues like #406
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker test image
+        run: docker build -f Dockerfile.test -t claude-sdk-test .
+
+      - name: Run e2e tests in Docker
+        env:
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          docker run --rm -e ANTHROPIC_API_KEY \
+            claude-sdk-test python -m pytest e2e-tests/ -v -m e2e
+
   test-examples:
     runs-on: ubuntu-latest
     needs: test-e2e # Run after e2e tests

Dockerfile.test

@@ -0,0 +1,29 @@
+# Dockerfile for running SDK tests in a containerized environment
+# This helps catch Docker-specific issues like #406
+
+FROM python:3.12-slim
+
+# Install dependencies for Claude CLI and git (needed for some tests)
+RUN apt-get update && apt-get install -y \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Claude Code CLI
+RUN curl -fsSL https://claude.ai/install.sh | bash
+ENV PATH="/root/.local/bin:$PATH"
+
+# Set up working directory
+WORKDIR /app
+
+# Copy the SDK source
+COPY . .
+
+# Install SDK with dev dependencies
+RUN pip install -e ".[dev]"
+
+# Verify CLI installation
+RUN claude -v
+
+# Default: run unit tests
+CMD ["python", "-m", "pytest", "tests/", "-v"]

scripts/test-docker.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# Run SDK tests in a Docker container
+# This helps catch Docker-specific issues like #406
+#
+# Usage:
+#   ./scripts/test-docker.sh [unit|e2e|all]
+#
+# Examples:
+#   ./scripts/test-docker.sh unit                    # Run unit tests only
+#   ANTHROPIC_API_KEY=sk-... ./scripts/test-docker.sh e2e   # Run e2e tests
+#   ANTHROPIC_API_KEY=sk-... ./scripts/test-docker.sh all   # Run all tests
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
+
+cd "$PROJECT_DIR"
+
+usage() {
+    echo "Usage: $0 [unit|e2e|all]"
+    echo ""
+    echo "Commands:"
+    echo "  unit  - Run unit tests only (no API key needed)"
+    echo "  e2e   - Run e2e tests (requires ANTHROPIC_API_KEY)"
+    echo "  all   - Run both unit and e2e tests"
+    echo ""
+    echo "Examples:"
+    echo "  $0 unit"
+    echo "  ANTHROPIC_API_KEY=sk-... $0 e2e"
+    exit 1
+}
+
+echo "Building Docker test image..."
+docker build -f Dockerfile.test -t claude-sdk-test .
+
+case "${1:-unit}" in
+    unit)
+        echo ""
+        echo "Running unit tests in Docker..."
+        docker run --rm claude-sdk-test \
+            python -m pytest tests/ -v
+        ;;
+    e2e)
+        if [ -z "$ANTHROPIC_API_KEY" ]; then
+            echo "Error: ANTHROPIC_API_KEY environment variable is required for e2e tests"
+            echo ""
+            echo "Usage: ANTHROPIC_API_KEY=sk-... $0 e2e"
+            exit 1
+        fi
+        echo ""
+        echo "Running e2e tests in Docker..."
+        docker run --rm -e ANTHROPIC_API_KEY \
+            claude-sdk-test python -m pytest e2e-tests/ -v -m e2e
+        ;;
+    all)
+        echo ""
+        echo "Running unit tests in Docker..."
+        docker run --rm claude-sdk-test \
+            python -m pytest tests/ -v
+
+        echo ""
+        if [ -n "$ANTHROPIC_API_KEY" ]; then
+            echo "Running e2e tests in Docker..."
+            docker run --rm -e ANTHROPIC_API_KEY \
+                claude-sdk-test python -m pytest e2e-tests/ -v -m e2e
+        else
+            echo "Skipping e2e tests (ANTHROPIC_API_KEY not set)"
+        fi
+        ;;
+    *)
+        usage
+        ;;
+esac
+
+echo ""
+echo "Done!"