agenttest

package
v0.15.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 7, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Documentation

Overview

Package agenttest provides deterministic consumer-side fixtures and reusable conformance suites for the Agent Framework's public execution boundaries. It exercises public Definition, Execution, and TreeDurability contracts without simulating private Engine state or Process lifecycle ownership.

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidDispatchScript = errors.New("agenttest: invalid dispatch script")
	ErrUnexpectedDispatch    = errors.New("agenttest: unexpected dispatch")
	ErrEffectMismatch        = errors.New("agenttest: effect does not match script")
)
View Source 
var ErrInvalidEventPredicate = errors.New("agenttest: invalid event predicate")

Functions

func RunDefinitionConformance 

func RunDefinitionConformance(t *testing.T, config DefinitionConformanceConfig)

RunDefinitionConformance verifies descriptor stability, concurrent Start isolation, exact Snapshot/Restore, and byte-equivalent Step results for the supplied representative cases. Step cases must describe successful Steps; Strategy-specific failure and cancellation paths remain ordinary tests owned by the Definition implementation.

func RunTreeDurabilityConformance 

func RunTreeDurabilityConformance(
	t *testing.T,
	factory func() TreeDurabilityConformanceDriver,
)

RunTreeDurabilityConformance exercises base-head creation, same-content callback retry, pending/settled/resolved Effect boundaries, Parked/Terminal checkpoints, old-writer fencing, and recovery after callback failures before and after the underlying commit. It checks head contents, dispatch counts, unknown outcomes, and publication ordering without assuming a storage engine. Each factory call must return a new driver backed by an empty isolated store.

Types

type DefinitionConformanceConfig 

type DefinitionConformanceConfig struct {
	// Definition is the immutable behavior under test.
	Definition agent.Definition
	// Input is one valid value accepted by Definition.Start.
	Input agent.Input
	// InitialSignals are delivered to each fresh Execution created from Input.
	InitialSignals []agent.Signal
	// RestoredCases exercise additional previously captured states.
	RestoredCases []ExecutionConformanceCase
}

DefinitionConformanceConfig describes representative public boundary cases for one Definition. Conformance is evidence for these cases, not a proof that arbitrary implementation code never reads hidden input or performs I/O.

type DispatchStep 

type DispatchStep struct {
	// ExpectedEffect is the optional complete Effect expected at this step.
	ExpectedEffect *agent.Effect
	// Deltas are emitted in declaration order before the final outcome.
	Deltas []json.RawMessage
	// SettlementStatus is the definite or unknown settlement status.
	SettlementStatus agent.SettlementStatus
	// SettlementPayload is the Strategy-owned settlement payload.
	SettlementPayload json.RawMessage
	// Error makes Dispatch return an indeterminate external error.
	Error error
}

DispatchStep describes one expected Dispatcher call and its deterministic stream and settlement outcome. ExpectedEffect is optional; when present, the complete immutable Effect must match. Error may follow emitted Deltas and is mutually exclusive with SettlementStatus and SettlementPayload.

type ExecutionConformanceCase 

type ExecutionConformanceCase struct {
	// Name identifies the sample in test output.
	Name string
	// State is an exact state previously produced by the Definition.
	State agent.ExecutionState
	// Signals are the ordered Signal prefix delivered to Step.
	Signals []agent.Signal
}

ExecutionConformanceCase describes one successful Restore and Step sample.

type MemoryTreeDurability 

type MemoryTreeDurability struct {
	// contains filtered or unexported fields
}

MemoryTreeDurability is a concurrency-safe teaching and test adapter for the TreeDurability CAS contract. It is intentionally in agenttest: production Hosts should implement the same transaction with their own durable store.

func NewMemoryTreeDurability 

func NewMemoryTreeDurability() *MemoryTreeDurability

NewMemoryTreeDurability constructs an empty in-memory durability adapter.

Example 
package main

import (
	"fmt"

	"github.com/Tangerg/scope/agent"
	"github.com/Tangerg/scope/agent/agenttest"
)

func main() {
	durability := agenttest.NewMemoryTreeDurability()
	var contract agent.TreeDurability = durability

	fmt.Printf("%T\n", contract)
}

Output:
*agenttest.MemoryTreeDurability

func (*MemoryTreeDurability) AcknowledgeProcessStartOutcome 

func (m *MemoryTreeDurability) AcknowledgeProcessStartOutcome(
	_ context.Context,
	outcome agent.ProcessStartOutcome,
) error

AcknowledgeProcessStartOutcome atomically closes admission and, for durable started/child outcomes, installs the prospective tree head.

func (*MemoryTreeDurability) ActivateTree 

