Best Practices for UUID Generators in Testing

Challenges of UUID Usage in Testing

Using UUID in testing faces several unique challenges: randomness causing test instability — if test assertions depend on specific UUID values, different UUIDs generated each run will cause snapshot tests to fail; test data management — large numbers of random UUIDs make test data difficult to track and reproduce; isolation in concurrent tests — when multiple concurrent tests share a database, UUIDs generated by different tests need proper isolation; debugging difficulty — random UUIDs in logs are hard to correlate to specific test cases.

Fixed UUIDs: Making Tests Reproducible

For tests requiring stability, use fixed (hardcoded) UUIDs rather than randomly generated ones: define a set of known UUIDs in test constant files, use these constants in test fixtures and mocks; use UUID v5 to derive deterministic UUIDs from test names or sequence numbers (same test always produces same UUID, and different tests have different UUIDs); in unit tests, mock UUID generation functions to return fixed values, allowing testing of downstream logic.

# Python 测试常量文件 (test_constants.py)
import uuid

# 固定的测试 UUID（不要随机生成）
USER_UUID_1 = uuid.UUID('00000000-0000-4000-8000-000000000001')
USER_UUID_2 = uuid.UUID('00000000-0000-4000-8000-000000000002')
ORDER_UUID_1 = uuid.UUID('00000000-0000-4000-8000-000000000101')
ORDER_UUID_2 = uuid.UUID('00000000-0000-4000-8000-000000000102')

# 或使用 v5 从名称派生（每次结果相同）
TEST_NAMESPACE = uuid.UUID('12345678-0000-0000-0000-000000000000')

def test_uuid(name: str) -> uuid.UUID:
    """从测试名称派生确定性 UUID"""
    return uuid.uuid5(TEST_NAMESPACE, name)

USER_1_ID = test_uuid('user-1')   # 每次运行结果相同
ORDER_1_ID = test_uuid('order-1') # 不同名称产生不同 UUID

Mocking UUID Generators

# Python + pytest：mock uuid4
from unittest.mock import patch
import uuid
import pytest

def create_user():
    user_id = uuid.uuid4()  # 生产代码中的 UUID 生成
    return {'id': str(user_id), 'name': 'Alice'}

def test_create_user_with_fixed_uuid():
    fixed_uuid = uuid.UUID('12345678-1234-4321-8000-000000000001')

    with patch('uuid.uuid4', return_value=fixed_uuid):
        user = create_user()
        assert user['id'] == '12345678-1234-4321-8000-000000000001'
        # 现在可以对确定的 UUID 值做断言

# Jest (JavaScript)：
# jest.mock('crypto', () => ({
#   randomUUID: jest.fn().mockReturnValue('12345678-1234-4321-8000-000000000001')
# }));

UUID Data Isolation in Integration Tests

# 使用唯一前缀隔离不同测试的数据
import uuid
import pytest

class TestPrefix:
    """为每个测试运行生成唯一前缀，避免测试间数据污染"""

    def __init__(self):
        # 每次测试运行有唯一 ID
        self.run_id = str(uuid.uuid4())[:8]

    def make_uuid(self, entity_type: str, num: int) -> str:
        """生成带前缀的 UUID，方便追踪测试数据"""
        # 格式：{run_id}-{entity}-{num:04d}-...
        # 用于在数据库中区分不同测试运行的数据
        seed = f"{self.run_id}-{entity_type}-{num}"
        namespace = uuid.UUID('00000000-0000-0000-0000-000000000000')
        return str(uuid.uuid5(namespace, seed))

@pytest.fixture
def test_prefix():
    return TestPrefix()

def test_create_multiple_users(test_prefix, db):
    users = []
    for i in range(5):
        user_id = test_prefix.make_uuid('user', i)
        users.append({'id': user_id, 'name': f'User {i}'})

    db.insert_many('users', users)
    # 断言...
    # 测试结束后可以用 run_id 前缀清理数据

Handling UUID in Snapshot Tests

# pytest-snapshot 中处理随机 UUID
import re

def normalize_uuids(text: str) -> str:
    """将文本中所有 UUID 替换为占位符，使快照稳定"""
    uuid_pattern = r'[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}'
    return re.sub(uuid_pattern, '<UUID>', text, flags=re.IGNORECASE)

def test_api_response_snapshot(client, snapshot):
    response = client.get('/api/users')
    # 规范化 UUID 后再做快照对比
    normalized = normalize_uuids(response.json())
    snapshot.assert_match(normalized, 'users_response')

# Jest + inline snapshot
# expect(response.body).toMatchInlineSnapshot(`
#   {
#     "id": "<UUID>",  // 使用 serializer 替换 UUID
#     "name": "Alice",
#   }
# `)

# 使用 jest-serializer-regex 或自定义 serializer
# expect.addSnapshotSerializer({
#   test: (val) => typeof val === 'string' && /^[0-9a-f-]{36}$/.test(val),
#   print: () => '"<UUID>"'
# });

Generating UUID Sets for Testing

# 为不同测试场景准备 UUID 工具
import uuid
from typing import Iterator

def uuid_counter(start: int = 1) -> Iterator[str]:
    """生成顺序排列的可读 UUID（方便调试）"""
    # 格式：00000000-0000-4000-8000-{num:012x}
    num = start
    while True:
        yield f'00000000-0000-4000-8000-{num:012x}'
        num += 1

# 使用
gen = uuid_counter()
id1 = next(gen)  # 00000000-0000-4000-8000-000000000001
id2 = next(gen)  # 00000000-0000-4000-8000-000000000002

# 批量准备测试数据
def make_test_users(count: int) -> list:
    gen = uuid_counter()
    return [
        {'id': next(gen), 'name': f'Test User {i}', 'email': f'user{i}@test.com'}
        for i in range(1, count + 1)
    ]

# 测试中使用
users = make_test_users(10)
print(users[0])  # {'id': '00000000-...001', 'name': 'Test User 1', ...}

UUID Strategy in E2E Tests

In end-to-end (E2E) tests, UUID handling strategy differs from unit tests: E2E tests typically interact with real systems, with UUIDs actually generated by the system; tests should extract UUIDs from API responses and use them in subsequent requests (rather than hardcoding); in Cypress or Playwright, pass UUIDs through variables: first POST to create a resource and obtain UUID, then use that UUID for subsequent operations; test assertions should check UUID format (whether valid) rather than specific values (which differ each run); when cleaning up database data before and after tests, use timestamp prefixes or specific fields (like is_test_data=true) to identify test data for batch cleanup.