Temporal Python Testing

1---
2name: temporal-python-testing
3description: 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 Strategies
7 
8Comprehensive testing approaches for Temporal workflows using pytest, progressive disclosure resources for specific testing scenarios.
9 
10## Do not use this skill when
11 
12- The task is unrelated to temporal python testing strategies
13- You need a different domain or tool outside this scope
14 
15## Instructions
16 
17- Clarify goals, constraints, and required inputs.
18- Apply relevant best practices and validate outcomes.
19- Provide actionable steps and verification.
20- If detailed examples are required, open `resources/implementation-playbook.md`.
21 
22## Use this skill when
23 
24- **Unit testing workflows** - Fast tests with time-skipping
25- **Integration testing** - Workflows with mocked activities
26- **Replay testing** - Validate determinism against production histories
27- **Local development** - Set up Temporal server and pytest
28- **CI/CD integration** - Automated testing pipelines
29- **Coverage strategies** - Achieve ≥80% test coverage
30 
31## Testing Philosophy
32 
33**Recommended Approach** (Source: docs.temporal.io/develop/python/testing-suite):
34 
35- Write majority as integration tests
36- Use pytest with async fixtures
37- Time-skipping enables fast feedback (month-long workflows → seconds)
38- Mock activities to isolate workflow logic
39- Validate determinism with replay testing
40 
41**Three Test Types**:
42 
431. **Unit**: Workflows with time-skipping, activities with ActivityEnvironment
442. **Integration**: Workers with mocked activities
453. **End-to-end**: Full Temporal server with real activities (use sparingly)
46 
47## Available Resources
48 
49This skill provides detailed guidance through progressive disclosure. Load specific resources based on your testing needs:
50 
51### Unit Testing Resources
52 
53**File**: `resources/unit-testing.md`
54**When to load**: Testing individual workflows or activities in isolation
55**Contains**:
56 
57- WorkflowEnvironment with time-skipping
58- ActivityEnvironment for activity testing
59- Fast execution of long-running workflows
60- Manual time advancement patterns
61- pytest fixtures and patterns
62 
63### Integration Testing Resources
64 
65**File**: `resources/integration-testing.md`
66**When to load**: Testing workflows with mocked external dependencies
67**Contains**:
68 
69- Activity mocking strategies
70- Error injection patterns
71- Multi-activity workflow testing
72- Signal and query testing
73- Coverage strategies
74 
75### Replay Testing Resources
76 
77**File**: `resources/replay-testing.md`
78**When to load**: Validating determinism or deploying workflow changes
79**Contains**:
80 
81- Determinism validation
82- Production history replay
83- CI/CD integration patterns
84- Version compatibility testing
85 
86### Local Development Resources
87 
88**File**: `resources/local-setup.md`
89**When to load**: Setting up development environment
90**Contains**:
91 
92- Docker Compose configuration
93- pytest setup and configuration
94- Coverage tool integration
95- Development workflow
96 
97## Quick Start Guide
98 
99### Basic Workflow Test
100 
101```python
102import pytest
103from temporalio.testing import WorkflowEnvironment
104from temporalio.worker import Worker
105 
106@pytest.fixture
107async def workflow_env():
108    env = await WorkflowEnvironment.start_time_skipping()
109    yield env
110    await env.shutdown()
111 
112@pytest.mark.asyncio
113async def test_workflow(workflow_env):
114    async with Worker(
115        workflow_env.client,
116        task_queue="test-queue",
117        workflows=[YourWorkflow],
118        activities=[your_activity],
119    ):
120        result = await workflow_env.client.execute_workflow(
121            YourWorkflow.run,
122            args,
123            id="test-wf-id",
124            task_queue="test-queue",
125        )
126        assert result == expected
127```
128 
129### Basic Activity Test
130 
131```python
132from temporalio.testing import ActivityEnvironment
133 
134async def test_activity():
135    env = ActivityEnvironment()
136    result = await env.run(your_activity, "test-input")
137    assert result == expected_output
138```
139 
140## Coverage Targets
141 
142**Recommended Coverage** (Source: docs.temporal.io best practices):
143 
144- **Workflows**: ≥80% logic coverage
145- **Activities**: ≥80% logic coverage
146- **Integration**: Critical paths with mocked activities
147- **Replay**: All workflow versions before deployment
148 
149## Key Testing Principles
150 
1511. **Time-Skipping** - Month-long workflows test in seconds
1522. **Mock Activities** - Isolate workflow logic from external dependencies
1533. **Replay Testing** - Validate determinism before deployment
1544. **High Coverage** - ≥80% target for production workflows
1555. **Fast Feedback** - Unit tests run in milliseconds
156 
157## How to Use Resources
158 
159**Load specific resource when needed**:
160 
161- "Show me unit testing patterns" → Load `resources/unit-testing.md`
162- "How do I mock activities?" → Load `resources/integration-testing.md`
163- "Setup local Temporal server" → Load `resources/local-setup.md`
164- "Validate determinism" → Load `resources/replay-testing.md`
165 
166## Additional References
167 
168- Python SDK Testing: docs.temporal.io/develop/python/testing-suite
169- Testing Patterns: github.com/temporalio/temporal/blob/main/docs/development/testing.md
170- Python Samples: github.com/temporalio/samples-python
171