Testing

The tests/ tree is the framework's full pytest suite — 1,349 collected tests, strictly network-free and credential-free. Run it from the package root with pytest; configuration lives in pyproject.toml (asyncio_mode = "auto", testpaths = ["tests"]).

The suite layout deliberately mirrors the package layout under indusagi/: one test subdirectory per subsystem (agent, ai, capabilities, connectors, interop, llmgateway, mcp, react_ink, runtime, shell_app, smithy, swarm, tracing, tui, ui_bridge), plus two root-level guards. Because of this, the test tree doubles as a map of the package's public surface — each directory imports only its sibling subpackage's public API.

Table of Contents

• Running the tests
• Collection model
• Coverage map
• Test-double strategy
• Root-level guards
• Key concepts
• Why 1,349?
• Relationship to neighbors

Running the tests

Install the package with its dev extras, then invoke pytest from the package root. asyncio_mode = "auto" means every async def test_* runs without an explicit @pytest.mark.asyncio decorator.

# from the package root (pyproject.toml supplies testpaths + asyncio mode)
# pytest                                     # all 1,349 tests
# pytest tests/llmgateway                    # one subsystem (101 collected)
# pytest tests/tui/test_keys.py              # one file
# pytest --collect-only -q tests | tail -1   # -> "1349 tests collected"
# pytest tests/ui_bridge -q                  # the Textual Pilot integration tests

No environment variables or API keys are required. Tests that exercise key resolution monkeypatch os.environ and never read real credentials; tests that exercise sessions open on-disk fixtures strictly read-only.

Collection model

A few structural facts shape how collection works:

• No top-level conftest.py and no __init__.py anywhere under tests/. pytest uses rootdir-relative sys.path insertion, which is why tests/agent/ imports the sibling module agent_suite_helpers by bare name (from agent_suite_helpers import make_agent).
• asyncio_mode = "auto" — async tests need no marker.
• The only per-directory conftest.py is tests/mcp/conftest.py, which installs the in-memory MCP transport fixture.

The physical test-function count is only ~470 (def test_* / async def test_*), but pytest collects 1,349 because of heavy parametrization (see Why 1,349?).

Coverage map

Per-directory collected counts (verified via pytest --collect-only):

Each subsystem directory maps to a documented page: AI, Agent, MCP, Memory, LLM Gateway, Runtime, Capabilities, Interop, Connectors, Swarm, Smithy, Tracing, Shell App, TUI, react-ink, UI Bridge.

Test-double strategy

The double strategy is uniform and network-free across the whole suite. Three seam patterns recur.

The deterministic mock connector

agent, ai, llmgateway, and ui_bridge bind to the catalog card mock-1 (indusagi.llmgateway.connectors.mock.MockConnector) so that gateway_stream routes locally. The mock streams fixed text ("Hello world", usage 8 in / 5 out) and a scripted echo tool call, making those runs fully deterministic without any network.

Scripted gateway / ModelInvoker

When a test needs to drive the model's output, it replaces the live model with a pre-recorded list of Emissions replayed as a Channel:

• tests/agent uses agent_suite_helpers.GatewayScript, which monkeypatches the module-level indusagi.agent.agent.gateway_stream seam.
• tests/runtime and tests/shell_app inject a scripted ModelInvoker replayed as a Channel of Emissions.

# pattern used across tests/agent via agent_suite_helpers.GatewayScript
from agent_suite_helpers import make_agent, GatewayScript, done_reply, events_named


async def test_prompt_runs_clean(monkeypatch):
    script = GatewayScript([done_reply("pong")])
    monkeypatch.setattr("indusagi.agent.agent.gateway_stream", script)
    agent = make_agent()
    await agent.prompt("ping")
    assert events_named(agent, "message_end")

In-memory MCP transport

tests/mcp and tests/interop stand up a create_provider_host server half over the MCP SDK's create_client_server_memory_streams and reach it through create_server_endpoint. tests/mcp/conftest.py monkeypatches indusagi.mcp.client.create_server_endpoint to inject an in-memory session factory per server name.

