Testing
orcher.testing.TestWorkflowEnvironment runs a workflow in memory, with no engine and no worker. Every task the workflow calls is answered by a mock you set up by task name, the environment records the calls, and ctx.sleep() moves a test clock instead of waiting.
The examples use pytest with pytest-asyncio.
The workflow under test
1@workflow(name="process-order")2async def process_order(ctx: WorkflowContext, order_id: str, amount: int, token: str) -> dict:3 payment = await ctx.execute_task(charge_payment, amount=amount, token=token)4 inventory = await ctx.execute_task(reserve_inventory, order_id=order_id)5 ctx.set_state("status", "paid")67 await ctx.sleep(timedelta(hours=1)) # a cooling-off period8 await ctx.execute_task(send_receipt, order_id=order_id)910 return {11 "order_id": order_id,12 "charge_id": payment["charge_id"],13 "reservation_id": inventory["reservation_id"],14 }1import pytest23from orcher.testing import TestWorkflowEnvironment, TestWorkflowOptions45from orders import process_orderMocking tasks
Mock each task by its registered name. A task the workflow calls without a mock raises ValueError, so a fixture that mocks them all keeps each test short:
1@pytest.fixture2def env() -> TestWorkflowEnvironment:3 env = TestWorkflowEnvironment()4 # Every task the workflow calls needs a mock: an unmocked one raises ValueError.5 env.mock_task("charge-payment").returns({"charge_id": "ch_test"})6 env.mock_task("reserve-inventory").returns({"reservation_id": "res_test"})7 env.mock_task("send-receipt").returns(None)8 return envRunning a workflow
execute_workflow takes the workflow function (or class) and its input, which reaches the workflow as a worker would pass it: a dict is spread into keyword arguments. It returns the workflow's result, or raises what the workflow raised:
1@pytest.mark.asyncio2async def test_completes_the_order(env: TestWorkflowEnvironment) -> None:3 # A dict input is spread into keyword arguments, as a worker does.4 result = await env.execute_workflow(process_order, ORDER)56 assert result == {7 "order_id": "ord_123",8 "charge_id": "ch_test",9 "reservation_id": "res_test",10 }Asserting on task calls
Pass TestWorkflowOptions(workflow_id=...) to refer to the run afterwards. A mock receives the task's keyword arguments as one dict, which is what assert_task_called_with compares:
1@pytest.mark.asyncio2async def test_calls_each_task_once(env: TestWorkflowEnvironment) -> None:3 await env.execute_workflow(4 process_order, ORDER, TestWorkflowOptions(workflow_id="order-test-1")5 )67 env.assert_task_called("charge-payment", times=1)8 # The mock receives the task's keyword arguments as one dict.9 env.assert_task_called_with("charge-payment", {"amount": 9999, "token": "tok_visa"})10 assert env.get_task_call_count("send-receipt") == 111 env.assert_workflow_completed("order-test-1")12 env.assert_state_equals("order-test-1", "status", "paid")The other assertions are assert_task_not_called(name) and assert_workflow_failed(workflow_id); get_execution_trace(workflow_id) returns everything recorded about a run.
Failures
.throws() makes a mocked task raise. The exception reaches the workflow as raised, so a test can also cover a workflow that catches it:
1class CardDeclined(Exception):2 pass345@pytest.mark.asyncio6async def test_a_declined_card_fails_the_order(env: TestWorkflowEnvironment) -> None:7 env.mock_task("charge-payment").throws(CardDeclined("insufficient funds"))89 with pytest.raises(CardDeclined, match="insufficient funds"):10 await env.execute_workflow(process_order, ORDER)1112 env.assert_task_not_called("reserve-inventory")In the environment a mocked task is called once: there are no retries, and a failure is not turned into the TaskError a real worker raises after the retries are used up. A workflow that catches TaskError needs the mock to throw one to take that path.
Other mock strategies
1@pytest.mark.asyncio2async def test_mock_strategies(env: TestWorkflowEnvironment) -> None:3 # Successive calls get successive values (an exception in the list is raised).4 env.mock_task("reserve-inventory").returns_sequence(5 [{"reservation_id": "res_1"}, {"reservation_id": "res_2"}]6 )7 # Compute the result from the input dict.8 env.mock_task("charge-payment").with_fn(9 lambda args: {"charge_id": f"ch_{args['amount']}"}10 )1112 result = await env.execute_workflow(process_order, ORDER)13 assert result["charge_id"] == "ch_9999"14 assert result["reservation_id"] == "res_1"MockTaskBuilder also has returns_once_then(first, rest), throws_once_then(error, value) and the aliases resolves() and rejects().
Time
ctx.sleep() advances the environment's clock by its duration instead of waiting, so a workflow that sleeps for an hour finishes at once:
1@pytest.mark.asyncio2async def test_the_cooling_off_period(env: TestWorkflowEnvironment) -> None:3 started = env.get_current_time()45 await env.execute_workflow(process_order, ORDER)67 # ctx.sleep moved the environment's clock instead of waiting.8 assert env.get_current_time() - started >= timedelta(hours=1)env.advance_time(ms), env.advance_time_to(datetime) and env.set_current_time(datetime) move the clock directly.
What the environment supports
The workflow runs with a test context, not a WorkflowContext, and that context supports only part of the API:
| Supported | Not supported |
|---|---|
execute_task, sleep, set_state, get_state(key) (no default argument), now(), is_replaying, workflow_id, workflow_type | execute, ctx.time, ctx.random, ctx.info, events, child workflows, sessions, restart_fresh, queries and updates |
A workflow that uses the unsupported parts fails in the environment with AttributeError or TypeError. Test those workflows against a real engine instead: the quickstart starts one locally.
Testing task logic
A task is an ordinary function, so test its logic directly. Keep the logic in plain functions and the task a thin wrapper around them, so the tests need no TaskContext:
1def order_total(items: list[dict]) -> int:2 return sum(int(item["price"]) * int(item["quantity"]) for item in items)345@task(name="price-order")6async def price_order(ctx: TaskContext, items: list[dict]) -> int:7 return order_total(items)8910def test_order_total() -> None:11 assert order_total([{"price": 250, "quantity": 2}, {"price": 100, "quantity": 1}]) == 600