Skip to content

pytest-uuid

pytest-uuid logo

A pytest plugin for mocking UUID generation in your tests. Supports uuid1, uuid3, uuid4, uuid5, uuid6, uuid7, and uuid8.

PyPI version License: MIT Tests codecov

Features

  • Mock all UUID versions: uuid1, uuid3, uuid4, uuid5, uuid6, uuid7, uuid8
  • Works with both import uuid and from uuid import uuid4 patterns
  • Multiple ways to mock: static, sequence, seeded, or node-seeded
  • Decorator, marker, and fixture APIs (inspired by freezegun)
  • Configurable exhaustion behavior for sequences
  • Ignore list for packages that should use real UUIDs
  • Spy mode to track calls without mocking
  • Detailed call tracking with caller module/file info
  • Automatic cleanup after each test
  • Zero configuration required - just use the fixture
  • uuid6/uuid7/uuid8 support via uuid6 backport (Python < 3.14)

Quick Example

import uuid

def test_single_uuid(mock_uuid):
    mock_uuid.uuid4.set("12345678-1234-4678-8234-567812345678")
    assert str(uuid.uuid4()) == "12345678-1234-4678-8234-567812345678"

def test_multiple_uuids(mock_uuid):
    mock_uuid.uuid4.set(
        "11111111-1111-4111-8111-111111111111",
        "22222222-2222-4222-8222-222222222222",
    )
    assert str(uuid.uuid4()) == "11111111-1111-4111-8111-111111111111"
    assert str(uuid.uuid4()) == "22222222-2222-4222-8222-222222222222"

Installation

pip install pytest-uuid

# or with uv
uv add pytest-uuid

Next Steps