Testing

Test Fixtures Best Practices: Structure, Scope, and Isolation

HelpMeTest

HelpMeTest

— 5 min read
Test Fixtures Best Practices: Structure, Scope, and Isolation

Test fixtures are the foundation every test stands on. Write them well and your tests are fast, isolated, and easy to debug. Write them carelessly and you'll spend more time fixing tests than writing code.

This guide covers the principles and patterns that separate reliable fixtures from the ones that make everyone afraid to touch the test suite.

What Is a Test Fixture?

A fixture is anything that establishes the known state a test needs to run. That can mean:

  • A JSON file with user records loaded before tests run
  • A beforeEach function that creates database entries
  • A set of objects instantiated at the top of a test file
  • A pytest fixture function decorated with @pytest.fixture

The word "fixture" gets used for all of these. What they share: they define preconditions — the state of the world at the moment a test begins.

Scope Is Everything

The most important decision for any fixture is its scope — how long it lives and what it's shared with.

Test-Scoped (Per-Test)

The fixture is created fresh for every individual test and torn down afterward.

# pytest
@pytest.fixture
def user(db):
    u = User.objects.create(email='test@example.com', role='user')
    yield u
    u.delete()

Use when: Tests modify the fixture. Tests must not affect each other. You need guaranteed isolation.

Cost: Higher — fixture setup runs N times for N tests.

Module-Scoped (Per-File)

The fixture is created once for all tests in a file, then torn down.

@pytest.fixture(scope='module')
def admin_user(db):
    return User.objects.create(email='admin@example.com', role='admin')

Use when: Tests only read the fixture, never modify it. Setup is expensive (e.g., populating a large dataset).

Risk: One test mutating the fixture breaks all following tests in the file.

Session-Scoped (Entire Suite)

The fixture is created once, shared across all tests.

@pytest.fixture(scope='session')
def django_db_setup():
    # Called once; database lives for the whole test session
    pass

Use when: Setting up infrastructure (database connections, external services, test servers).

Never use for: Data fixtures that tests might modify.

The Isolation Principle

Fixtures must not leak state between tests. This is the rule that everything else flows from.

Transaction Rollback (The Standard Pattern)

Wrap each test in a transaction that rolls back. Tests can create, modify, and delete records freely — it all disappears when the test ends.

# Django
@pytest.fixture
def db_with_rollback(db):
    with transaction.atomic():
        savepoint = transaction.savepoint()
        yield
        transaction.savepoint_rollback(savepoint)
// Jest + TypeORM
beforeEach(async () => {
  queryRunner = dataSource.createQueryRunner();
  await queryRunner.startTransaction();
});

afterEach(async () => {
  await queryRunner.rollbackTransaction();
  await queryRunner.release();
});

This is the fastest isolation mechanism. No truncation, no reseed — the database engine undoes everything.

Limitation: Doesn't work if your code under test commits transactions. In that case, use truncate-and-reseed.

Truncate and Reseed

After each test (or suite), truncate the affected tables and reload fixture data.

afterEach(async () => {
  await db.query('TRUNCATE TABLE users, orders, products RESTART IDENTITY CASCADE');
  await loadFixtures();
});

Slower than rollback, but works with any code regardless of transaction behavior.

Unique Data Per Test

For tests that can't use transaction rollback, generate unique values to avoid conflicts:

const testId = Date.now();
const user = await createUser({ email: `user-${testId}@example.com` });

This prevents collision when tests run in parallel against a shared database.

Fixture Files vs. Programmatic Fixtures

When Fixture Files Work

Static fixture files (JSON, YAML, SQL) are appropriate when:

  • The dataset is small and stable
  • You need the same specific records across many tests
  • The data represents reference/lookup tables (countries, currency codes, etc.)
# fixtures/roles.yaml
- name: admin
  permissions: [read, write, delete, manage_users]
- name: editor  
  permissions: [read, write]
- name: viewer
  permissions: [read]

When Fixture Files Break Down

Fixture files become a liability when:

  • Tests need variations of the same object
  • The schema changes — every file needs updating
  • Tests become coupled to specific IDs in the fixture
  • Files grow to hundreds of records and no one knows what's actually needed

At that point, switch to programmatic fixtures.

Programmatic Fixtures

Code that constructs data is more flexible and stays in sync with schema changes automatically:

async function createUserFixture({ role = 'user', ...overrides } = {}) {
  return User.create({
    email: faker.internet.email(),
    name: faker.person.fullName(),
    role,
    ...overrides,
  });
}

When your User model gains a required timezone field, you update one factory function — not 30 JSON files.

Naming Conventions

Fixture names should describe the state, not the test:

# Bad — names tied to specific tests
@pytest.fixture
def user_for_login_test():
    ...

@pytest.fixture
def user_for_settings_test():
    ...

