Documentation
¶
Overview ¶
Package elelemtest holds elelem's test doubles.
Which one to reach for, in one question: does the test need the model to SAY something?
- Yes — the turn loop, tool calls, streaming, history. Use ScriptedDriver. It plays a sequence of turns and honours the Driver contract, so a test cannot pass against a shape no real provider emits.
- No — a decorator, retry, metrics, a registry. Use elelemtest/mocks MockDriver. It has no behaviour; what it gives you is call verification (argument matchers, .Once(), AssertExpectations at cleanup).
This package imports NOTHING beyond elelem and ctxerrors — no `testing`, no testify — because production code reaches it: the app resolves every upstream to the scripted driver under `go test` so a test cannot dial a real provider by accident, and that import must not drag the test framework into the shipped binary. The contract suite, which does need testify, lives in the elelemtest/conformance subpackage for exactly that reason.
Index ¶
- Variables
- func ResetGlobalScriptedDriver()
- func SetGlobalScriptedDriver(driver *ScriptedDriver)
- type ScriptedDriver
- func (c *ScriptedDriver) Calls() int
- func (c *ScriptedDriver) Capabilities(elelem.Model) elelem.Capabilities
- func (c *ScriptedDriver) Complete(ctx context.Context, request elelem.DriverRequest, ...) (elelem.Usage, error)
- func (c *ScriptedDriver) LastRequest() (elelem.DriverRequest, bool)
- func (c *ScriptedDriver) ListModels(_ context.Context) ([]string, error)
- func (c *ScriptedDriver) Requests() []elelem.DriverRequest
- func (c *ScriptedDriver) Stream(ctx context.Context, request elelem.DriverRequest, ...) (elelem.Usage, error)
- func (c *ScriptedDriver) Streamed() []bool
- func (c *ScriptedDriver) TokenCounter() elelem.TokenCounter
- func (c *ScriptedDriver) WithCapabilities(capabilities elelem.Capabilities) *ScriptedDriver
- func (c *ScriptedDriver) WithModels(models ...string) *ScriptedDriver
- func (c *ScriptedDriver) WithTokenCounter(counter elelem.TokenCounter) *ScriptedDriver
- type Turn
Constants ¶
This section is empty.
Variables ¶
var ErrNoScriptedTurns = errors.New(
"elelemtest: no scripted turn for Stream call",
)
Functions ¶
func ResetGlobalScriptedDriver ¶
func ResetGlobalScriptedDriver()
ResetGlobalScriptedDriver clears the registry.
func SetGlobalScriptedDriver ¶
func SetGlobalScriptedDriver(driver *ScriptedDriver)
SetGlobalScriptedDriver installs the driver the app's wiring will hand out while running under `go test`. Call ResetGlobalScriptedDriver in a cleanup; leaving one installed leaks a script into the next test.
Types ¶
type ScriptedDriver ¶
type ScriptedDriver struct {
// contains filtered or unexported fields
}
ScriptedDriver is an elelem.Driver that replays a fixed sequence of turns, one per Stream call. Reach for it when the code under test consumes model output — the agentic turn loop, tool calls, streaming, history — because those assertions only exist if something plays the model's part.
When the code under test merely wraps or calls a Driver (a decorator, retry, metrics) and the question is "was it called, with what, and did the result survive", use elelemtest/mocks.MockDriver instead: it verifies calls and this does not.
Unlike a bare generated mock, this honours the Driver contract (see conformance.Run) rather than replaying whatever it is handed, so a test built on it cannot pass against a driver shape no real provider can produce.
func GlobalScriptedDriver ¶
func GlobalScriptedDriver() *ScriptedDriver
GlobalScriptedDriver returns the installed driver, or nil when none is set.
func NewScriptedDriver ¶
func NewScriptedDriver(turns ...Turn) *ScriptedDriver
func (*ScriptedDriver) Calls ¶
func (c *ScriptedDriver) Calls() int
func (*ScriptedDriver) Capabilities ¶
func (c *ScriptedDriver) Capabilities(elelem.Model) elelem.Capabilities
func (*ScriptedDriver) Complete ¶ added in v0.4.0
func (c *ScriptedDriver) Complete( ctx context.Context, request elelem.DriverRequest, onDelta func(elelem.Delta) error, ) (elelem.Usage, error)
Complete replays the scripted turn EXACTLY as Stream does, recording only that it was the method called.
It deliberately does not reshape the deltas to imitate a non-streaming provider. The deltas come from the test — Turn{Deltas: ...} — so rewriting them would be the double second-guessing its own caller: script three deltas, assert three OnText calls, and this method would silently deliver something else, failing the test for a reason unrelated to elelem. A test wanting the one-big-chunk shape scripts one big delta.
The contrast worth keeping in mind is validateTranscript below, which is a double being STRICTER than its caller — refusing input no provider accepts. That kind of fidelity catches real bugs. Manufacturing output nobody asked for is the opposite: it produces green tests about behaviour that never ran.
func (*ScriptedDriver) LastRequest ¶
func (c *ScriptedDriver) LastRequest() (elelem.DriverRequest, bool)
func (*ScriptedDriver) ListModels ¶
func (c *ScriptedDriver) ListModels(_ context.Context) ([]string, error)
func (*ScriptedDriver) Requests ¶
func (c *ScriptedDriver) Requests() []elelem.DriverRequest
func (*ScriptedDriver) Streamed ¶ added in v0.4.0
func (c *ScriptedDriver) Streamed() []bool
Streamed reports, per call in order, whether the engine reached for Stream (true) or Complete (false) — the assertion a WithStreaming test is actually after.
func (*ScriptedDriver) TokenCounter ¶
func (c *ScriptedDriver) TokenCounter() elelem.TokenCounter
func (*ScriptedDriver) WithCapabilities ¶
func (c *ScriptedDriver) WithCapabilities( capabilities elelem.Capabilities, ) *ScriptedDriver
func (*ScriptedDriver) WithModels ¶
func (c *ScriptedDriver) WithModels(models ...string) *ScriptedDriver
func (*ScriptedDriver) WithTokenCounter ¶
func (c *ScriptedDriver) WithTokenCounter( counter elelem.TokenCounter, ) *ScriptedDriver
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package conformance is the contract suite for people WRITING an elelem.Driver.
|
Package conformance is the contract suite for people WRITING an elelem.Driver. |