Testing

Before contributing to Read the Docs, make sure your patch passes our test suite and your code style passes our code linting suite.

Read the Docs uses Tox to execute testing and linting procedures. Tox is the only dependency you need to run linting or our test suite, the remainder of our requirements will be installed by Tox into environment specific virtualenv paths. Before testing, make sure you have Tox installed:

pip install tox

Running tests

The test suite is split into separate tox environments that match the CI pipeline:

tox -e py312          # Core tests (no search, no proxito)
tox -e search         # Search tests (requires Elasticsearch)
tox -e proxito        # Proxito tests

To run all test suites at once:

tox -e py312,search,proxito

To run a subset of tests:

tox -e py312 -- -k test_celery

Tip

Install tox-uv alongside tox for faster virtualenv creation and dependency resolution:

pip install tox tox-uv

Tox environments

The tox configuration has the following environments configured. You can target a single environment to limit the test suite:

py312

Core tests — excludes search, proxito, and embed API markers.

search

Search tests — requires an Elasticsearch instance.

proxito

Proxito tests — uses readthedocs.settings.proxito.test.

pre-commit

Run linting and formatting checks via pre-commit.

migrations

Check for missing Django migrations.

docs

Build user documentation with Sphinx.

docs-dev

Build developer documentation with Sphinx.

Pytest marks

The Read the Docs code base is deployed as three instances:

  • Main: where you can see the dashboard.

  • Build: where the builds happen.

  • Serve/proxito: it is in charge of serving the documentation pages.

Each instance has its own Django settings. To make sure we test each part as close as possible to its real settings, we use pytest marks and separate tox environments.

Current marks are:

  • search — tests that require Elasticsearch

  • proxito — tests for the serve/proxito instance

  • embed_api — tests for the embed API

Tests without a mark are from the main instance.

Continuous integration

The CI pipeline runs on Circle CI for every push. Tests are split into parallel jobs:

  • checks — pre-commit linting + migration checks

  • tests — core tests (no Elasticsearch needed)

  • tests-proxito — proxito tests

  • tests-search — search tests (requires Elasticsearch, runs after the above pass)

  • tests-embedapi — embed API tests across multiple Sphinx versions

You can check out the current build status: https://app.circleci.com/pipelines/github/readthedocs/readthedocs.org