func (m *MemoryTreeDurability) ActivateTree(
	_ context.Context,
	activation agent.TreeActivation,
) error

ActivateTree atomically fences the previous writer and installs the new incarnation snapshot.

func (*MemoryTreeDurability) CommitCheckpoint 

func (m *MemoryTreeDurability) CommitCheckpoint(
	_ context.Context,
	checkpoint agent.TreeCheckpoint,
) error

CommitCheckpoint atomically records a Runtime safe cut and advances its tree.

func (*MemoryTreeDurability) CommitEffect 

func (m *MemoryTreeDurability) CommitEffect(
	_ context.Context,
	boundary agent.EffectBoundary,
) error

CommitEffect atomically records an Effect boundary and advances its tree.

func (*MemoryTreeDurability) LoadTree 

func (m *MemoryTreeDurability) LoadTree(
	_ context.Context,
	rootID agent.ProcessID,
) (agent.TreeSnapshot, bool, error)

LoadTree returns the current authoritative head for rootID.

func (*MemoryTreeDurability) TreeDurability 

func (m *MemoryTreeDurability) TreeDurability() agent.TreeDurability

TreeDurability returns this adapter through the conformance-driver port.

type ObservationRecorder 

type ObservationRecorder struct {
	// contains filtered or unexported fields
}

ObservationRecorder is a concurrency-safe EventListener and DeltaListener. Its zero value is ready for use.

func (*ObservationRecorder) AwaitEvent 

func (o *ObservationRecorder) AwaitEvent(
	ctx context.Context,
	predicate func(agent.Event) bool,
) (agent.Event, error)

AwaitEvent returns the first recorded Event accepted by predicate. It waits for later events until ctx ends and never polls Process state.

func (*ObservationRecorder) Deltas 

func (o *ObservationRecorder) Deltas() []agent.Delta

Deltas returns recorded increments in delivery order.

func (*ObservationRecorder) Events 

func (o *ObservationRecorder) Events() []agent.Event

Events returns recorded events in publication order.

func (*ObservationRecorder) OnDelta 

func (o *ObservationRecorder) OnDelta(_ context.Context, delta agent.Delta)

func (*ObservationRecorder) OnEvent 

func (o *ObservationRecorder) OnEvent(_ context.Context, event agent.Event)

type ScriptedDispatcher 

type ScriptedDispatcher struct {
	// contains filtered or unexported fields
}

ScriptedDispatcher is a concurrency-safe finite Dispatcher fixture. It records every request that reaches script consumption and fails calls made beyond or contrary to the configured script.

func NewScriptedDispatcher 

func NewScriptedDispatcher(config ScriptedDispatcherConfig) (*ScriptedDispatcher, error)

NewScriptedDispatcher freezes the script at construction so a test cannot mutate expectations while the Engine is running against them. It fails calls that go beyond or contrary to the script rather than returning a zero settlement, because a dispatcher that quietly answers anything turns an ordering bug into a passing test.

func (*ScriptedDispatcher) Dispatch 

func (s *ScriptedDispatcher) Dispatch(
	ctx context.Context,
	request agent.EffectRequest,
	emit agent.DeltaEmitter,
) (agent.Settlement, error)

Dispatch consumes the next scripted step, emits its Deltas, and returns its configured settlement or error.

func (*ScriptedDispatcher) Remaining 

func (s *ScriptedDispatcher) Remaining() int

Remaining reports how many scripted calls have not been consumed.

func (*ScriptedDispatcher) ReplayPolicy 

func (s *ScriptedDispatcher) ReplayPolicy(effect agent.Effect) agent.ReplayPolicy

ReplayPolicy returns the immutable policy declared at construction.

func (*ScriptedDispatcher) Requests 

func (s *ScriptedDispatcher) Requests() []agent.EffectRequest

Requests returns consumed Dispatch requests in actual call order, including requests that mismatch or exceed the script.

type ScriptedDispatcherConfig 

type ScriptedDispatcherConfig struct {
	// ReplayPolicy is returned for every valid Dispatcher Effect.
	ReplayPolicy agent.ReplayPolicy
	// Steps are consumed in actual Dispatch order.
	Steps []DispatchStep
}

ScriptedDispatcherConfig declares a finite deterministic dispatch script.

type TreeDurabilityConformanceDriver 

type TreeDurabilityConformanceDriver interface {
	// TreeDurability returns the adapter under test.
	TreeDurability() agent.TreeDurability
	// LoadTree reads the current authoritative head without activating it.
	LoadTree(ctx context.Context, rootID agent.ProcessID) (agent.TreeSnapshot, bool, error)
}

TreeDurabilityConformanceDriver exposes one empty adapter instance and its authoritative head reader to the reusable TreeDurability contract suite.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.