Skip to content

Commit bb2051b

Browse files
committed
Added docs for new utilities.
1 parent 4c58368 commit bb2051b

File tree

1 file changed

+63
-6
lines changed

1 file changed

+63
-6
lines changed

docs/guide/testing-taskiq.md

Lines changed: 63 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ the same interface as a real broker, but it doesn't send tasks actually.
8383
Let's define a task.
8484

8585
```python
86-
from your_project.taskiq import broker
86+
from your_project.tkq import broker
8787

8888
@broker.task
8989
async def parse_int(val: str) -> int:
@@ -107,7 +107,7 @@ And that's it. Test should pass.
107107
What if you want to test a function that uses task. Let's define such function.
108108

109109
```python
110-
from your_project.taskiq import broker
110+
from your_project.tkq import broker
111111

112112
@broker.task
113113
async def parse_int(val: str) -> int:
@@ -129,6 +129,63 @@ async def test_add_one():
129129
assert await parse_and_add_one("11") == 12
130130
```
131131

132+
### Unawaitable tasks
133+
134+
When a function calls an asynchronous task but doesn't await its result,
135+
it can be challenging to test.
136+
137+
In such cases, the `InMemoryBroker` provides two convenient ways to help you:
138+
the `await_inplace` constructor parameter and the `wait_all` method.
139+
140+
Consider the following example where we define a task and a function that calls it:
141+
142+
```python
143+
from your_project.tkq import broker
144+
145+
@broker.task
146+
async def parse_int(val: str) -> int:
147+
return int(val)
148+
149+
150+
async def parse_int_later(val: str) -> int:
151+
await parse_int.kiq(val)
152+
return 1
153+
```
154+
155+
To test this function, we can do two things:
156+
157+
1. By setting the `await_inplace=True` parameter when creating the broker.
158+
In that case all tasks will be automatically awaited as soon as they are called.
159+
In such a way you don't need to manually call the `wait_result` in your code.
160+
161+
To set it up, define the broker as the following:
162+
163+
```python
164+
...
165+
broker = InMemoryBroker(await_inplace=True)
166+
...
167+
168+
```
169+
170+
With this setup all `await function.kiq()` calls will behave similarly to `await function()`, but
171+
with dependency injection and all taskiq-related functionality.
172+
173+
2. Alternatively, you can manually await all tasks after invoking the
174+
target function by using the `wait_all` method.
175+
This gives you more control over when to wait for tasks to complete.
176+
177+
```python
178+
from your_project.tkq import broker
179+
180+
@pytest.mark.anyio
181+
async def test_add_one():
182+
# Call the function that triggers the async task
183+
assert await parse_int_later("11") == 1
184+
await broker.wait_all() # Waits for all tasks to complete
185+
# At that time we can guarantee that all sent tasks
186+
# have been completed and do all the assertions.
187+
```
188+
132189
## Dependency injection
133190

134191
If you use dependencies in your tasks, you may think that this can become a problem. But it's not.
@@ -146,7 +203,7 @@ from typing import Annotated
146203
from pathlib import Path
147204
from taskiq import TaskiqDepends
148205

149-
from your_project.taskiq import broker
206+
from your_project.tkq import broker
150207

151208

152209
@broker.task
@@ -161,7 +218,7 @@ async def modify_path(some_path: Annotated[Path, TaskiqDepends()]):
161218
from pathlib import Path
162219
from taskiq import TaskiqDepends
163220

164-
from your_project.taskiq import broker
221+
from your_project.tkq import broker
165222

166223

167224
@broker.task
@@ -177,7 +234,7 @@ expected dependencies manually as function's arguments or key-word arguments.
177234

178235
```python
179236
import pytest
180-
from your_project.taskiq import broker
237+
from your_project.tkq import broker
181238

182239
from pathlib import Path
183240

@@ -193,7 +250,7 @@ must mutate dependency_context before calling a task. We suggest to do it in fix
193250

194251
```python
195252
import pytest
196-
from your_project.taskiq import broker
253+
from your_project.tkq import broker
197254
from pathlib import Path
198255

199256

0 commit comments

Comments
 (0)