Testing Utilities¶

Fixtures and context managers for testing Trails apps without boilerplate.

Auto-generated docs

When trails is installed, run ENABLE_MKDOCSTRINGS=true ./scripts/docs-build for full docstring-extracted reference.

Context managers¶

Symbol	Signature	Description
`isolated_kernel`	`isolated_kernel() -> ContextManager[None]`	Snapshot + clear every module-level registry (handlers, node types, shapes); restore on exit
`mock_llm`	`mock_llm(response_or_fn: str \\| Callable \\| None = None, *, fail_first: int = 0, model: str = "mock:canned") -> ContextManager[LLMClient]`	Install a mock LLMClient as `ctx.llm` for the duration of the block
`capture_events`	`capture_events() -> ContextManager[list[tuple[str, dict]]]`	Collect every observability event emitted inside the block

Symbol	Signature	Description
`fresh_context`	`fresh_context(principal: str = "did:local:test", trace_id: str \\| None = None) -> Context`	Build a Context bound to the kernel store with a fresh trace_id
`register_principal_role`	`register_principal_role(principal: str, role: str) -> None`	Register a principal with a role for Cedar policy evaluation

Symbol	Signature	Description
`assert_graph`	`assert_graph(ctx) -> GraphAssertions`	Create a fluent assertion interface for graph state
`GraphAssertions.has_type`	`.has_type(type_name: str) -> GraphAssertions`	Assert at least one `rdf:type` triple references the type
`GraphAssertions.has_instance`	`.has_instance(type_name: str, **filters) -> GraphAssertions`	Assert at least one instance of the type matches all filters
`GraphAssertions.triple_exists`	`.triple_exists(subject, predicate, obj) -> GraphAssertions`	Assert a triple matching the pattern exists (`None` = wildcard)
`GraphAssertions.shacl_valid`	`.shacl_valid() -> GraphAssertions`	Assert every `@node_type` instance passes SHACL validation

Symbol	Signature	Description
`@competency_question`	`@competency_question(question_text: str)`	Register a test function as answering a competency question
`cq_report`	`cq_report() -> CQReport`	Generate a competency question coverage report
`discover_competency_questions`	`discover_competency_questions(path: str = "tests/") -> list[CQEntry]`	Find all `@competency_question`-decorated tests via AST inspection

Symbol	Signature	Description
`@graph_fixture`	`@graph_fixture(name: str)`	Register a function as a named graph fixture
`load_fixture`	`load_fixture(ctx, name: str) -> dict`	Load a named graph fixture into the context
`load_ttl_fixture`	`load_ttl_fixture(ctx, path: str \\| Path) -> None`	Load a Turtle file as test data into the context
`assert_graph_snapshot`	`assert_graph_snapshot(ctx, snapshot_path, *, update: bool = False) -> None`	Compare current graph state to an N-Triples snapshot file

Opt in via pytest_plugins = ["trails.testing"] in conftest.py:

Fixture	Description
`trails_isolated`	Per-test wrapper around `isolated_kernel()`
`trails_mock_llm`	Yields an installed mock LLM client; supports indirect parametrization
`ctx`	Fresh `Context` per test with an empty graph
`graph_assert`	Pre-bound `GraphAssertions` for the `ctx` fixture