Documentation
¶
Overview ¶
Package testing (imported as orjanda/testing) provides the first-class test harness: NewTestSite, WithApps, WithDialect, CreateUser, WithUser, SeedFixtures, MockLLM, ToolCall, TextResponse, and ApprovalPrompt.
NewTestSite provisions a fully-wired site (Registry compiled, tables created, engines attached, no HTTP server) with a fresh in-memory SQLite database per test, or a testcontainers-go PostgreSQL instance under the "integration" build tag (WithDialect("postgres")). TestSite exposes the real Document Engine as Document and an Agent Runtime as Agent, so the PRD §32.2–§32.3 patterns read verbatim; per-turn LLM providers come from agent.WithProvider(…).
See TAD §17 and PRD §32 for the full specification.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MockLLM ¶
MockLLM builds a scripted llm.Provider whose responses are deterministic and require no network access or API keys (PRD §32.1). Running out of steps — or consuming a step from the wrong call type — fails the test with a descriptive message, so an over- or under-scripted exchange cannot pass silently.
Types ¶
type MockStep ¶
type MockStep interface {
// contains filtered or unexported methods
}
MockStep is one entry in a MockLLM step queue: a scripted ChatCompletion response (ToolCall/TextResponse) or an approval round trip (ApprovalPrompt). See TAD §17.
func ApprovalPrompt ¶
func ApprovalPrompt() MockStep
ApprovalPrompt scripts the client-side approval round trip (TAD §12.3): the next RequestApproval call is answered with Approved. Place it in the queue where the human's decision belongs — for a plan approval that is between the plan JSON response and the final summary synthesis (TAD §11.2 step b).
func TextResponse ¶
TextResponse scripts a single ChatCompletion response containing only text (TAD §17). It also scripts structured-output plan responses in Plan-and-Execute mode: the text is handed to planner.Unmarshal verbatim.
func ToolCall ¶
ToolCall scripts a single ChatCompletion response asking the executor to invoke name with the given arguments (TAD §17). Arguments are JSON-encoded into the tool-call payload exactly as a real model would emit them.
type Option ¶
type Option func(*testSiteConfig)
Option configures a NewTestSite call. See TAD §17.
func WithApps ¶
func WithApps(apps ...app.Definition) Option
WithApps installs the given Application definitions onto the site, ordered by the application dependency DAG (TAD §7.1 step 2). The Application's Documents must be supplied either through its Definition.Hooks' OnInstall hook (PRD §11.3 "Install: register documents") or via WithDocuments — the app.Definition type itself carries no Documents (TAD §7).
func WithDialect ¶
WithDialect selects the backing database. Default is a fresh in-memory SQLite database per test. "postgres" opts into a testcontainers-go-backed PostgreSQL instance (TAD §17.1 guarantee 1) and requires the "integration" build tag; without it NewTestSite fails fast.
func WithDocuments ¶
WithDocuments registers Documents under an Application name. Use it to declare an Application's Documents to the harness when the Application has no OnInstall hook of its own. Documents are registered before the Registry is compiled, so they are compiled, have tables created, and are immediately usable when NewTestSite returns (TAD §17.1 guarantee 2).
type TestSite ¶
type TestSite struct {
*orjanda.Site
// Document is the same Document Engine the site's DocEngine field
// references. Every Create/Read/Update/Delete call goes through the real
// permission, hook, workflow, and audit pipeline — no test-only bypass
// (PRD §25.1, TAD §17.1 guarantee 3).
Document *document.Engine
// Agent is an Agent Runtime wired to the site's engines. No LLM provider
// is configured by default: a turn only works when the caller supplies one
// per call via agent.WithProvider(...) — which is how MockLLM drives it.
Agent *runtime.Runtime
// contains filtered or unexported fields
}
TestSite is the test-site composition root returned by NewTestSite. It embeds the full *orjanda.Site and additionally exposes the Document Engine and an Agent Runtime under the names PRD §32 uses (site.Document.Create, site.Agent.Execute), so the §32.2/§32.3 acceptance examples read verbatim. See TAD §17.
func NewTestSite ¶
NewTestSite provisions a fresh, isolated site for a single test: a new in-memory SQLite database by default, the core User/Role/RolePermission Documents, and every Document declared via WithDocuments/WithApps installed. Registry.Compile() has already run and all tables exist when it returns — the site is immediately usable with no serve step (TAD §17.1 guarantees 1–3). No HTTP server is started.
func (*TestSite) CreateUser ¶
CreateUser provisions a User (plus Role records and UserRole grants) with the given roles and returns its auth.Identity. Runs through the real Document Engine under the System Administrator identity, so the User, UserRole, and Role rows are written through the same permission/audit path the application uses (TAD §4.1, PRD §32.2).
func (*TestSite) SeedFixtures ¶
SeedFixtures loads Application fixture JSON (PRD §11.1 fixtures/) and creates every record through the Document Engine under the System Administrator identity. The file is a map of DocType → array of record objects, e.g.:
{ "Employee": [ {"FirstName":"Ada","LastName":"Lovelace"} ] }
Records are created in file order per DocType (map iteration order across DocTypes is unspecified; fixtures must not depend on cross-DocType order).
Source Files