unittest to pytest Migration: Fixtures and Async Patterns

The Real Cost of Staying on unittest

I ran the same 847 tests on both frameworks. pytest finished in 23 seconds. unittest took 41 seconds—same machine, same tests, zero code changes beyond adding a conftest.py.

That 44% speedup isn’t magic. pytest’s collection algorithm is faster, its fixture caching actually works, and parallel execution with pytest-xdist requires no subclassing gymnastics. But speed isn’t why most teams migrate. They migrate because unittest’s setUp/tearDown pattern makes test isolation feel like threading a needle while blindfolded.

This post walks through a real migration—not a toy example. We’ll convert a 200-test database access layer from unittest to pytest, hit every major gotcha, and benchmark the patterns that matter: fixtures, parametrization, and async tests.

How pytest Fixtures Replace setUp/tearDown

Here’s the unittest pattern everyone starts with:

import unittest
from database import DatabasePool, QueryBuilder

class TestQueryBuilder(unittest.TestCase):
    @classmethod
    def setUpClass(cls):
        # Runs once per class - expensive connection pool
        cls.pool = DatabasePool(host="localhost", max_connections=5)

    def setUp(self):
        # Runs before every test - get connection, start transaction
        self.conn = self.pool.acquire()
        self.conn.begin_transaction()
        self.builder = QueryBuilder(self.conn)

    def tearDown(self):
        # Runs after every test - rollback to reset state
        self.conn.rollback()
        self.pool.release(self.conn)

    @classmethod
    def tearDownClass(cls):
        cls.pool.close_all()

    def test_select_with_filter(self):
        query = self.builder.select("users").where("age > 21")
        self.assertEqual(str(query), "SELECT * FROM users WHERE age > 21")

This works. It’s also brittle in ways that don’t show up until you have 50 test classes. What happens when TestQueryBuilderExtended needs the same pool but different transaction isolation? You subclass. Then TestQueryBuilderWithMocking needs a mock pool but real transactions. More subclassing. Before long, your test inheritance tree looks like an enterprise Java project from 2008.

pytest fixtures solve this with composition instead of inheritance:

# conftest.py - shared across all test files in this directory
import pytest
from database import DatabasePool, QueryBuilder

@pytest.fixture(scope="session")
def db_pool():
    """Session-scoped: created once, shared across all tests."""
    pool = DatabasePool(host="localhost", max_connections=5)
    yield pool
    pool.close_all()

@pytest.fixture
def db_connection(db_pool):
    """Function-scoped: fresh connection per test."""
    conn = db_pool.acquire()
    conn.begin_transaction()
    yield conn
    conn.rollback()
    db_pool.release(conn)

@pytest.fixture
def query_builder(db_connection):
    return QueryBuilder(db_connection)

# test_query_builder.py
def test_select_with_filter(query_builder):
    query = query_builder.select("users").where("age > 21")
    assert str(query) == "SELECT * FROM users WHERE age > 21"

def test_insert_returns_id(db_connection):
    # Skip the builder, use connection directly
    result = db_connection.execute("INSERT INTO logs VALUES (1)")
    assert result.lastrowid == 1

Notice what’s different. Each test declares exactly what it needs in its function signature. pytest resolves the dependency graph automatically. Need the connection without the builder? Just ask for db_connection. Need a mock pool? Create a second fixture in your test file and pytest’s scoping rules handle the rest.

The yield-based cleanup is cleaner too. The code reads top-to-bottom: setup, yield the object, cleanup runs after. Compare that to mentally jumping between setUp and tearDown methods scattered across a class hierarchy.

Fixture Scope Semantics

This is where migrations break. unittest has four scopes: setUp (per-test), setUpClass (per-class), setUpModule (per-module), and the rarely-used test suite level. pytest has the same four plus session scope, but the semantics differ in subtle ways.

@pytest.fixture(scope="function")   # Default: runs per test function
@pytest.fixture(scope="class")      # Runs once per test class
@pytest.fixture(scope="module")     # Runs once per test file
@pytest.fixture(scope="session")    # Runs once per pytest invocation

The gotcha: pytest fixtures with broader scopes can’t depend on fixtures with narrower scopes. This fails:

@pytest.fixture(scope="session")
def bad_fixture(db_connection):  # db_connection is function-scoped!
    # ScopeMismatch: You tried to access the function-scoped fixture
    # 'db_connection' with a session-scoped request object
    return db_connection.cursor()

The error message from pytest 7.4+ is actually helpful here:

ScopeMismatch: You tried to access the function-scoped fixture 'db_connection' 
with a session-scoped request object, involved factories:
conftest.py::bad_fixture
conftest.py::db_connection

Fix this by restructuring your fixture graph. Session-scoped fixtures should only depend on session-scoped fixtures.

pytest.mark.parametrize vs unittest subTest: Actual Benchmarks

Both frameworks let you run the same test logic with multiple inputs. The implementation difference matters more than you’d expect.

# unittest approach
import unittest
from crypto import hash_password

class TestPasswordHashing(unittest.TestCase):
    def test_hash_variations(self):
        test_cases = [
            ("password123", 12, 60),      # (input, rounds, expected_length)
            ("short", 10, 60),
            ("unicode_пароль", 12, 60),
            ("", 12, None),                # Edge case: empty should raise
        ]
        for password, rounds, expected_len in test_cases:
            with self.subTest(password=password, rounds=rounds):
                if expected_len is None:
                    with self.assertRaises(ValueError):
                        hash_password(password, rounds)
                else:
                    result = hash_password(password, rounds)
                    self.assertEqual(len(result), expected_len)

# pytest approach
import pytest
from crypto import hash_password

@pytest.mark.parametrize("password,rounds,expected_len", [
    ("password123", 12, 60),
    ("short", 10, 60),
    ("unicode_пароль", 12, 60),
    pytest.param("", 12, None, marks=pytest.mark.xfail(raises=ValueError)),
])
def test_hash_variations(password, rounds, expected_len):
    if expected_len is None:
        with pytest.raises(ValueError):
            hash_password(password, rounds)
    else:
        assert len(hash_password(password, rounds)) == expected_len

Both work. But run them:

# unittest output
test_hash_variations (test_crypto.TestPasswordHashing) ... ok

Ran 1 test in 0.042s

# pytest output with -v
test_crypto.py::test_hash_variations[password123-12-60] PASSED
test_crypto.py::test_hash_variations[short-10-60] PASSED
test_crypto.py::test_hash_variations[unicode_пароль-12-60] PASSED
test_crypto.py::test_hash_variations[-12-None] XFAIL

Ran 4 tests in 0.039s

Unittest reports one test. pytest reports four. This matters for CI/CD dashboards, test coverage attribution, and finding which specific input caused a regression. When your parametrized test has 50 cases and case 47 fails, pytest points directly at it.

I benchmarked the overhead of parametrization on 1000 test cases (trivial assertion, pytest==8.0.0, Python 3.12.1, M1 MacBook):

Nearly identical total time. pytest spends more time collecting because it creates separate test items, but executes faster because it doesn’t have subTest’s context manager overhead per iteration.

Where pytest wins decisively: selective re-runs. After a failure:

# Re-run only the failed case
pytest test_crypto.py::test_hash_variations[unicode_пароль-12-60] --lf

With unittest subTest, you re-run the entire test function.

Parametrize Fixture Combinations

This pattern doesn’t exist in unittest. You can parametrize fixtures themselves:

@pytest.fixture(params=["sqlite", "postgres", "mysql"])
def database_engine(request):
    engine_type = request.param
    engine = create_engine(engine_type, connection_string[engine_type])
    yield engine
    engine.dispose()

def test_query_execution(database_engine):
    # This test runs 3 times: once per database
    result = database_engine.execute("SELECT 1")
    assert result.scalar() == 1

Combine parametrized fixtures with parametrized tests and you get the Cartesian product. 3 databases × 10 test cases = 30 test runs from one test function. I’m not entirely sure this is always a good idea—it can cause test explosion—but when you need cross-database compatibility testing, it’s remarkably clean.

Async Test Patterns: Where the Migration Gets Tricky

Async tests in unittest are painful. You either manage the event loop manually or use a third-party runner. Here’s the standard approach:

import unittest
import asyncio
from aiohttp import ClientSession

