Reference

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")
2
async 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")
6
7
await ctx.sleep(timedelta(hours=1)) # a cooling-off period
8
await ctx.execute_task(send_receipt, order_id=order_id)
9
10
return {
11
"order_id": order_id,
12
"charge_id": payment["charge_id"],
13
"reservation_id": inventory["reservation_id"],
14
}
1
import pytest
2
3
from orcher.testing import TestWorkflowEnvironment, TestWorkflowOptions
4
5
from orders import process_order

Mocking 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.fixture
2
def 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 env

Running 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.asyncio
2
async 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)
5
6
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.asyncio
2
async 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
)
6
7
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") == 1
11
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:

1
class CardDeclined(Exception):
2
pass
3
4
5
@pytest.mark.asyncio
6
async def test_a_declined_card_fails_the_order(env: TestWorkflowEnvironment) -> None:
7
env.mock_task("charge-payment").throws(CardDeclined("insufficient funds"))
8
9
with pytest.raises(CardDeclined, match="insufficient funds"):
10
await env.execute_workflow(process_order, ORDER)
11
12
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.asyncio
2
async 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
)
11
12
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.asyncio
2
async def test_the_cooling_off_period(env: TestWorkflowEnvironment) -> None:
3
started = env.get_current_time()
4
5
await env.execute_workflow(process_order, ORDER)
6
7
# 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:

SupportedNot supported
execute_task, sleep, set_state, get_state(key) (no default argument), now(), is_replaying, workflow_id, workflow_typeexecute, 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:

1
def order_total(items: list[dict]) -> int:
2
return sum(int(item["price"]) * int(item["quantity"]) for item in items)
3
4
5
@task(name="price-order")
6
async def price_order(ctx: TaskContext, items: list[dict]) -> int:
7
return order_total(items)
8
9
10
def test_order_total() -> None:
11
assert order_total([{"price": 250, "quantity": 2}, {"price": 100, "quantity": 1}]) == 600

Next steps

  • Workflows: what the workflows under test can do
  • Tasks: task design for testability
  • Patterns: workflows worth testing