task_sdk_integration_tests.rst

Task SDK Integration Tests

Task SDK Integration Tests are a specialized type of test that verify the integration between the Apache Airflow Task SDK and a running Airflow instance (mainly the execution API server). These tests ensure that the Task SDK can properly communicate with Airflow's execution API server and that the integration between the two works correctly in a realistic environment.

What are Task SDK Integration Tests?

The Task SDK Integration Tests differ from regular unit tests in several key ways:

Purpose & Scope

These tests verify that the Task SDK package can successfully communicate with a complete Airflow environment, mainly the Airflow Execution API server. They test the actual integration points between the SDK and Airflow core, which is also known as Task Execution Interface.

Real Environment Testing

Unlike unit tests that use mocks and stubs, these integration tests spin up actual Airflow services using Docker Compose to create a realistic testing environment that closely mirrors real deployments.

Cross-Package Validation

Since the Task SDK is distributed as a separate Python package (apache-airflow-task-sdk), these tests ensure that the SDK works correctly with different versions of Airflow core and that API compatibility is maintained.

End-to-End Communication

The tests verify complete request/response cycles between the Task SDK API client and Airflow's execution API, including authentication, API versioning, and error handling (some of it is yet to come).

Why Task SDK Integration?

API Compatibility Assurance

The Task SDK communicates with Airflow through well defined APIs for task execution. These tests ensure that changes to either the SDK or Airflow core don't break the interface contract between the two.

Real World Scenario Testing

While unit tests verify individual components work correctly, integration tests validate that the entire system works together as expected in deployment scenarios.

Quicker Interface Issue resolution

These tests catch integration issues early in the development cycle, preventing breaking changes reaching a release.

Version Compatibility Matrix

As both Airflow and the Task SDK evolve, these tests help ensure compatibility across different version combinations (to come soon).

Running Task SDK Integration Tests

There are multiple ways to run Task SDK Integration Tests depending based on your preferences.

Using Breeze

The simplest way to run Task SDK Integration Tests is using Breeze, which provides CI like reproducibility:

# Run all Task SDK integration tests
breeze testing task-sdk-integration-tests

# Run specific test files
breeze testing task-sdk-integration-tests task_sdk_tests/test_task_sdk_health.py

# Run with custom Docker image
DOCKER_IMAGE=my-custom-airflow-imahge:latest breeze testing task-sdk-integration-tests

Running in Your Current Virtual Environment

Since you're already working in the Airflow repository, you can run Task SDK Integration Tests directly:

Run Tests

# Navigate to task-sdk-tests directory and run tests
cd task-sdk-tests/
uv run pytest -s

# Run specific test file
cd task-sdk-tests/
uv run pytest tests/task_sdk_tests/test_task_sdk_health.py -s

# Keep containers running for debugging
cd task-sdk-tests/
SKIP_DOCKER_COMPOSE_DELETION=1 uv run pytest -s

Optional: Set Custom Docker Image

# Use a different Airflow image for testing
cd task-sdk-tests/
DOCKER_IMAGE=my-custom-airflow:latest uv run pytest -s

Debugging Failed Tests

When tests fail, the logs from all running containers are automatically dumped to the console and the Docker Compose deployment is shut down. To debug issues more effectively:

# Run with maximum verbosity
cd task-sdk-tests/
uv run pytest tests/task_sdk_tests/ -vvv -s --tb=long

# Keep containers running for inspection (local environment)
cd task-sdk-tests/
SKIP_DOCKER_COMPOSE_DELETION=1 uv run pytest tests/task_sdk_tests/test_task_sdk_health.py::test_task_sdk_health

# Keep containers running for inspection (using Breeze)
breeze testing task-sdk-integration-tests --skip-docker-compose-deletion

# Inspect container logs (when containers are still running)
cd task-sdk-tests/docker
docker-compose logs airflow-apiserver
docker-compose logs airflow-scheduler
docker-compose logs postgres

# Access running containers for interactive debugging
docker-compose exec airflow-apiserver bash

Tip

Container Cleanup Control: By default, the Docker Compose deployment is deleted after tests complete to keep your system clean. To keep containers running for debugging:

• Local environment: Export SKIP_DOCKER_COMPOSE_DELETION=1 before running tests
• Breeze environment: Use the --skip-docker-compose-deletion flag

Remember to manually clean up containers when done: cd task-sdk-tests/docker && docker-compose down -v

Testing Custom Airflow Images

To test the Task SDK against custom Airflow builds:

# Build your custom Airflow image first
cd /path/to/airflow
docker build -t my-custom-airflow:latest -f Dockerfile .

# Use custom image for integration tests
export DOCKER_IMAGE=my-custom-airflow:latest
cd task-sdk-tests
uv run pytest tests/task_sdk_tests/

Common Issues and Solutions

Port Conflicts

If port 8080 is already in use, change the host port:

export HOST_PORT=localhost:9090
export TASK_SDK_HOST_PORT=localhost:9090

Memory Issues

These tests require sufficient memory for multiple containers. Ensure Docker has at least 4GB RAM allocated.

Files and Directories

The Task SDK Integration Tests are organized as follows:

task-sdk-tests/
├── pyproject.toml                    # Test package configuration and dependencies
├── docker/
│   └── docker-compose.yaml           # Airflow services configuration
└── tests/
    └── task_sdk_tests/
        ├── conftest.py                # Test configuration and setup
        ├── constants.py               # Test constants and configuration
        ├── test_task_sdk_health.py    # Main integration test
        └── __init__.py

Key Files:

• docker-compose.yaml: Defines the complete Airflow environment (postgres, scheduler, api-server)
• test_task_sdk_health.py: Main test that verifies Task SDK can communicate with Airflow API
• conftest.py: Handles Task SDK installation and test environment setup
• constants.py: Configuration constants for Docker images, ports, and API versions

---

For other kinds of tests look at Testing document