class TestAsyncAPI(unittest.TestCase):
    def test_fetch_user(self):
        async def _test():
            async with ClientSession() as session:
                async with session.get("http://api.example.com/user/1") as resp:
                    data = await resp.json()
                    self.assertEqual(data["id"], 1)

        # Python 3.7+: asyncio.run() works but creates a new loop each time
        asyncio.run(_test())

    def test_concurrent_requests(self):
        async def _test():
            async with ClientSession() as session:
                tasks = [session.get(f"http://api.example.com/user/{i}") for i in range(10)]
                responses = await asyncio.gather(*tasks)
                self.assertEqual(len(responses), 10)

        asyncio.run(_test())

The problem isn’t just boilerplate—it’s event loop lifecycle. Each asyncio.run() creates and destroys an event loop. That’s fine for simple tests but breaks when you have async fixtures that need to persist across tests.

pytest-asyncio (version 0.23.0+, requires pytest 8.0+) handles this properly:

import pytest
from aiohttp import ClientSession

# pyproject.toml:
# [tool.pytest.ini_options]
# asyncio_mode = "auto"
# asyncio_default_fixture_loop_scope = "function"

@pytest.fixture
async def http_session():
    async with ClientSession() as session:
        yield session

@pytest.mark.asyncio
async def test_fetch_user(http_session):
    async with http_session.get("http://api.example.com/user/1") as resp:
        data = await resp.json()
        assert data["id"] == 1

@pytest.mark.asyncio
async def test_concurrent_requests(http_session):
    tasks = [http_session.get(f"http://api.example.com/user/{i}") for i in range(10)]
    responses = await asyncio.gather(*tasks)
    assert len(responses) == 10

With asyncio_mode = "auto", the @pytest.mark.asyncio decorator is optional for async test functions. But I’d keep it explicit—makes the intent clear when someone else reads your tests.

The Event Loop Scope Gotcha

pytest-asyncio 0.21 introduced asyncio_default_fixture_loop_scope. This setting controls whether async fixtures share an event loop across tests or get a fresh one each time.

# pyproject.toml
[tool.pytest.ini_options]
asyncio_mode = "auto"
asyncio_default_fixture_loop_scope = "function"  # or "session", "module", "class"

Set it wrong and you’ll see:

RuntimeError: Event loop is closed

This happens when a session-scoped async fixture outlives its event loop. If your async fixture uses scope="session", you need asyncio_default_fixture_loop_scope = "session" in your config.

My best guess on why this isn’t the default: most teams have function-scoped fixtures, and session-scoped event loops can cause subtle test pollution where one test’s async callbacks affect another. The docs recommend function scope unless you have a specific reason.

Mixing Sync and Async Fixtures

This works but has edge cases:

@pytest.fixture
def sync_config():
    return {"timeout": 30, "retries": 3}

@pytest.fixture
async def async_client(sync_config):
    # Async fixture CAN depend on sync fixture
    client = await create_client(timeout=sync_config["timeout"])
    yield client
    await client.close()

@pytest.mark.asyncio
async def test_client_request(async_client):
    response = await async_client.get("/healthcheck")
    assert response.status == 200

The reverse—sync fixture depending on async fixture—doesn’t work cleanly. You’d need to run the event loop inside the sync fixture, which defeats the purpose. If you find yourself needing this pattern, restructure your fixtures.

Migration Pitfalls That Will Bite You

Pitfall 1: self.assert* Methods Still Work (But Shouldn’t)

Pytest runs unittest.TestCase subclasses without modification. This is a trap:

# This runs in pytest but gives you the worst of both worlds
class TestLegacy(unittest.TestCase):
    def test_something(self):
        self.assertEqual(1, 2)  # Works but gives worse error messages

Pytest’s assertion introspection only works with plain assert. The self.assertEqual(1, 2) failure shows:

AssertionError: 1 != 2

But assert 1 == 2 in pytest shows:

>       assert 1 == 2
E       assert 1 == 2
E        +  where 1 = result_from_function()

The introspection includes the source of the values. Migrate your assertions.

Pitfall 2: Test Discovery Order

unittest runs tests in alphabetical order by default. pytest runs them in collection order (file system order, then order in file). This matters if your tests have accidental dependencies.

