python-tests

Python Test Style

• Pytest is used to run tests.
• Do not add @pytest.mark.asyncio to any test. Async tests are automatically detected and run by the async runner; the decorator is unnecessary clutter.
• Do not add a -> None return type annotation to test functions. This is not a common convention in pytest and adds unnecessary verbosity.
• When mocking a class, do not define a new class. Use unittest.mock.MagicMock or unittest.mock.AsyncMock, with the spec constructor argument when necessary.
• The name of the mocked class should be prefixed with mock, not fake.
• Prefer pytest fixtures over helper methods.
• Do not repeat fixtures, if a fixture is needed in multiple test files, place it in a conftest.py file.
• When creating a fixture follow this pattern:

  @pytest.fixture(name="<fixture_name>"[, scope="<scope>"])
  def <fixture_name>_fixture() -> <return_type>:
      ...
  Only specify the scope argument when the value is something other than "function".
• Prefer pytest.mark.parametrize over creating individual tests for different input types.
• If a fixture is needed for a test, but either does not return a value or the value is not used in the test, use the @pytest.mark.usefixtures decorator.
• tests/conftest.py contains a restore_environ_fixture fixture that restores the environment variables to their original state after each test, it is defined with autouse=True so it is automatically applied to all tests. If you need to modify the environment variables in a test, do so using os.environ and the fixture will restore them after the test completes. There is no need to use monkeypatch.setenv to modify environment variables in tests.
• Avoid defensive programming in tests. If a test fails, it should fail loudly and clearly, rather than silently passing due to defensive checks. For example

  data = results["data"]
  is preferred over

  data = results.get("data")
  Simply allow the resulting KeyError to be raised if the "data" key is not present in the results dictionary, as this will provide a clear indication of what went wrong in the test.

Common Commands

# Focused test loop
uv run pytest -k "<pattern>"
 
# Run all tests
uv run pytest

Do Not Write Tests For

• Documentation.
• Test helper code under tests/_utils/.
• Package metadata or wheel installation behavior.

References

• pyproject.toml
• tests/conftest.py