lexigram-testing

Centralized testing infrastructure for Lexigram Framework — Fixtures, factories, and utilities.

Overview

lexigram-testing provides in-process fakes for common framework protocols (FakeCache, FakeEventBus, FakeCommandBus, FakeClock, …), a pytest plugin with auto-registered fixtures, deterministic data-factory helpers, and a ContainerTestFixture for DI integration tests.

Full documentation: docs.lexigram.dev

Install

uv add --dev lexigram-testing

# With extras for specific backends
uv add --dev "lexigram-testing[db]"      # aiosqlite, asyncpg
uv add --dev "lexigram-testing[web]"     # httpx, starlette
uv add --dev "lexigram-testing[ai]"      # lexigram-ai
uv add --dev "lexigram-testing[auth]"    # lexigram-auth

Quick Start

import pytest
from lexigram.testing.fixtures import fake_cache
from lexigram.testing.fakes import FakeCache


class TestUserService:
    @pytest.fixture
    def cache(self) -> FakeCache:
        return FakeCache()

    @pytest.fixture
    def service(self, cache: FakeCache) -> UserService:
        return UserService(cache=cache)

    @pytest.mark.asyncio
    async def test_returns_cached_user(
        self, service: UserService, cache: FakeCache
    ) -> None:
        await cache.set("user:123", {"id": "123", "name": "Alice"})
        result = await service.find_cached("123")
        assert result.is_ok()
        assert result.unwrap().name == "Alice"

Testing

from lexigram.testing.fakes import FakeEventBus


@pytest.mark.asyncio
async def test_places_order_emits_event(self, fake_event_bus: FakeEventBus) -> None:
    service = OrderService(bus=fake_event_bus)
    await service.place(order)

    fake_event_bus.assert_published(OrderPlaced, order_id=order.id)
    assert len(fake_event_bus.published_of_type(OrderPlaced)) == 1

Available Fakes

All fakes live in lexigram.testing.fakes and implement the async contracts of the real services.

Key Features

• Zero infrastructure — all fakes run in-process; no Docker or external services needed
• Assertion helpers — assert_published(), assert_not_published(), assert_published_once(), assert_events_in_order()
• Async-first — all fakes implement the same async APIs as real backends
• pytest plugin — auto-registered fixtures and auto-skip for external-service markers (Redis, PostgreSQL, Elasticsearch, RabbitMQ, Meilisearch)
• DB fixtures — database_provider, clean_database, db_transaction, mock_connection, sample_user_data (with [db] extra)
• Data factory — test_data.create_user(), create_task(), create_message() via lexigram.testing.lib
• Container fixture — ContainerTestFixture with mock()/get() for DI integration tests
• Reproducible — deterministic IDs and timestamps for snapshot testing

pytest Plugin

The plugin is loaded automatically via entry points — no manual wiring needed:

uv run pytest -m "not integration"   # unit tests only (fast)
uv run pytest -m integration         # integration tests

Tests marked with external-service markers (redis, postgres, elasticsearch, rabbitmq, meilisearch) are skipped automatically when the service is unreachable.

Key Source Files