Skip to main content
rule CX Codex

python-tests — Claude Code rule: what it does, how to install

python-tests sets pytest authoring conventions: AAA test structure, given-when-then naming, and when to reach for mocker, monkeypatch or MagicMock.

MIT ★ 1,627 updated 2026-10-25

Install into GitHub Copilot · Manually: put the files in place All methods and platforms ↓
.github/instructions/python-tests.instructions.md
Open on GitHub

What python-tests does

The rule targets **/*.py files and defines how pytest tests should be written, with BDD-style method names following test_given_context_when_action_then_expected and an Arrange/Act/Assert layout separated by blank lines and comments. Each test is expected to carry one assertion.

A table splits mocking tools by purpose: the mocker fixture from pytest-mock is the default for new code and migrations, monkeypatch covers plain attribute or environment overrides, and a direct unittest.mock.MagicMock() import is reserved for data stubs that aren't used as spy or assertion targets. Existing projects keep their current unittest.mock usage and only switch to mocker when a file gets edited anyway.

File naming has to mirror the module under test, so parser.py gets test_parser.py, and shared setup belongs in conftest.py fixtures. @pytest.mark.parametrize is the expected tool for data-driven cases with multiple input/output pairs, and logger mocks are excluded from assertions. The companion python-script.instructions.md conventions apply on top of this one.

What it helps with

  • enforce Arrange/Act/Assert structure in pytest tests
  • decide between mocker, monkeypatch and MagicMock
  • name test methods with given-when-then phrasing
  • migrate @patch decorators to mocker.patch
  • split shared setup into conftest.py fixtures

Example prompts for the agent

  • Write tests for parser.py following the python-tests rule
  • Convert this test from @patch to mocker.patch per python-tests
  • Add a parametrized test for DataProcessor using the python-tests conventions

How to install python-tests

Manually: put the files in place

.github/instructions/python-tests.instructions.md

The applyTo field sets which files it applies to

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about python-tests

How to install python-tests in Claude Code?

Place the rule at .claude/rules/python-tests.md.

What does python-tests do?

It sets pytest authoring conventions for **/*.py files, covering AAA structure, given-when-then test naming, and the split between mocker, monkeypatch and MagicMock for mocking.

How do mocker, monkeypatch and MagicMock differ under this rule?

mocker.patch() handles functions, methods and classes where call counts matter, monkeypatch.setattr() covers simple constant or environment-variable overrides, and a direct MagicMock() import is only for building data stubs that aren't checked as spies.

Source text

python-tests.instructions.md · MIT
---
applyTo: '**/*.py'
description: 'Python test code authoring conventions'
---

# Python Test Instructions

Conventions for Python test code. All conventions from [python-script.instructions.md](python-script.instructions.md) apply.

## Test Framework

Use pytest with BDD-style naming. Structure each test with Arrange/Act/Assert (AAA) sections separated by blank lines and comments.

### Mocking Libraries

| Library                        | Usage                                                  |
|--------------------------------|--------------------------------------------------------|
| pytest-mock (`mocker` fixture) | Preferred for new projects and test migrations         |
| monkeypatch                    | Acceptable for simple attribute/environment patching   |
| unittest.mock (direct import)  | Existing projects only; migrate to mocker when editing |

## When to Use mocker vs monkeypatch

* `mocker.patch()` — replacing functions, methods, classes, or module attributes with controlled return values or side effects; verifying call counts and arguments.
* `monkeypatch.setattr()` — simple attribute overrides (constants, config values, environment variables) where return tracking is not needed.
* Direct `MagicMock()` import — acceptable for constructing pure test data stubs (mock objects used as constructor arguments, not as spy/assert targets).

## Test Naming

Test method format: `test_given_context_when_action_then_expected`

```text
test_given_valid_request_when_process_data_then_returns_parsed_response
test_given_empty_input_when_process_data_then_raises_value_error
test_given_missing_config_when_initialize_then_exits_with_error
```

Prefer one assertion per test. Related assertions validating the same behavior are acceptable. Do not verify logger mocks.

Use `@pytest.mark.parametrize` for data-driven tests with multiple input/output combinations.

## Test Organization

* File naming mirrors module under test with `test_` prefix (for example, `parser.py` → `test_parser.py`).
* Fixtures in `conftest.py` when shared across multiple test files.
* Class-based grouping optional; use when tests share setup logic.
* Group test methods by behavior, alphabetically within groups.
* Common mock setup in fixtures or class-level setup; specific setup in individual tests.

## pytest-mock Patterns

The `mocker` fixture from pytest-mock replaces direct `unittest.mock` usage. These patterns show each migration.

### mocker.patch() replacing @patch decorator

```python
# Before — unittest.mock
from unittest.mock import patch


@patch("myapp.service.fetch_data")
def test_process_uses_fetched_data(mock_fetch):
    mock_fetch.return_value = {"key": "value"}
    result = process()
    assert result == "value"


# After — pytest-mock
def test_process_uses_fetched_data(mocker):
    mock_fetch = mocker.patch("myapp.service.fetch_data", return_value={"key": "value"})
    result = process()
    assert result == "value"
    mock_fetch.assert_called_once()
```

### mocker.patch() replacing with patch() context manager

```python
# Before — unittest.mock
from unittest.mock import patch


def test_service_calls_endpoint():
    with patch("myapp.client.post") as mock_post:
        mock_post.return_value.status_code = 200
        response = send_request()
    assert response.status_code == 200


# After — pytest-mock
def test_service_calls_endpoint(mocker):
    mock_post = mocker.patch("myapp.client.post")
    mock_post.return_value.status_code = 200
    response = send_request()
    assert response.status_code == 200
```

