Version history: pytest

v1

scan: pass2026-08-11 — Ingested from source

Initial version.

v2

currentscan: pass2026-11-02 — Currency pass 2026-11-01: fixed the two broken GOOD examples (class test method now takes self; api_client fixture no longer requests a narrower-scoped db_session, which raised ScopeMismatch), softened single-assert-per-test to a preference, strict xfail, Iterator fixture typing, quoted globs so the frontmatter parses, removed team boilerplate.
  ---- description: This guide defines our team's definitive best practices for writing fast, reliable, and maintainable tests using pytest, ensuring consistency and high code quality across projects.
- globs: **/*.py+ description: "Best practices for writing fast, reliable, and maintainable tests with pytest: src layout, fixtures and scopes, parametrize, markers, mocking, and coverage."
+ globs: "**/*.py"
+ alwaysApply: false  ---
  # pytest Best Practices
  - This document outlines our team's standard for writing `pytest` tests. Adhering to these guidelines ensures our test suite is fast, reliable, and easy to maintain, integrating seamlessly into our CI/CD pipelines.+ This document outlines a standard for writing `pytest` tests. Following these guidelines keeps the test suite fast, reliable, and easy to maintain, and lets it integrate cleanly into CI/CD pipelines.  
  ## 1. Code Organization & Structure
  
  ### 1.1 Project Layout
  Always use the `src/` layout for your project. This prevents common import pitfalls and ensures tests run against the installed package, not local source.
  
  **✅ GOOD:**
  ```
  .
  ├── pyproject.toml
  ├── src/
  │   └── mypackage/
  │       ├── __init__.py
  │       └── module.py
  └── tests/
      ├── __init__.py
      └── test_module.py
  ```
  
  **❌ BAD:**
  ```
  .
  ├── pyproject.toml
  ├── mypackage/ # Top-level package
  │   ├── __init__.py
  │   └── module.py
  └── tests/
      └── test_module.py
  ```
  
  ### 1.2 Test File Naming
  Name test files `test_*.py` or `*_test.py`. We prefer `test_*.py`.
  Place `__init__.py` files in `tests/` and its subdirectories to treat them as Python packages, enabling structured imports and avoiding name collisions.
  
  **✅ GOOD:**
  ```python
  # tests/test_my_feature.py
  from mypackage.module import my_function
  
  def test_my_function_returns_expected_value():
      assert my_function() == "expected"
  ```
  
  ### 1.3 Test Naming Conventions
  Prefix test functions and methods with `test_`. For classes, prefix with `Test`. Use descriptive names that read like sentences.
  
  **✅ GOOD:**
  ```python
  def test_user_can_be_created_with_valid_email():
      # ...
      pass
  
  class TestUserService:-     def test_get_user_by_id_returns_correct_user():+     def test_get_user_by_id_returns_correct_user(self):          # ...
          pass
  ```
  
  **❌ BAD:**
  ```python
  def create_user(): # Not discovered by pytest
      pass
  
  def test_create_user_and_email(): # Tests multiple things
      pass
  
  class UserServiceTest: # Incorrect class prefix
      pass
  ```
  
  ## 2. Common Patterns & Anti-patterns
  - ### 2.1 Single Assert Per Test
