Article summary

TL;DR

  • Unit tests check focused behavior; integration tests exercise selected real connections; E2E tests enter through a complete user workflow.
  • A calculation can work while its configuration or command output is wrong. Keep tests that reach each responsibility.
  • The companion has 18 cases. Three deliberate defects show which failures each test group can detect.
  • Acceptance and regression describe why a test exists. Either purpose can apply at different testing levels.
  • Use the testing pyramid to think about feedback cost, not to enforce a fixed percentage. AI-generated tests still need independently chosen expectations.

Code for this article

Open the repository to follow along.

artem-istranin/istranin-dev-code-examples
View on GitHub (opens in a new tab)

01 / COMPARISON

Unit testing vs integration testing vs E2E: compare the boundaries.

Your calculation tests pass, but a customer still gets the wrong answer. The formula works. The application loaded the wrong conversion settings.

A test can only detect a mistake in the behavior it actually exercises. This is the useful distinction between unit testing, integration testing, and end-to-end testing: where the test enters the software, which real components run, and where it checks the result.

We’ll test one small Python unit converter at all 3 levels. The requirement stays the same: converting 25 degrees Celsius to Fahrenheit should produce 77. Then we’ll introduce deliberate defects and see which tests notice.

Level What runs in this example A failure it can expose
Unit The calculation, using unit definitions supplied by the test A wrong formula
Integration The real JSON definitions, their loader, and the calculation together Wrong configuration or incompatible data
End-to-end (E2E) The installed command, from terminal arguments to output and exit status Broken command wiring or output

The larger boundaries include responsibilities the smaller test leaves out. That makes them useful for different questions, even when all 3 expect 77.

You need basic Python and familiarity with pytest assertions. If you’re new to pytest, start with my pytest guide for beginners.

This is a walkthrough of a finished example; you won’t need a browser, database, or remote service.

Teams use testing labels differently. When a label is unclear, describe what the test runs and observes. A folder name alone doesn’t establish its scope.

Nested test boundaries: unit tests cover conversion, integration adds the packaged JSON and loader, and E2E adds the installed command

The outlines show the real components included at each boundary in this example. The unit test supplies its own definitions; the broader tests use the application’s packaged JSON.

02 / RUN THE EXAMPLE

Start with a working command and a green suite.

Use Git, Python 3.13 or newer, and uv. Clone the companion, then open this article’s project:

git clone https://github.com/artem-istranin/istranin-dev-code-examples.git
cd istranin-dev-code-examples/unit-integration-e2e-testing-python
uv sync --locked
uv run units-convert 25 C F
uv run pytest -v

If you already cloned the repository, open that directory and run the last 3 commands. The conversion prints 77. The suite reports 18 passed: 10 unit cases, 4 integration cases, and 4 E2E cases.

uv sync --locked installs the project and the dependencies recorded in uv.lock. It also installs the units-convert command. This walkthrough was checked with Python 3.13.12, pytest 9.1.1, and Typer 0.27.2 from that environment.

Keep your terminal in this directory. The snippets below explain files that already exist; they are not replacement files or extra tests to paste in.

src/unit_converter/
  converter.py    # Conversion rules
  registry.py     # Reads packaged definitions
  units.json      # Supported units and their settings
  cli.py          # Terminal arguments and output
tests/
  unit/
  integration/
  e2e/

The application supports meters, centimeters, kilograms, grams, Celsius, and Fahrenheit. Symbols are case-sensitive: C and F are valid. Invalid conversions produce an error and a nonzero exit status.

This is an editable development installation: changing the checked-out source changes what the next command run executes. We’ll use that property for the temporary defects, restoring each change afterward.

03 / UNIT TESTING

Unit tests check the calculation with controlled inputs.

A unit test checks a focused piece of behavior. The unit can be a function, a class, or a few closely related objects. It doesn’t have to be exactly one function, and it doesn’t require mocking every collaborator.

Unit-test scope highlighted: conversion, with other testing levels muted

Our calculation uses a small Unit data object. It holds a dimension, such as temperature, plus a scale and offset. Celsius is the base temperature unit. Fahrenheit uses fahrenheit = celsius * 1.8 + 32.

The first test in tests/unit/test_converter.py supplies those definitions directly:

import pytest

from unit_converter.converter import Unit, convert


def test_celsius_to_fahrenheit():
    celsius = Unit(dimension="temperature")
    fahrenheit = Unit(dimension="temperature", scale=1.8, offset=32)

    result = convert(25, celsius, fahrenheit)

    assert result == pytest.approx(77)

The test prepares the inputs, calls the real calculation, and checks an independently chosen answer. pytest.approx allows a small numeric tolerance for floating-point rounding.

No JSON file is read. A passing result establishes this conversion with the supplied definitions. It says nothing about whether the application loads the right definitions.

Practice choosing useful test cases and boundaries in the Pytest Python test automation course.

View course

Here is the function the test calls, from src/unit_converter/converter.py:

def convert(value: float, source: Unit, target: Unit) -> float:
    if source.dimension != target.dimension:
        raise ValueError("Cannot convert between different dimensions")

    base_value = (value - source.offset) / source.scale
    return base_value * target.scale + target.offset

It first rejects incompatible dimensions, such as length and mass. Then it converts through the shared base unit. For 77 F -> C, the first calculation is (77 - 32) / 1.8 = 25. For 25 C -> F, the target scale and offset produce 25 * 1.8 + 32 = 77.

Run the unit tests:

uv run pytest tests/unit -v

Expect 10 passed. The suite also covers reverse conversions, zero and negative values, and invalid unit scales. This small boundary makes it easy to explore many calculation cases. The Python unit-testing best practices guide goes further into selecting useful cases and keeping tests readable.

04 / INTEGRATION TESTING

Integration tests include the real configuration and its loader.

An integration test checks an interaction between selected real components. Here, that interaction starts when the application reads its JSON definitions and turns them into Unit objects for the converter.

Integration scope highlighted: real JSON, loader, and conversion

Other integration tests might connect application code to a real database or an API client to a test server. The selected connection matters more than the number of functions involved.

Open src/unit_converter/units.json. Fahrenheit’s entry has a scale of 1.8 and an offset of 32. Those values play the same role as the arguments in the unit test, but they now come from the application.

load_units() in registry.py reads the file and builds the objects:

import json
from importlib.resources import files

from unit_converter.converter import Unit


def load_units() -> dict[str, Unit]:
    text = files("unit_converter").joinpath("units.json").read_text(encoding="utf-8")
    definitions = json.loads(text)
    return {symbol: Unit(**definition) for symbol, definition in definitions.items()}

importlib.resources locates the data inside the installed package. It doesn’t assume the command runs from the repository directory. Unit(**definition) passes each JSON object’s values as named arguments to Unit.

The test in tests/integration/test_registry_conversion.py uses that real loader:

import pytest

from unit_converter.converter import convert
from unit_converter.registry import load_units


def test_packaged_temperature_conversion():
    units = load_units()

    result = convert(25, units["C"], units["F"])

    assert result == pytest.approx(77)

The expected answer is still 77. What changed is the path to it: real file, real loader, real calculation. An incorrect Fahrenheit setting can now make the test fail.

Replacing load_units() with a mock returning perfect data would remove the interaction this test needs to check. In a larger application, it can still make sense to replace an unrelated dependency. Keep the connection under examination real.

uv run pytest tests/integration -v

Expect 4 passed. This local file integration is quick. Speed alone doesn’t classify a test; the real dependency and the question being checked matter more.

05 / E2E TESTING

End-to-end tests enter through the installed command.

An end-to-end test follows a complete workflow through the application’s external entry point. For this application, that means launching units-convert, passing arguments, and observing its output and exit status.

E2E scope highlighted: installed command through loading and conversion

The CLI uses Typer to parse the arguments, then loads the units and calls convert. A successful conversion writes one number to stdout, the normal output stream, and exits with code 0. Invalid conversions write an explanation to stderr, the error stream, and exit with code 1.

The command is registered in pyproject.toml:

[project.scripts]
units-convert = "unit_converter.cli:app"

The test in tests/e2e/test_cli.py exercises that installed entry point:

import shutil
import subprocess

import pytest


