Skip to content

Testing Guidelines

We use pytest as our testing framework and respx to safely mock outbound HTTP requests to Google Play.

It is strictly required that developers run tests before committing code. We mock network requests instead of writing live integration tests to prevent IP bans and flaky continuous integration pipelines.

Running Tests

To run the entire test suite via uv:

uv run pytest

How to use Context Managers Context Managers (PlayScraper is typically used via a with statement), your respx mocks must account for the __enter__ and __exit__ flows.

Mocking Responses

When writing a new test, you should utilize @respx.mock and define precise network intercepts. A common pattern is to inject a minimal, valid HTML skeleton containing the specific AF_initDataCallback JSON data your new function requires.

import respx
from httpx import Response
from google_play_scraper import PlayScraper

@respx.mock
def test_new_feature_success() -> None:
    app_id = "com.test.app"
    url = f"https://play.google.com/store/apps/details?id={app_id}"

    # 1. Provide the exact string the scraper regex expects
    mock_html = (
        "<html><body><script>"
        "AF_initDataCallback({key: 'ds:5', hash: '1', data: [null, [null, "
        '[null, "IconUrl"]]], sideChannel: {}});"
        "</script></body></html>"
    )

    # 2. Intercept the network call
    respx.get(url).mock(return_value=Response(200, text=mock_html))

    # 3. Assert the outcome
    with PlayScraper() as scraper:
        # Action
        assert True

Manual Verification (test_manual.py)

While automated unit tests with mocks are required for CI pipelines, building the initial extraction index mappings ([1][0][6]) often requires exploring live, real-world data responses.

You can create temporary exploratory test scripts under the test_manual.py naming convention (this file is excluded from CI checks if configured correctly, or generally intended for local-only use).

When adjusting internal batchexecute protocols, manual live testing is heavily encouraged to verify the raw JSON array responses.