- Each test should verify one specific behavior. This improves readability and simplifies debugging.+ ### 2.1 One Behavior Per Test
+ Each test should verify one specific behavior. Prefer few, closely related asserts over long chains that mix unrelated checks; one assert per test is a useful default, not a hard rule. This improves readability and simplifies debugging.  
  **✅ GOOD:**
  ```python
  def test_user_creation_sets_email():
      user = create_user("test@example.com")
      assert user.email == "test@example.com"
  
  def test_user_creation_sends_welcome_email():
      user = create_user("test@example.com")+     send_welcome_email(user)      assert email_service.last_sent_email == "test@example.com"
  ```
  
  **❌ BAD:**
  ```python
  def test_user_creation_and_email_sending():
      user = create_user("test@example.com")-     assert user.email == "test@example.com" # First assert+     assert user.email == "test@example.com" # First behavior      send_welcome_email(user)-     assert email_service.last_sent_email == "test@example.com" # Second assert+     assert email_service.last_sent_email == "test@example.com" # Unrelated second behavior  ```
  
  ### 2.2 Fixtures for Setup/Teardown & Dependency Injection
  Use fixtures to provide isolated, reusable resources and manage setup/teardown.
  
  *   **Scope**:
      *   `function` (default): Run once per test function. Use for most tests.
      *   `class`: Run once per test class.
      *   `module`: Run once per test module. Use for expensive setups shared across module tests.
      *   `session`: Run once per test session. Use for global, very expensive resources (e.g., database connection pool).
  *   **Teardown**: Use `yield` in fixtures for automatic teardown.- *   **Modularity**: Compose fixtures by injecting them into others.+ *   **Modularity**: Compose fixtures by injecting them into others. A fixture can only depend on fixtures of the same or a wider scope (a `module` fixture cannot use a `function` fixture; pytest raises `ScopeMismatch`).  *   **Avoid `autouse=True`**: Only use for truly global, non-interfering setups (e.g., patching a common library function for all tests).
  
  **✅ GOOD:**
  ```python
  # conftest.py
  import pytest
  
  @pytest.fixture(scope="function")
  def db_session():
      # Setup: Create a fresh database session
      session = create_test_db_session()
      yield session  # Test runs here
      # Teardown: Close and clean up the session
      session.close()
  - @pytest.fixture(scope="module")+ @pytest.fixture # function scope: must not be wider than db_session's scope  def api_client(db_session): # Fixtures can use other fixtures
      # Setup: Create an API client with a specific DB session
      client = TestClient(db_session)
      yield client
      # Teardown: Cleanup client resources+     client.close()  ```
  
  **❌ BAD:**
  ```python
  # test_bad.py
  class TestUser:
      def setup_method(self): # unittest-style setup, less flexible
          self.user = User("test@example.com")
  
      def test_user_email(self):
          assert self.user.email == "test@example.com"
  
  @pytest.fixture(autouse=True) # Avoid unless absolutely necessary
  def global_patch():
      # This fixture runs for *every* test, potentially causing unexpected side effects.
      pass
  ```
  
  ### 2.3 Parameterization
  Use `@pytest.mark.parametrize` for data-driven tests.
  
  **✅ GOOD:**
  ```python
  import pytest
  
  @pytest.mark.parametrize("input, expected_output", [
      (1, 2),
      (2, 3),
      (0, 1),
  ])
  def test_increment_function(input, expected_output):
      assert increment(input) == expected_output
  ```
  
  ### 2.4 Markers
  Use `@pytest.mark.skip` for tests that are not yet ready or temporarily broken. Use `@pytest.mark.xfail` for known bugs that are expected to fail but should still be run.
  
  **✅ GOOD:**
  ```python
  import pytest
  
  @pytest.mark.skip(reason="Feature not implemented yet")
  def test_new_feature_endpoint():
      pass
  - @pytest.mark.xfail(reason="Known bug: #1234")+ @pytest.mark.xfail(reason="Known bug: #1234", strict=True) # fails the run if it unexpectedly passes  def test_buggy_legacy_function():
      assert legacy_function() == "fixed_output"
  ```
  
  ## 3. Performance Considerations
  
  ### 3.1 Keep Tests Fast
  Prioritize fast tests. Slow tests discourage local execution and lead to longer CI times.
  *   **Mock external services**: Use mocks for APIs, databases, and file systems.
  *   **Appropriate fixture scope**: Don't use `session` scope for resources that need to be fresh per test.
  *   **Small, focused tests**: Each test should do minimal work.
  
  ## 4. Mocking Strategies
  
  Use the `mocker` fixture (from `pytest-mock`) for robust mocking. It integrates `unittest.mock` functionality with `pytest`'s fixture system.
  
  **✅ GOOD:**
  ```python
  # test_service.py
  from mypackage.service import MyService
  from mypackage.external_api import get_data
  
  def test_my_service_fetches_data(mocker):
      mock_get_data = mocker.patch("mypackage.service.get_data")
      mock_get_data.return_value = {"key": "mocked_value"}
  
      service = MyService()
      result = service.fetch_and_process()
  
      mock_get_data.assert_called_once()
      assert result == "processed_mocked_value"
  ```
  
  **❌ BAD:**
  ```python
  # test_service.py (using raw monkeypatch for complex mocks)
  import pytest
  from mypackage.service import MyService
  from mypackage.external_api import get_data
  
  def test_my_service_fetches_data_raw_monkeypatch(monkeypatch):
      # monkeypatch is fine for simple cases, but mocker is better for complex mocks
      # and provides more assert methods.
      def mock_get_data():
          return {"key": "mocked_value"}
      monkeypatch.setattr("mypackage.service.get_data", mock_get_data)
  
      service = MyService()
      result = service.fetch_and_process()
      assert result == "processed_mocked_value"
  ```
  
  ## 5. Coverage Patterns
  
  Integrate `pytest-cov` to measure test coverage. Aim for high coverage, but understand that 100% coverage doesn't guarantee bug-free code. Focus on covering critical paths and edge cases.
  
  **✅ GOOD:**
  ```bash
  # Run tests with coverage and generate report
  pytest --cov=mypackage --cov-report=term-missing --cov-report=html
  ```
  
  ## 6. Type Hints
  
  Apply type hints to test code, especially for fixtures and complex test functions. This improves readability, maintainability, and enables static analysis.
  
  **✅ GOOD:**
  ```python- from typing import Generator+ from collections.abc import Iterator  import pytest
  
  class User:
      def __init__(self, email: str):
          self.email = email
  
  @pytest.fixture- def new_user() -> Generator[User, None, None]:+ def new_user() -> Iterator[User]:      user = User("test@example.com")
      yield user
      # Cleanup if necessary
  
  def test_user_email_property(new_user: User) -> None:
      assert new_user.email == "test@example.com"- ```+ ```