Skip to content

Commit 022041c

Browse files
authored
docs: merge the test READMEs into tests/README.md (#1207)
The unit and integration tests each had their own README. They're merged into one `tests/README.md` with a section per level, and `CONTRIBUTING.md` links to it. This follows the same structure as Crawlee's [`tests/README.md`](https://github.com/apify/crawlee-python/tree/v2/tests) on its `v2` branch and the SDK's in apify/apify-sdk-python#1236. The content stays the same, plus the command to run each level. *✍️ Drafted by Claude Code*
1 parent 32fa36e commit 022041c

4 files changed

Lines changed: 91 additions & 33 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,10 @@ We use [ruff](https://docs.astral.sh/ruff/) for linting and formatting, [ty](htt
3030

3131
## Tests
3232

33-
- **Unit tests** (`tests/unit`) are isolated from the Apify API. See [`tests/unit/README.md`](tests/unit/README.md) for the rules they follow. Run them with `uv run poe unit-tests`, or a single test with `uv run pytest tests/unit/<path>.py::<test_name>`.
34-
- **Integration tests** (`tests/integration`) call the real Apify API. See [`tests/integration/README.md`](tests/integration/README.md) for the tokens they need. Run them with `uv run poe integration-tests`.
33+
[`tests/README.md`](tests/README.md) describes each test level, with its rules and required tokens.
34+
35+
- **Unit tests** (`tests/unit`) are isolated from the Apify API. Run them with `uv run poe unit-tests`, or a single test with `uv run pytest tests/unit/<path>.py::<test_name>`.
36+
- **Integration tests** (`tests/integration`) call the real Apify API. Run them with `uv run poe integration-tests`.
3537

3638
## Code style
3739

‎tests/README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Tests
2+
3+
The tests have two levels:
4+
5+
- [Unit tests](#unit-tests) (`tests/unit`) are isolated from the Apify API and need no credentials or network access.
6+
- [Integration tests](#integration-tests) (`tests/integration`) call the real Apify API.
7+
8+
A test that calls the Apify API is an integration test. Every other test is a unit test. Helpers shared by both levels live in `tests/_utils.py`.
9+
10+
## Unit tests
11+
12+
Unit tests are fully isolated from the real Apify API. They use mocks, fakes, or a local HTTP server, so they need no API tokens and no network access.
13+
14+
### Running unit tests
15+
16+
```bash
17+
uv run poe unit-tests
18+
```
19+
20+
To run a single test:
21+
22+
```bash
23+
uv run pytest tests/unit/<path>.py::<test_name>
24+
```
25+
26+
### Unit test fixtures
27+
28+
- `httpserver`: a local HTTP server (from `pytest-httpserver`) on `127.0.0.1`, shared by the session and cleared after each test.
29+
- `sync_client` and `async_client`: an `ApifyClient` and an `ApifyClientAsync` pointed at `httpserver`.
30+
- `http_client_classes`: runs the test once per built-in HTTP transport (`impit` and `httpx2`) and makes it the default transport the clients construct. A module opts all its tests in with `pytestmark = pytest.mark.usefixtures('http_client_classes')`. Tests that construct a transport directly use `http_client_class` and `http_client_async_class`.
31+
32+
### Mocking the API
33+
34+
Register the expected requests on `httpserver` and point the client at it:
35+
36+
```python
37+
def test_example(httpserver: HTTPServer, sync_client: ApifyClient) -> None:
38+
httpserver.expect_request('/v2/endpoint').respond_with_json({'data': ...})
39+
# call sync_client and assert its behavior
40+
```
41+
42+
## Integration tests
43+
44+
Integration tests communicate with the real Apify API.
45+
46+
### Running integration tests
47+
48+
The tests need API tokens of two test users:
49+
50+
- `APIFY_TEST_USER_API_TOKEN`: the main test user.
51+
- `APIFY_TEST_USER_2_API_TOKEN`: a second user, who owns the storages for the permission tests.
52+
53+
```bash
54+
export APIFY_TEST_USER_API_TOKEN=<your-token>
55+
export APIFY_TEST_USER_2_API_TOKEN=<your-second-token>
56+
uv run poe integration-tests
57+
```
58+
59+
To run them against a different Apify API environment, also set `APIFY_INTEGRATION_TESTS_API_URL`.
60+
61+
### Integration test fixtures
62+
63+
- `client`: an `ApifyClient` or `ApifyClientAsync` for the main test user. Each test that uses it runs four times, once for each combination of sync or async client and `impit` or `httpx2` transport.
64+
- `is_async`: `True` when the test runs with the async client.
65+
- `test_dataset_of_another_user` and `test_kvs_of_another_user`: a dataset and a key-value store owned by the second user, with known content and the signatures for accessing it.
66+
67+
### Writing integration tests
68+
69+
One test function covers both clients. Wrap each client call in `maybe_await`, which awaits the result of the async client and returns the result of the sync one as is:
70+
71+
```python
72+
async def test_dataset_get_or_create(client: ApifyClient | ApifyClientAsync) -> None:
73+
"""A dataset created by name can be retrieved by its ID."""
74+
dataset_name = get_random_resource_name('dataset')
75+
dataset = await maybe_await(client.datasets().get_or_create(name=dataset_name))
76+
dataset_client = client.dataset(dataset.id)
77+
78+
try:
79+
retrieved = await maybe_await(dataset_client.get())
80+
assert retrieved is not None
81+
assert retrieved.name == dataset_name
82+
finally:
83+
await maybe_await(dataset_client.delete())
84+
```
85+
86+
- Name the resources a test creates with `get_random_resource_name`, so parallel test runs don't collide, and delete them in a `finally` block.
87+
- The API is eventually consistent, so a resource you just created or changed may take a moment to show up. Poll with `poll_until_condition`, or with `collect_iterate_until_present` for `iterate()` listings, instead of sleeping for a fixed time. Where a test has to sleep, use `maybe_sleep`, which blocks only for the sync client.

‎tests/integration/README.md‎

Lines changed: 0 additions & 11 deletions
This file was deleted.

‎tests/unit/README.md‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

0 commit comments

Comments
 (0)