Documentation
¶
Overview ¶
Package enginetest provides reusable contract-test machinery for implementations of engine.Engine.
Modeled on net/http/httptest and testing/iotest: a sibling package next to its subject, importable from any concrete engine's *_test files. It contains exclusively test-support code; nothing in here should be referenced from non-test production paths.
What lives here ¶
[Suite] / RunSuite — the standard contract every Engine implementation should pass. New engines should add a one-liner:
func TestEngineContract(t *testing.T) { enginetest.RunSuite(t, func() engine.Engine { return newMyEngine() }) }
MockHost — a minimal Host implementation that records every interaction, lets tests inject interrupts / user replies, and exposes the captured envelopes / usage / checkpoints for assertion. Engines may use it directly in their own tests instead of re-implementing the full Host surface.
What does NOT live here ¶
This package does not enumerate engine-specific behaviours (graph-edge ordering, script-language semantics, …). It only asserts what every engine.Engine is contractually obliged to do. Engine-specific tests live next to the engine.
Index ¶
- func RunSuite(t *testing.T, f Factory)
- type Capabilities
- type Factory
- type MockHost
- func (h *MockHost) AskUser(_ context.Context, p engine.UserPrompt) (engine.UserReply, error)
- func (h *MockHost) Checkpoint(_ context.Context, cp engine.Checkpoint) error
- func (h *MockHost) Checkpoints() []engine.Checkpoint
- func (h *MockHost) Envelopes() []event.Envelope
- func (h *MockHost) Interrupt(cause engine.Cause, detail string)
- func (h *MockHost) Interrupts() <-chan engine.Interrupt
- func (h *MockHost) Prompts() []engine.UserPrompt
- func (h *MockHost) Publish(_ context.Context, env event.Envelope) error
- func (h *MockHost) ReportUsage(_ context.Context, usage model.TokenUsage)
- func (h *MockHost) SetCheckpointError(err error)
- func (h *MockHost) SetPublishError(err error)
- func (h *MockHost) SetUserReply(reply *engine.UserReply)
- func (h *MockHost) TotalUsage() model.TokenUsage
- func (h *MockHost) Usages() []model.TokenUsage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RunSuite ¶
RunSuite runs every contract test that applies to the engine produced by f. Engines should call this from their own *_test.go:
func TestEngineContract(t *testing.T) {
enginetest.RunSuite(t, func() (engine.Engine, enginetest.Capabilities) {
return graph.NewEngine(), enginetest.Capabilities{SupportsResume: true}
})
}
Each subtest constructs a fresh engine, so failures isolate cleanly. The whole suite must pass for an implementation to be considered engine.Engine-compliant.
Types ¶
type Capabilities ¶
type Capabilities struct {
// SupportsResume is true when the engine implements Run.ResumeFrom
// (i.e. given a non-nil ResumeFrom whose ExecID matches Run.ID it
// resumes the run rather than returning errdefs.NotAvailable).
SupportsResume bool
}
Capabilities lets an engine declare which optional behaviours it implements. The contract suite uses this to skip resume-specific subtests when the engine has SupportsResume == false (those subtests instead assert the engine returns NotAvailable).
type Factory ¶
type Factory func() (engine.Engine, Capabilities)
Factory builds a fresh engine and reports its capabilities. The suite calls Factory once per subtest so subtests do not share engine state.
Engines that take no construction arguments can wrap a constructor:
enginetest.RunSuite(t, enginetest.NewFactory(graph.NewEngine))
or implement Factory directly when the construction needs more setup.
type MockHost ¶
type MockHost struct {
// contains filtered or unexported fields
}
MockHost is a fully-featured engine.Host for tests. It records every interaction and lets the test inject cooperative interrupts and user replies.
All methods are safe for concurrent use; any number of goroutines inside the engine may call them while the test inspects state.
Zero value is NOT ready to use. Call NewMockHost which pre-allocates the channels.
func NewMockHost ¶
func NewMockHost() *MockHost
NewMockHost returns a ready-to-use MockHost. The interrupt channel is buffered so MockHost.Interrupt never blocks the test goroutine when the engine has not yet reached its select on Interrupts().
func (*MockHost) AskUser ¶
AskUser records the prompt and returns the configured reply, or a NotAvailable error when no reply has been set.
func (*MockHost) Checkpoint ¶
Checkpoint records cp and returns the configured checkpointErr.
func (*MockHost) Checkpoints ¶
func (h *MockHost) Checkpoints() []engine.Checkpoint
Checkpoints returns a copy of every checkpoint the engine submitted.
func (*MockHost) Interrupt ¶
Interrupt queues an interrupt for the engine. Non-blocking: if the buffer is full the call drops the new signal silently — tests that care should call only once or assert via MockHost.Envelopes that the engine has reached its select.
func (*MockHost) Interrupts ¶
Interrupts returns the cooperative-interrupt channel.
func (*MockHost) Prompts ¶
func (h *MockHost) Prompts() []engine.UserPrompt
Prompts returns a copy of every UserPrompt the engine submitted.
func (*MockHost) Publish ¶
Publish records the envelope and returns the configured publishErr (default nil).
func (*MockHost) ReportUsage ¶
func (h *MockHost) ReportUsage(_ context.Context, usage model.TokenUsage)
ReportUsage records the usage delta. Multiple calls are kept in order so tests can assert per-call totals; sum them with MockHost.TotalUsage when only the total matters.
func (*MockHost) SetCheckpointError ¶
SetCheckpointError configures all subsequent Checkpoint calls to return err. Pass nil to clear.
func (*MockHost) SetPublishError ¶
SetPublishError configures all subsequent Publish calls to return err. Pass nil to clear.
func (*MockHost) SetUserReply ¶
SetUserReply configures what AskUser returns. Pass nil to revert to the NotAvailable default.
func (*MockHost) TotalUsage ¶
func (h *MockHost) TotalUsage() model.TokenUsage
TotalUsage sums every recorded usage report.
func (*MockHost) Usages ¶
func (h *MockHost) Usages() []model.TokenUsage
Usages returns a copy of every usage report.
Source Files