# Good — names describe the state
@pytest.fixture
def authenticated_user():
    ...

@pytest.fixture
def admin_user():
    ...

@pytest.fixture
def user_with_expired_subscription():
    ...

Tests can then compose what they need:

def test_admin_can_delete_users(admin_user, regular_user):
    ...

def test_settings_visible_to_authenticated_users(authenticated_user):
    ...

Fixture Composition

Complex scenarios are built by composing simple fixtures, not by creating monolithic setup blocks.

@pytest.fixture
def user(db):
    return User.objects.create(email='user@example.com')

@pytest.fixture
def subscription(user):
    return Subscription.objects.create(user=user, plan='pro', status='active')

@pytest.fixture
def invoice(subscription):
    return Invoice.objects.create(subscription=subscription, amount=100)

# Test uses the full chain
def test_invoice_linked_to_user(invoice):
    assert invoice.subscription.user.email == 'user@example.com'

Each fixture is independently testable and reusable. Tests declare exactly what they need.

Avoid These Patterns

Fixture Inheritance Chains That Are Too Deep

Three levels of composition is usually fine. Six levels makes debugging a nightmare.

# Reasonable
def test_checkout(user, cart, cart_with_items):
    ...

# Excessive — what state are we actually in?
def test_checkout(tenant, org, user_in_org, subscription_for_org, 
                  cart, cart_with_items, promo_code_applied):
    ...

If you need this many fixtures, consider a single checkout_scenario fixture that sets up everything.

Fixtures That Depend on Order

Tests within a file should be runnable in any order. If Test B assumes Test A ran first, you have a problem:

# Bad — relies on state from a previous test
def test_create_user():
    user = User.objects.create(email='test@example.com')
    assert user.id is not None

def test_find_user():
    # Assumes the user from test_create_user exists
    user = User.objects.get(email='test@example.com')
    assert user is not None

Fix: each test sets up its own preconditions.

Overloaded Shared Fixtures

A fixture used by 50 tests that everyone modifies slightly is a shared mutable state trap:

# This fixture is "convenient" but dangerous
@pytest.fixture(scope='module')
def user(db):
    u = User.objects.create(email='test@example.com')
    return u

# Test A modifies it
def test_update_email(user):
    user.email = 'new@example.com'
    user.save()

# Test B now sees the modified version
def test_user_email_format(user):
    # Fails because email was changed by Test A
    assert '@example.com' in user.email

Fix: use test-scoped fixtures for anything tests might modify.

Fixtures in Different Frameworks

Jest (JavaScript)

// Global setup
beforeAll(async () => {
  await db.migrate();
  testUsers = await User.bulkCreate([
    { email: 'alice@example.com', role: 'admin' },
    { email: 'bob@example.com', role: 'user' },
  ]);
});

// Per-test setup
beforeEach(async () => {
  testOrder = await Order.create({ userId: testUsers[0].id, status: 'pending' });
});

// Cleanup
afterEach(async () => {
  await Order.destroy({ where: {} });
});

afterAll(async () => {
  await User.destroy({ where: {} });
  await db.close();
});

pytest (Python)

import pytest
from myapp.models import User, Order

@pytest.fixture(scope='session')
def django_db_setup(django_db_setup, django_test_environment):
    pass

@pytest.fixture
def admin_user(db):
    return User.objects.create_user(
        username='admin',
        email='admin@example.com',
        is_staff=True
    )

@pytest.fixture
def pending_order(db, admin_user):
    return Order.objects.create(
        user=admin_user,
        status='pending',
        total=99.99
    )

RSpec (Ruby)

RSpec.describe Order do
  let(:user) { create(:user) }
  let(:order) { create(:order, user: user, status: 'pending') }
  
  context 'when order is cancelled' do
    let(:cancelled_order) { create(:order, user: user, status: 'cancelled') }
    
    it 'cannot be reinstated' do
      expect(cancelled_order.reinstate).to eq(false)
    end
  end
end

Testing the Fixtures Themselves

If a fixture is complex enough to get wrong, write a sanity check:

def test_admin_user_fixture_has_correct_permissions(admin_user):
    assert admin_user.role == 'admin'
    assert admin_user.can_manage_users is True
    assert admin_user.is_active is True

This takes one minute to write and prevents an entire class of "the fixture was wrong and 20 tests silently passed for the wrong reason" bugs.

Summary

Good fixtures are:

  • Scoped correctly — per-test for anything mutable, broader only for read-only data
  • Isolated — each test starts clean, finishes clean
  • Named for state — admin_user, not user_for_admin_test
  • Composed, not duplicated — build complex scenarios from simple pieces
  • Schema-resilient — programmatic fixtures update in one place

The fixture layer is infrastructure. Invest in getting it right and the rest of your test suite becomes dramatically easier to write and maintain.

Read more