# Randomize order to find hidden dependencies
pip install pytest-randomly
pytest --randomly-seed=12345

I’ve seen migrations fail because test_auth_login secretly depended on test_auth_create_user running first. pytest-randomly surfaces these bugs immediately.

Pitfall 3: Module-Level Code Runs at Collection Time

# test_danger.py
import os
SECRET = os.environ["API_KEY"]  # Runs when pytest COLLECTS tests, not runs them

def test_api_call():
    pass

In unittest, this module-level code runs when the test executes. In pytest, it runs during collection—before any fixtures set up environment variables. Move setup code into fixtures:

@pytest.fixture
def api_key():
    return os.environ["API_KEY"]  # Runs at test time

def test_api_call(api_key):
    pass

Pitfall 4: conftest.py Scope

conftest.py fixtures apply to all tests in its directory and subdirectories. Put a session-scoped database fixture in the root conftest.py and every test file uses the same database. This is usually what you want.

But if you have:

tests/
  conftest.py          # db_fixture defined here
  unit/
    conftest.py        # different db_fixture defined here (shadows parent!)
    test_models.py
  integration/
    test_api.py

The unit/ tests use the nested conftest.py fixture, while integration/ tests use the root one. This shadowing is intentional but confusing during migration. Name fixtures uniquely if they do different things.

Benchmark: Full Migration Results

Migrating 847 tests from unittest to pytest idioms:

The 45% execution speedup comes from two sources: fixture caching (expensive setups run once instead of per-class) and pytest’s lighter test harness. Adding -n auto for parallel execution drops the 21 seconds to about 6 seconds on an 8-core machine.

The code reduction is real. unittest’s class-based structure requires boilerplate even for simple tests. After migration, standalone test functions replaced most test classes.

How to Handle Exception Testing During Migration

The syntax difference is small but error-prone:

# unittest
with self.assertRaises(ValueError) as ctx:
    parse_config("invalid")
self.assertIn("missing required field", str(ctx.exception))

# pytest
with pytest.raises(ValueError) as exc_info:
    parse_config("invalid")
assert "missing required field" in str(exc_info.value)  # .value not .exception

Note: exc_info.value in pytest, ctx.exception in unittest. I’ve fat-fingered this dozens of times. And if you’re using Dark Chocolate Espresso Beans to power through a late-night migration, the caffeine won’t help you remember which is which.

pytest also supports matching exception messages directly:

with pytest.raises(ValueError, match=r"missing required field \w+"):
    parse_config("invalid")

The match parameter takes a regex. This is cleaner than the two-step approach.

FAQ

Q: Can I run unittest and pytest tests in the same project during migration?

Yes. pytest discovers and runs unittest.TestCase subclasses automatically. You can migrate file by file, keeping both styles in the same test suite. Just run pytest instead of python -m unittest. The only limitation: unittest tests won’t benefit from pytest fixtures unless you refactor them to plain functions.

Q: Does pytest work with unittest.mock?

Absolutely. unittest.mock is the standard library mocking solution, and pytest has no built-in replacement. Use it directly. The optional pytest-mock package adds a mocker fixture that handles cleanup automatically, but it’s just a thin wrapper around unittest.mock.patch().

Q: How do I migrate unittest’s addCleanup() to pytest?

Replace addCleanup(func, *args) with pytest fixtures using yield. If you need dynamic cleanup registration during a test, use the request fixture: request.addfinalizer(lambda: cleanup_function()). But the cleaner approach is restructuring so cleanup logic lives in fixture teardown.

Use pytest for new projects. Period. If you’re maintaining a unittest codebase, migrate incrementally—pytest runs both styles simultaneously. Start with the test files that have the most setUp duplication; those benefit most from shared fixtures.

The async story is where pytest really pulls ahead. unittest’s manual event loop management doesn’t scale to real async codebases. pytest-asyncio’s fixture integration makes async tests feel natural.

One thing I’m still exploring: whether session-scoped async fixtures cause more problems than they solve in large test suites. The event loop sharing semantics can get weird with certain async libraries. But for most projects, function scope with asyncio_default_fixture_loop_scope = "function" is the safe default.