@pytest.mark.acceptance
def test_weather_conversion_from_terminal(tmp_path):
    command = shutil.which("units-convert")
    assert command is not None, "Install the project with uv sync --locked"

    result = subprocess.run(
        [command, "25", "C", "F"],
        cwd=tmp_path,
        capture_output=True,
        text=True,
        timeout=10,
        check=False,
    )

    assert result.returncode == 0, result.stderr
    assert result.stdout.strip() == "77"
    assert result.stderr == ""

shutil.which finds the command. subprocess.run starts it in a separate process. capture_output=True captures both streams, and text=True returns them as strings. check=False lets the assertions inspect a nonzero exit code; the timeout bounds how long the test waits for the running command.

Pytest supplies tmp_path, a fresh temporary directory. Running there checks that the command can find its JSON without relying on the repository as its working directory. The acceptance marker labels the test’s purpose; we’ll return to that distinction shortly.

uv run pytest tests/e2e -v

Expect 4 passed. The other cases check unknown symbols and incompatible dimensions. E2E tests can protect important failure paths as well as successful journeys.

These tests exercise the editable installation on this machine. They don’t establish that a release package includes its data or works on every operating system. The companion README has a separate built-wheel check for the packaging boundary.

06 / TRY THREE DEFECTS

See why one green test group isn’t enough.

Let’s change one responsibility at a time. Keep the tests unchanged, and restore each edit before trying the next.

Run these 3 commands after each temporary change:

uv run pytest tests/unit -v
uv run pytest tests/integration -v
uv run pytest tests/e2e -v

Break the calculation

In converter.py, temporarily remove + target.offset from the return statement:

return base_value * target.scale

Each test group reports 1 failed. All 3 exercise the broken calculation and expect 77, but it now returns 45. Restore + target.offset.

Break only the JSON setting

In units.json, change Fahrenheit’s "offset": 32 to "offset": 0.

The 10 unit cases still pass: they supply their own definitions. Integration and E2E each report 1 failed, because they read the changed file. Restore the JSON offset to 32.

Break only the output stream

In cli.py, change the final successful output to:

typer.echo(f"{result:g}", err=True)

The unit and integration groups pass. 1 E2E case fails: the number is correct, but it went to stderr instead of stdout. Restore typer.echo(f"{result:g}").

The formula defect causes failures at all three levels; the JSON defect affects integration and E2E; the output-stream defect affects only E2E

The pattern comes from these specific tests and defects. A broader test can miss a calculation bug if it never tries the relevant input. More scope gives it the opportunity to observe a problem; the scenario and assertions still need to expose it.

Finish by running uv run pytest -v and confirming 18 passed. We now have evidence for why all 3 boundaries are useful, rather than just different names for test folders.

07 / CHOOSE A USEFUL MIX

Use the testing pyramid as a starting point.

The testing pyramid suggests many focused tests, a smaller set of integration checks, and fewer complete workflows. Martin Fowler’s explanation frames the balance around the cost of broad tests and acknowledges that fast, reliable broad tests can change that tradeoff.

A testing pyramid with rule variations at the unit-test base, real connections in the integration layer, and selected E2E workflows at the top

Scope grows toward complete workflows

Moving upward includes more of the real application. Our unit test checks the calculation; integration adds the JSON and loader; E2E adds the installed command. That broader scope can reveal mistakes in how the parts connect.

Testing pyramid with an upward arrow from focused behavior toward a whole workflow, showing increasing scope

A wider boundary still covers only the inputs and assertions in that test. It doesn’t automatically check every calculation case.

Smaller tests usually run faster

Moving downward usually means less setup and fewer dependencies. A direct calculation call avoids starting a process or loading application data. That makes focused tests useful for quick feedback across many input variations.

Testing pyramid with a downward arrow toward faster execution, showing the usual speed trend from E2E to unit tests

This is a typical trend. Our local-file integration tests are also quick. Measure your suite: databases, networks, and test setup affect runtime more than the folder name.

For our converter, keep the many arithmetic variations close to convert. Use integration tests for representative conversions through the real definitions. Use E2E tests for the installed command’s success and failure behavior.

Some overlap is useful. Checking 25 C -> 77 F at each level tests the calculation, configuration, and command wiring. Repeating every arithmetic variation through a subprocess would add more work without necessarily answering a new question.

There is no required 70/20/10 ratio. A calculation library and a database-heavy service have different risks. Kent C. Dodds’ testing trophy emphasizes integration tests; it doesn’t propose making E2E the largest layer.

