Struct ProgramSimulator 

pub struct ProgramSimulator<M: Model> { /* private fields */ }

Deterministic simulator for Model testing.

Runs model logic without any terminal or IO dependencies. Events can be injected, messages sent directly, and frames captured for snapshot testing.

Implementations

impl<M: Model> ProgramSimulator<M>

pub fn new(model: M) -> Self

Create a new simulator with the given model.

The model is not initialized until init is called.

pub fn with_registry(model: M, registry: Arc<StateRegistry>) -> Self

Create a new simulator with the given model and persistence registry.

When provided, Cmd::SaveState/Cmd::RestoreState will flush/load through the registry, mirroring runtime behavior.

pub fn init(&mut self)

Initialize the model once and execute its startup commands.

Should be called once before injecting events or capturing frames.

pub fn inject_events(&mut self, events: &[Event])

Inject terminal events into the model.

Each event is converted to a message via From<Event> and dispatched through Model::update(). Commands returned from update are executed.

pub fn inject_event(&mut self, event: Event)

Inject a single terminal event into the model.

The event is converted to a message via From<Event> and dispatched through Model::update(). Commands returned from update are executed.

pub fn send(&mut self, msg: M::Message)

Send a specific message to the model.

The message is dispatched through Model::update() and returned commands are executed.

pub fn now(&self) -> Duration

Current deterministic monotonic simulator time.

pub fn advance_time(&mut self, delta: Duration) -> usize

Advance deterministic time and deliver every scheduled tick now due.

Positive tick intervals are delivered at their exact deadlines. A zero interval remains manually driven to avoid an unbounded loop.

pub fn tick(&mut self)

Deliver one tick immediately without advancing deterministic time.

pub fn poll_subscriptions(&mut self) -> &[SubId]

Reconcile the model’s declarative subscriptions without starting background threads.

Tests explicitly deliver subscription messages with deliver_subscription, keeping ordering and time fully deterministic.

pub fn active_subscription_ids(&self) -> &[SubId]

IDs of subscriptions active at the last deterministic reconciliation.

pub fn deliver_subscription( &mut self, id: SubId, msg: M::Message, ) -> Result<(), SimulatorError>

Deliver one message from an active declarative subscription.

pub fn report_error(&mut self, error: impl Into<String>)

Inject a runtime error through Model::on_error.

pub fn cancel(&mut self)

Cancel the simulated runtime and complete shutdown exactly once.

pub fn shutdown(&mut self)

Run Model::on_shutdown and clear simulated subscriptions exactly once.

pub fn is_shutdown(&self) -> bool

Whether the one-shot shutdown contract has completed.

pub fn errors(&self) -> &[String]

Errors delivered through Model::on_error.

pub fn capture_frame(&mut self, width: u16, height: u16) -> &Buffer

Capture the current frame at the given dimensions.

Calls Model::view() to render into a fresh buffer and stores the result. Returns a reference to the captured buffer.

pub fn frames(&self) -> &[Buffer]

Get all captured frame buffers.

pub fn last_frame(&self) -> Option<&Buffer>

Get the most recently captured frame buffer, if any.

pub fn frame_count(&self) -> usize

Get the number of captured frames.

pub fn model(&self) -> &M

Get a reference to the model.

pub fn model_mut(&mut self) -> &mut M

Get a mutable reference to the model.

pub fn pool(&self) -> &GraphemePool

Access the simulator grapheme pool used to render captured frames.

pub fn is_running(&self) -> bool

Check if the simulated program is still running.

Returns false after a Cmd::Quit has been executed.

pub fn tick_rate(&self) -> Option<Duration>

Get the current tick rate (if any).

pub fn logs(&self) -> &[String]

Get all log messages emitted via Cmd::Log.

pub fn command_log(&self) -> &[CmdRecord]

Get the command execution log.

pub fn clear_frames(&mut self)

Clear all captured frames.

pub fn clear_logs(&mut self)

Clear all logs.