# tests/mcp use the conftest fixture to route a facade client onto an in-memory host
from indusagi.mcp import MCPClient
# conftest provides: install_transport, ping_tool, echo_tool, boom_tool, sleep_tool


async def test_call_tool(install_transport):
    install_transport({"srv": memory_session_factory([ping_tool()])})  # noqa: F821
    client = MCPClient(...)
    await client.connect()
    result = await client.call_tool("ping", {})
    assert any(b.get("text") == "pong" for b in result.content)

HTTP, filesystem, and Textual

• HTTP wire tests (llmgateway streaming/gateway/catalog-fallback) use respx to mock httpx, exercising real SSE/NDJSON framing across chunk boundaries, CRLF/LF/CR, and multibyte UTF-8 without a server.
• Filesystem suites (capabilities, swarm, smithy, tracing) write under pytest's tmp_path against the real local fs/shell backends rather than stubs — genuine I/O paths, no network.
• Textual TUI tests (ui_bridge) drive the real InteractiveApp headless via App.run_test() / Pilot.
• react_ink/test_diff.py guards an optional sibling with pytest.importorskip("indusagi.react_ink.theme_adapter").

Root-level guards

test_public_api.py is the single guard that the whole tree imports cleanly and every barrel's __all__ is honest. Its PUBLIC_BARRELS list and USER_JOURNEY_IMPORTS lines enumerate the canonical entry points for each subsystem, so it doubles as a living checklist of the package exports.

import importlib
import pkgutil
import indusagi

modules = {"indusagi"} | {
    info.name
    for info in pkgutil.walk_packages(indusagi.__path__, prefix="indusagi.")
}
for name in sorted(modules):
    importlib.import_module(name)  # every module must import

from indusagi.agent import Agent, create_coding_tools  # a USER_JOURNEY_IMPORTS line
from indusagi.mcp import MCPClient, MCPClientPool       # another

Key concepts

Why 1,349?

File size does not equal test count — equating the two is a trap. Two parametrization sources account for nearly the entire gap between ~470 physical functions and 1,349 collected:

1. test_public_api.py (507 collected) — test_module_imports parametrizes over every module pkgutil.walk_packages discovers under indusagi (~279 modules; the file's own tripwire asserts >= 200), plus test_every_all_name_resolves over every barrel declaring __all__ and 14 USER_JOURNEY_IMPORTS.
2. tests/tui (444 collected) — test_keys.py (14 parametrize blocks) and test_text_width.py (9 blocks) fan a small number of functions into hundreds of cases over terminal escape-sequence and grapheme-width corpora.

The suite is strictly offline / no-credential: env-key tests monkeypatch os.environ (never read real keys), and session tests open the smallest real on-disk session strictly read-only (never via SessionManager.open, which would rewrite a pre-v3 file).

Relationship to neighbors

Cross-subsystem coupling shows up entirely in the harnesses:

• agent, ai, and llmgateway share the deterministic mock/mock-1 connector card.
• mcp and interop share the same MCP-SDK in-memory transport pattern; mcp/conftest.py explicitly reuses interop's create_provider_host approach.
• runtime, shell_app, agent, and ui_bridge all script the model via a Channel of Emissions / ModelInvoker, so the conductor loop runs deterministically.
• ui_bridge composes runtime.create_agent + the llmgateway mock + the Textual app, making its tests the broadest integration tests in the suite.

Several suites pin deliberate Python-side behaviors that are documented as intentional, not bugs: shell_app/test_boot_flags.py asserts that --system/--no-tools/--mcp actually take effect and that faulted MCP servers print to stderr; shell_app/test_auth_cli.py pins the API-key-first login path. For the full TS-vs-Python coverage story and the per-file "ported 1:1" vs "authored" provenance, see Parity. For the entry points enumerated by PUBLIC_BARRELS, see Package exports; for the high-level layering, see Architecture.