Testing with Lexigram

Overview

Lexigram's DI container makes testing straightforward: fake at the contract boundary, use TestEnvironment for isolation, and use stub() modules for full integration tests.

TestEnvironment

from lexigram.testing import TestEnvironment
from lexigram.testing.fakes import FakeCache
from lexigram.contracts.infra.cache import CacheBackendProtocol

async def test_user_service():
    # extra_registrations is a callable receiving the container
    env = TestEnvironment(
        extra_registrations=lambda c: c.singleton(
            CacheBackendProtocol, instance=FakeCache()
        )
    )
    await env.setup()
    service = await env.container.resolve(UserService)
    result = await service.get_user("user-123")
    assert result.is_ok()
    await env.teardown()

Each TestEnvironment is fully isolated — no global state pollution.

Module Stubs

@module(imports=[
    LLMModule.stub(),       # No-op LLM
    EventsModule.stub(),    # In-memory events
    DatabaseModule.stub(),  # In-memory DB
])
class TestModule(Module): pass

async def test_with_modules():
    async with Application.boot(modules=[TestModule]) as app:
        service = await app.container.resolve(MyService)
        result = await service.process()
        assert result.is_ok()

Every extension package should define stub() returning a DynamicModule with in-memory/noop backends.

Testing Result-Returning Methods

@pytest.mark.asyncio
async def test_find_user_returns_ok():
    result = await service.find_user("user-123")
    assert result.is_ok()
    assert result.unwrap().id == "user-123"

@pytest.mark.asyncio
async def test_find_user_returns_err():
    result = await service.find_user("nonexistent")
    assert result.is_err()
    assert isinstance(result.unwrap_err(), UserNotFound)

Ambient Clock Override

from datetime import UTC, datetime
from lexigram.testing import FixedClock
from lexigram.primitives import clock

# FixedClock requires a timezone-aware datetime
with clock.use(FixedClock(datetime(2026, 1, 1, tzinfo=UTC))):
    assert clock.now().year == 2026

Test Organization

# tests/test_user_service.py
class TestUserService:
    @pytest.fixture
    def mock_db(self) -> AsyncMock:
        db = AsyncMock(spec=DatabaseProviderProtocol)
        db.execute = AsyncMock(return_value=[])
        return db

    @pytest.mark.asyncio
    async def test_create_user(self, mock_db: AsyncMock) -> None:
        service = UserService(db=mock_db)
        user = await service.create(email="test@example.com")
        assert user.id is not None
        mock_db.execute.assert_awaited_once()

Conventions

• Files: test_*.py
• Classes: Test*
• Methods: test_*
• Fakes at contract boundary — mock Protocol, not internals
• No global state — each test is independent
• Mock clients in tests/, never in src/

Running Tests

uv run pytest                          # Full suite
uv run pytest -m "not integration"     # Unit-only
uv run pytest -m integration           # Integration only
uv run pytest lexigram-web/tests/      # Single package
uv run pytest -k "test_user"           # Pattern match
uv run pytest --cov --cov-report=html  # Coverage
uv run pytest --cov-fail-under=80      # Coverage gate

Pytest Markers

Defined in root pyproject.toml: integration, slow, unit, e2e, scenario, performance, plus requires_* markers: redis, postgres, elasticsearch, meilisearch, rabbitmq, smtp, kafka, minio, mongodb, qdrant, neo4j.

Common Mistakes

• Testing with real infrastructure (DB, Redis) for unit tests — use stubs
• Forgetting @pytest.mark.asyncio on async tests
• Mocking implementation details instead of protocol interfaces
• Shared global state between tests — use fresh TestEnvironment per test
• Not passing overrides via extra_registrations to TestEnvironment
• Testing without stub() modules — forces full boot with real infrastructure