Testing Pytest

Pytest Backend Testing

Purpose

Guide to concrete pytest implementation for backend services.

Use this as a supporting/tooling skill after the lead testing skill is known:

• unit-testing leads isolated Python behavior;
• integration-testing leads database, repository, transaction, API, and multi-component behavior;
• concurrency_fuzzing_testing leads scheduler/interleaving/race-condition behavior;
• testing-test-strategy leads broad test planning;
• test-driven-development leads the test-first workflow.

If the user simply asks for "pytest tests" and the level is unclear, first infer or state the lead level, then use this skill for pytest-specific syntax and fixtures.

Test Writing Algorithm

1. Define the observable behavior.
2. Choose the smallest public interface that verifies it.
3. Identify dependencies:
   • controlled internal dependencies;
   • uncontrolled external dependencies.
4. Mock only uncontrolled external dependencies.
5. Prepare data explicitly.
6. Perform one main action.
7. Assert through a public effect:
   • API response;
   • database state;
   • return value;
   • published event;
   • external service call.
8. Ensure the test is independent.
9. Check that the test is not tied to incidental implementation details.

Arrange / Act / Assert

Write tests using AAA:

def test_create_user_fails_when_email_already_exists(client: Client) -> None:
    # Arrange
    client.post("/api/users", json={"name": "John", "email": "john@example.com"})

    # Act
    response = client.post(
        "/api/users",
        json={"name": "John2", "email": "john@example.com"},
    )

    # Assert
    assert response.status_code == 409
    assert "already exists" in response.json()["message"].lower()

Rules:

• one test has one main Act;
• avoid Act -> Assert -> Act -> Assert unless it is one coherent scenario;
• do not use if inside tests;
• do not hide important setup in unclear helpers;
• a huge Arrange often signals the test or code design should be simplified.

Naming

Name tests in domain language.

Good:

def test_create_user_fails_when_email_already_exists() -> None: ...

Bad:

def test_create_user_409_case_2() -> None: ...

Prefer clarity over a rigid naming scheme.

Mocking

Mock external uncontrolled dependencies:

• external HTTP;
• SMTP;
• third-party APIs and SDKs;
• external brokers and queues;
• filesystem access when it is not the subject of the test;
• unstable time, randomness, and environment sources.

Do not mock by default:

• internal application services;
• repositories when a test database gives better confidence;
• the database as a controlled dependency;
• cache controlled entirely by the service;
• private methods;
• internal calls that are not part of the public contract.

Mocking internal implementation often makes tests brittle.

When creating mocks, prefer specs:

from unittest.mock import Mock, create_autospec

email_sender_mock = Mock(spec=EmailSender)
repository_mock = create_autospec(UserRepository)

Specs catch typos, wrong attributes, bad signatures, and contract drift.

Public Behavior

Avoid asserting internals:

def test_user_creation_internals(client, user_repository_mock, db_session) -> None:
    response = client.post("/api/users", json={"name": "John", "email": "john@example.com"})

    assert response.status_code == 201
    assert db_session.execute.call_count == 2
    user_repository_mock.create.assert_called_once()

Prefer public effects:

from dirty_equals import IsDatetime, IsInt


def test_create_user_successfully(client, email_service_mock) -> None:
    email_service_mock.send_welcome_email.return_value = True

    response = client.post(
        "/api/users",
        json={"name": "John", "email": "john@example.com"},
    )

    assert response.status_code == 201
    assert response.json() == {
        "id": IsInt,
        "name": "John",
        "email": "john@example.com",
        "created_at": IsDatetime,
        "updated_at": IsDatetime,
    }
    email_service_mock.send_welcome_email.assert_called_once()

DAMP Over Excessive DRY

In tests, readability matters more than removing every duplicate line.

Prefer DAMP: Descriptive And Meaningful Phrases.

Small duplication is acceptable when it makes the scenario obvious. Do not build complex helper classes or factories that hide the business meaning.

A helper is useful when it is:

• short;
• typed;
• not hiding important business logic;
• reducing noise rather than meaning;
• reused by many similar tests.