Which test should you write next?

Choose a boundary that includes the possible failure, then consider how quickly and clearly it reports the problem.

  • A new calculation rule: start with unit tests for its normal and edge cases. A failure gives you a small area to investigate.
  • A changed data format or database query: add an integration test through the real connection. Perfect replacement data can hide the mismatch you need to find.
  • A new user workflow: keep an E2E check through its entry point. It checks more wiring, so a failure may take more investigation.

Run fast, reliable checks on pull requests, including critical E2E workflows when practical. Larger browser or environment matrices can run separately.

08 / LEVEL AND PURPOSE

Separate how much a test runs from why you keep it.

Acceptance and regression describe purposes across different testing levels.

An acceptance test checks an agreed requirement. “Reject a conversion from length to mass” can be checked at the unit level. “A user can convert a temperature through the terminal” needs the command workflow. Both are acceptance checks in this companion.

A regression is when a change breaks behavior that previously worked. Suppose 77 F -> C correctly returns 25. Later, a refactor accidentally removes the source-offset subtraction. The conversion now gives the wrong answer. A regression test reruns that known case to catch the breakage.

Acceptance asks, “Does this meet the agreed requirement?” Regression asks, “Does this still work after a change?” The same test can serve both purposes: check the requirement initially, then protect that behavior as the code evolves.

This project uses directories for levels and pytest markers for selected purposes. The markers are registered in pyproject.toml:

uv run pytest -m acceptance -v
uv run pytest -m regression -v

The first command reports 2 passed, 16 deselected: one unit case and one E2E case. The second reports 3 passed, 15 deselected: the reverse-temperature cases. Those protect the source-offset subtraction; the README demonstrates a separate defect that they catch.

The markers select cases; they don’t determine everything a test can protect. Unmarked tests can still catch regressions.

09 / COMMON QUESTIONS

Common questions about testing levels.

How do testing levels, purposes, and approaches differ?

  • Level: what runs? Unit, integration, and E2E describe the test’s scope.
  • Purpose: why test it? Acceptance checks an agreed requirement; regression catches breakage after changes.
  • Approach: how do we develop? Test-driven development (TDD) guides implementation with failing tests. Behavior-driven development (BDD) uses shared examples to clarify expected behavior.

Are integration tests the same as end-to-end tests?

Integration tests check selected real components together. E2E tests follow a complete workflow from its external entry point. Here, loading the JSON and calling convert is an integration check; launching the installed command also checks argument handling, output, and exit status.

Is every browser test an E2E test?

No. A browser test with all backend responses replaced doesn’t verify the real frontend-backend connection. Likewise, an in-process CLI test can check parsing without checking that the installed executable starts. Describe the real components and boundaries instead of classifying by tool.

How does system testing differ from E2E testing?

System testing checks a defined complete system against its requirements. E2E testing follows a complete workflow across its participants. This standalone CLI fits both descriptions. In a larger product, a system test might stop at one service while an E2E workflow continues through other services.

Should you start with unit tests or E2E tests on legacy code?

Start where you can protect an important behavior reliably. A few broad checks may help when tightly coupled code is hard to test in isolation. As the code becomes easier to change, add focused tests for rules and integration checks for risky connections. The first tests you write don’t dictate the mix you keep forever.

Does AI make unit and integration tests unnecessary?

No. AI can help author tests, but a generated E2E test still has to run the workflow and provide a useful failure. It doesn’t remove process startup, environment setup, or investigation costs.

Give the agent the expected result from a requirement. Copying the program’s current output into an assertion can preserve a bug. On legacy code, recording existing behavior can help detect changes, but review that behavior before treating it as correct. The guide to writing useful pytest tests with AI covers that review process.

Takeaway: choose the boundary that can expose the mistake

We saw a formula defect fail all 3 groups, a configuration defect leave unit tests green, and an output defect appear only through the command. Each level contributed evidence the others couldn’t supply on their own.

For your next change, name one plausible failure. Choose a test that reaches it, state the expected result, and check that the test can tell a correct result from a broken one. Then add broader checks for responsibilities outside that boundary.

Build a practical test suite with the Pytest Python test automation course.

View course