|
| 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. |
0 commit comments