feat: add test setup with cloud-tasks-emulator

.github/workflows/test.yml

@@ -0,0 +1,57 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      cloud-tasks-emulator:
+        image: ghcr.io/aertje/cloud-tasks-emulator:latest
+        ports:
+          - 8123:8123
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+
+    - name: Install Poetry
+      uses: snok/install-poetry@v1
+      with:
+        version: "1.8.2"
+
+    - name: Install dependencies
+      run: |
+        poetry install --with test
+        poetry install --with dev
+
+    - name: Run linting
+      run: poetry run sh scripts/lint.sh
+
+    - name: Run type checking
+      run: poetry run mypy fastapi_gcp_tasks
+
+    - name: Run tests
+      run: poetry run pytest --cov=fastapi_gcp_tasks --cov-report=xml
+      env:
+        IS_LOCAL: "true"
+        CLOUD_TASKS_EMULATOR_URL: http://localhost:8123
+        TASK_LISTENER_BASE_URL: http://localhost:8000
+        TASK_PROJECT_ID: test-project
+        TASK_LOCATION: us-central1
+        TASK_QUEUE: test-queue
+
+    - name: Upload coverage reports to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        fail_ci_if_error: true

docs/tests.md

@@ -0,0 +1,112 @@
+# Testing Guide
+
+## Prerequisites
+- Python 3.11 or higher
+- Poetry for dependency management
+- cloud-tasks-emulator (install from https://github.com/aertje/cloud-tasks-emulator)
+
+## Environment Variables
+Required environment variables for testing:
+```bash
+# Local development flag
+IS_LOCAL=true
+
+# Task emulator settings
+CLOUD_TASKS_EMULATOR_URL=http://localhost:8123
+TASK_LISTENER_BASE_URL=http://localhost:8000
+
+# Task queue settings
+TASK_PROJECT_ID=test-project
+TASK_LOCATION=us-central1
+TASK_QUEUE=test-queue
+```
+
+## Running Tests
+
+1. Install dependencies:
+```bash
+poetry install --with test
+```
+
+2. Start the cloud-tasks-emulator:
+```bash
+cloud-tasks-emulator
+```
+
+3. Run tests:
+```bash
+# Run all tests
+poetry run pytest
+
+# Run with coverage report
+poetry run pytest --cov=fastapi_gcp_tasks
+
+# Run specific test file
+poetry run pytest tests/test_delayed_route.py
+```
+
+## Test Structure
+
+The test suite is organized into several key areas:
+
+### Core Functionality Tests
+- DelayedRouteBuilder
+  * Basic task creation and execution
+  * Queue auto-creation
+  * Task options (countdown, task_id)
+  * Error handling and validation
+
+- ScheduledRouteBuilder
+  * Basic job creation
+  * Cron schedule validation
+  * Time zone handling
+  * Job updates and uniqueness
+
+### Hook and Dependency Tests
+- Task Hooks
+  * OIDC token hooks
+  * Deadline hooks
+  * Chained hooks
+  * Custom hook creation
+- Dependencies
+  * max_retries functionality
+  * CloudTasksHeaders integration
+  * Error propagation
+
+### Example Implementation Tests
+- Simple Example
+  * Local mode functionality
+  * Task queueing
+  * Environment variable handling
+  * Default settings
+
+- Full Example
+  * Chained hook configuration
+  * Retry mechanisms
+  * Scheduled tasks
+  * Environment-specific behavior
+
+### Environment-Specific Tests
+- Local Development
+  * Emulator integration
+  * Default configurations
+  * Environment variable handling
+
+- Deployed Environment
+  * OIDC token integration
+  * Cloud Scheduler integration
+  * Job scheduling
+  * Production settings
+
+## Contributing Tests
+
+When adding new tests:
+1. Follow existing test patterns
+2. Ensure proper type hints are used
+3. Run formatting and linting:
+```bash
+sh scripts/format.sh
+sh scripts/lint.sh
+```
+4. Add appropriate docstrings for complex test cases
+5. Consider edge cases and error scenarios

pyproject.toml

@@ -19,6 +19,13 @@ mypy = "^1.10.0"
 types-ujson = "^5.10.0.20240515"
 types-protobuf = "^5.26.0.20240422"
 
+[tool.poetry.group.test.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+pytest-cov = "^4.1.0"
+httpx = "^0.26.0"
+pytest-env = "^1.1.0"
+
 [tool.mypy]
 plugins = ["pydantic.mypy"]
 ignore_missing_imports = true

tests/conftest.py

@@ -0,0 +1,41 @@
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+from fastapi_gcp_tasks import DelayedRouteBuilder, ScheduledRouteBuilder
+from fastapi_gcp_tasks.utils import emulator_client, queue_path
+
+
+@pytest.fixture
+def app():
+    """Create a fresh FastAPI application for each test."""
+    return FastAPI()
+
+
+@pytest.fixture
+def delayed_route():
+    """Create a DelayedRouteBuilder configured for testing with emulator."""
+    return DelayedRouteBuilder(
+        client=emulator_client(),
+        base_url="http://localhost:8000",
+        queue_path=queue_path(
+            project="test-project",
+            location="us-central1",
+            queue="test-queue",
+        ),
+    )
+
+
+@pytest.fixture
+def scheduled_route():
+    """Create a ScheduledRouteBuilder configured for testing."""
+    return ScheduledRouteBuilder(
+        base_url="http://localhost:8000",
+        location_path="projects/test-project/locations/us-central1",
+    )
+
+
+@pytest.fixture
+def test_client(app):
+    """Create a TestClient instance for the FastAPI app."""
+    return TestClient(app)