### mocker.patch.dict() replacing @patch.dict

```python
# Before — unittest.mock
from unittest.mock import patch


@patch.dict("os.environ", {"API_KEY": "test-key"})
def test_config_reads_env():
    config = load_config()
    assert config.api_key == "test-key"


# After — pytest-mock
def test_config_reads_env(mocker):
    mocker.patch.dict("os.environ", {"API_KEY": "test-key"})
    config = load_config()
    assert config.api_key == "test-key"
```

### mocker.patch.object() replacing patch.object()

```python
# Before — unittest.mock
from unittest.mock import patch

from myapp.service import DataService


@patch.object(DataService, "connect")
def test_service_connects(mock_connect):
    mock_connect.return_value = True
    svc = DataService()
    assert svc.connect() is True


# After — pytest-mock
from myapp.service import DataService


def test_service_connects(mocker):
    mock_connect = mocker.patch.object(DataService, "connect", return_value=True)
    svc = DataService()
    assert svc.connect() is True
    mock_connect.assert_called_once()
```

### mocker.MagicMock() and mocker.AsyncMock() for spy targets

Use `mocker.MagicMock()` and `mocker.AsyncMock()` when constructing mock objects that serve as spy targets for call assertion:

```python
def test_handler_delegates_to_processor(mocker):
    mock_processor = mocker.MagicMock()
    handler = RequestHandler(processor=mock_processor)
    handler.handle({"id": 1})
    mock_processor.process.assert_called_once_with({"id": 1})


async def test_async_handler_awaits_processor(mocker):
    mock_processor = mocker.AsyncMock()
    handler = AsyncRequestHandler(processor=mock_processor)
    await handler.handle({"id": 1})
    mock_processor.process.assert_awaited_once_with({"id": 1})
```

### Direct MagicMock() import for test data stubs

Direct `MagicMock()` import stays as-is when constructing pure test data stubs that are not spy/assert targets:

```python
from unittest.mock import MagicMock


def test_formatter_accepts_any_writer():
    # Arrange
    stub_writer = MagicMock()
    stub_writer.encoding = "utf-8"
    formatter = OutputFormatter(writer=stub_writer)

    # Act
    result = formatter.format("hello")

    # Assert
    assert result == "hello"
```

## Complete Example

A full test class using the mocker fixture with AAA structure:

```python
import pytest  # noqa: F811

from myapp.processor import DataProcessor
from myapp.service import DataService


class TestDataProcessor:
    @pytest.fixture()
    def mock_service(self, mocker):
        return mocker.patch.object(DataService, "fetch", return_value={"status": "ok", "value": 42})

    @pytest.fixture()
    def processor(self):
        return DataProcessor(service=DataService())

    def test_given_valid_response_when_process_then_returns_value(self, processor, mock_service):
        # Act
        result = processor.process()

        # Assert
        assert result == 42
        mock_service.assert_called_once()

    def test_given_error_response_when_process_then_raises(self, processor, mocker):
        # Arrange
        mocker.patch.object(DataService, "fetch", side_effect=ConnectionError("timeout"))

        # Act & Assert
        with pytest.raises(ConnectionError, match="timeout"):
            processor.process()

    @pytest.mark.parametrize(
        ("status", "expected"),
        [
            ("ok", 42),
            ("pending", 0),
        ],
    )
    def test_given_status_when_process_then_returns_expected(self, mocker, status, expected):
        # Arrange
        mocker.patch.object(DataService, "fetch", return_value={"status": status, "value": expected})
        processor = DataProcessor(service=DataService())

        # Act
        result = processor.process()

        # Assert
        assert result == expected
```

© microsoft · MIT · microsoft/hve-core

Similar IDE rules

All IDE rules for Testing and QA →

From the same set148

The whole set →
Functional Planner Functional Planner — a read-only subagent turns PRDs into work-item hierarchies for Azure DevOps, GitHub, or Jira when you need a reviewable plan before execution. CX Codex +1 ★ 1,627repo stars ADO Backlog Executor ADO Backlog Executor runs a pre-approved batch of Azure DevOps work-item operations — create, update, link, comment — inside one confirmed project. CX Codex +1 ★ 1,627repo stars risk-register Generates a qualitative risk register using a Probability × Impact matrix, assigns owners, defines mitigation strategies, and creates contingency plans. CX Codex +1 ★ 1,627repo stars hve-builder The hve-builder rule sets authoring conventions for prompts, agents, subagents, instructions, and skills. It activates for matching artifact files. CX Codex +1 ★ 1,627repo stars vex OpenVEX v0.2.0 reference and management playbooks for structuring, checking, and validating vulnerability statements. CX Codex +1 ★ 1,627repo stars rust-tests This rule sets conventions for Rust tests, from module placement and naming to fixtures and HTTP mocks. Use it when you want tests in a project to follow the same structure. CX Codex +1 ★ 1,627repo stars CVE Analyzer CVE Analyzer — a subagent for deep CVE analysis: checks if vulnerable code is reachable in the project and returns evidence-backed VEX status. CX Codex +1 ★ 1,627repo stars python-script python-script defines Python 3.11+ script standards for Claude Code, enforcing package workflows with uv, modern type syntax, and clean CLI structures. CX Codex +1 ★ 1,627repo stars

Project sponsors

Companies that keep this analytics open