Temporal Python Testing

1---2name: temporal-python-testing3description: Test Temporal workflows with pytest, time-skipping, and mocking strategies. Covers unit testing, integration testing, replay testing, and local development setup. Use when implementing Temporal workflow tests or debugging test failures.4---5 6# Temporal Python Testing Strategies7 8Comprehensive testing approaches for Temporal workflows using pytest, progressive disclosure resources for specific testing scenarios.9 10## When to Use This Skill11 12- **Unit testing workflows** - Fast tests with time-skipping13- **Integration testing** - Workflows with mocked activities14- **Replay testing** - Validate determinism against production histories15- **Local development** - Set up Temporal server and pytest16- **CI/CD integration** - Automated testing pipelines17- **Coverage strategies** - Achieve ≥80% test coverage18 19## Testing Philosophy20 21**Recommended Approach** (Source: docs.temporal.io/develop/python/testing-suite):22 23- Write majority as integration tests24- Use pytest with async fixtures25- Time-skipping enables fast feedback (month-long workflows → seconds)26- Mock activities to isolate workflow logic27- Validate determinism with replay testing28 29**Three Test Types**:30 311. **Unit**: Workflows with time-skipping, activities with ActivityEnvironment322. **Integration**: Workers with mocked activities333. **End-to-end**: Full Temporal server with real activities (use sparingly)34 35## Available Resources36 37This skill provides detailed guidance through progressive disclosure. Load specific resources based on your testing needs:38 39### Unit Testing Resources40 41**File**: `resources/unit-testing.md`42**When to load**: Testing individual workflows or activities in isolation43**Contains**:44 45- WorkflowEnvironment with time-skipping46- ActivityEnvironment for activity testing47- Fast execution of long-running workflows48- Manual time advancement patterns49- pytest fixtures and patterns50 51### Integration Testing Resources52 53**File**: `resources/integration-testing.md`54**When to load**: Testing workflows with mocked external dependencies55**Contains**:56 57- Activity mocking strategies58- Error injection patterns59- Multi-activity workflow testing60- Signal and query testing61- Coverage strategies62 63### Replay Testing Resources64 65**File**: `resources/replay-testing.md`66**When to load**: Validating determinism or deploying workflow changes67**Contains**:68 69- Determinism validation70- Production history replay71- CI/CD integration patterns72- Version compatibility testing73 74### Local Development Resources75 76**File**: `resources/local-setup.md`77**When to load**: Setting up development environment78**Contains**:79 80- Docker Compose configuration81- pytest setup and configuration82- Coverage tool integration83- Development workflow84 85## Quick Start Guide86 87### Basic Workflow Test88 89```python90import pytest91from temporalio.testing import WorkflowEnvironment92from temporalio.worker import Worker93 94@pytest.fixture95async def workflow_env():96    env = await WorkflowEnvironment.start_time_skipping()97    yield env98    await env.shutdown()99 100@pytest.mark.asyncio101async def test_workflow(workflow_env):102    async with Worker(103        workflow_env.client,104        task_queue="test-queue",105        workflows=[YourWorkflow],106        activities=[your_activity],107    ):108        result = await workflow_env.client.execute_workflow(109            YourWorkflow.run,110            args,111            id="test-wf-id",112            task_queue="test-queue",113        )114        assert result == expected115```116 117### Basic Activity Test118 119```python120from temporalio.testing import ActivityEnvironment121 122async def test_activity():123    env = ActivityEnvironment()124    result = await env.run(your_activity, "test-input")125    assert result == expected_output126```127 128## Coverage Targets129 130**Recommended Coverage** (Source: docs.temporal.io best practices):131 132- **Workflows**: ≥80% logic coverage133- **Activities**: ≥80% logic coverage134- **Integration**: Critical paths with mocked activities135- **Replay**: All workflow versions before deployment136 137## Key Testing Principles138 1391. **Time-Skipping** - Month-long workflows test in seconds1402. **Mock Activities** - Isolate workflow logic from external dependencies1413. **Replay Testing** - Validate determinism before deployment1424. **High Coverage** - ≥80% target for production workflows1435. **Fast Feedback** - Unit tests run in milliseconds144 145## How to Use Resources146 147**Load specific resource when needed**:148 149- "Show me unit testing patterns" → Load `resources/unit-testing.md`150- "How do I mock activities?" → Load `resources/integration-testing.md`151- "Setup local Temporal server" → Load `resources/local-setup.md`152- "Validate determinism" → Load `resources/replay-testing.md`153 154## Additional References155 156- Python SDK Testing: docs.temporal.io/develop/python/testing-suite157- Testing Patterns: github.com/temporalio/temporal/blob/main/docs/development/testing.md158- Python Samples: github.com/temporalio/samples-python