Enum PocketIcStartupConfig 

pub enum PocketIcStartupConfig {
    Spawn {
        server_binary: PathBuf,
        timeout: Duration,
        server_hard_ttl: Option<Duration>,
        server_idle_ttl: Option<Duration>,
        server_output_files: Option<(PathBuf, PathBuf)>,
    },
    Connect {
        server_url: String,
        timeout: Duration,
    },
}

Explicit bounded source and policy for one PocketIC startup.

Spawn-only settings cannot be attached to a borrowed connection. Callers own binary admission, output retention and namespace custody.

Variants

Spawn

Spawn and own one exact server executable.

Fields

server_binary: PathBuf

Caller-selected, already prepared server binary.

timeout: Duration

Complete startup deadline; must be positive.

server_hard_ttl: Option<Duration>

Optional hard lifetime, in whole seconds; None disables it.

server_idle_ttl: Option<Duration>

Optional operation-idle lifetime; None uses PocketIC’s default.

server_output_files: Option<(PathBuf, PathBuf)>

New caller-owned stdout/stderr files, or temporary output when absent. Existing entries are refused. Created files survive failure and teardown.

Connect

Borrow an existing server without claiming its process lifetime.

Fields

server_url: String

Existing server URL, admitted by the upstream builder.

timeout: Duration

Complete startup deadline; must be positive.

Implementations

impl PocketIcStartupConfig

pub fn from_env(timeout: Duration) -> Result<Self, PocketIcStartupError>

Select the shared environment contract without discovery or downloads.

IC_TESTKIT_POCKET_IC_URL takes precedence over POCKET_IC_BIN. An explicitly empty or invalid selected value fails rather than falling back. URL mode never launches a version probe or claims server ownership. Binary mode resolves the explicit path and checks --version against Testkit’s supported protocol range using the shared bounded capture engine. This is version qualification, not executable-byte admission; prepare and verify the binary with ic-testkit-server setup / check. The probe has its own timeout; subsequent startup has the same budget.

pub const fn timeout(&self) -> Duration

Complete startup deadline for either source.

pub fn build_instance( self, builder: PocketIcBuilder, ) -> Result<PocketIcInstance<PocketIc>, PocketIcStartupError>

Construct a synchronous instance and retain its exact managed server.

One deadline covers server readiness and instance creation. Topology, state paths and request policy remain on the caller’s builder. Spawn mode terminates the server on failure and retains it on success; connect mode never claims the external server. See PocketIcInstance for drop limits.

use ic_testkit::pic::{PocketIcBuilder, PocketIcStartupConfig};
use std::{path::Path, time::Duration};
let owned = PocketIcStartupConfig::Spawn { server_binary: binary.into(), timeout: Duration::from_secs(60), server_hard_ttl: None, server_idle_ttl: None, server_output_files: None }
    .build_instance(PocketIcBuilder::new().with_application_subnet())?;
let canister = owned.instance.create_canister();
assert!(owned.instance.canister_exists(canister));
// Drop deletes the instance, then terminates and reaps the owned server.

pub async fn build_instance_async( self, builder: PocketIcBuilder, ) -> Result<PocketIcInstance<PocketIc>, PocketIcStartupError>

Construct an upstream nonblocking instance on the caller’s Tokio runtime.

Uses the same deadline, readiness checks, typed panic/exit failures and bounded output as Self::build_instance, without running the synchronous instance constructor. Requires a Tokio runtime with its time driver enabled. Readiness and instance waits yield; process spawning and small file reads remain synchronous, as does exact owned-child cleanup. The deadline cannot preempt synchronous work inside an upstream future poll (such as copying a read-only state directory); it is enforced when that poll returns.

Dropping the future cancels local construction and terminates/reaps its owned server, including during readiness. Cancellation has no returned error; select output files to retain diagnostics. A borrowed server is untouched. If a borrowed server created an instance before timeout or a lost reply, local cancellation cannot identify or delete that instance; the caller owns this reconciliation. The deadline covers construction, not subsequent deletion.

use ic_testkit::pic::{PocketIcBuilder, PocketIcStartupConfig};
use std::{path::Path, time::Duration};
let owned = PocketIcStartupConfig::Spawn { server_binary: binary.into(), timeout: Duration::from_secs(60), server_hard_ttl: None, server_idle_ttl: None, server_output_files: None }
    .build_instance_async(PocketIcBuilder::new().with_application_subnet()).await?;
let canister = owned.instance.create_canister().await;
assert!(owned.instance.canister_exists(canister).await);
owned.instance.drop().await;
drop(owned.server);

pub fn start_managed_server( self, ) -> Result<PocketIcManagedServer, PocketIcStartupError>

Start a caller-owned managed server without constructing an instance.

This requires a configuration created by Self::Spawn. Readiness is bounded by Self::timeout. No hard TTL is passed by default; an explicit server_hard_ttl value is passed to the child. server_idle_ttl independently selects the operation-idle lifetime; otherwise PocketIC retains its own idle default. Readiness requires a nonzero decimal port followed by a newline in a regular UTF-8 file of at most 64 bytes; oversized files fail with bounded diagnostics. Non-regular port files fail with PocketIcStartupFailure::Io and io::ErrorKind::InvalidData without waiting for a FIFO writer. The returned handle terminates the child on drop; use its URL with Self::Connect to construct bounded instances.

pub fn run_command( self, command: &mut Command, cancelled: impl FnMut() -> bool, ) -> Result<ExitStatus, PocketIcStartupError>

Run a command with IC_TESTKIT_POCKET_IC_URL set to this server.

Spawn mode retains the managed server until command completion; connect mode borrows the external server and never terminates it. The command’s IO and other environment selections remain caller-owned. Cancellation is polled after bounded startup and every 20 ms while the command runs. It returns an io::ErrorKind::Interrupted error after cleanup. If the owned server exits while the command is pending, the command is terminated and the server’s status and bounded diagnostics are returned as PocketIcStartupFailure::ServerExited. External servers are not monitored.

On Unix the command starts in a new owned process group. Completion, cancellation and observation failures terminate remaining group members before reaping the leader, using the same lifecycle engine as managed servers. This does not impose a command deadline or sandbox descendants that deliberately leave the owned group. Other hosts own the direct child.

Trait Implementations

impl Clone for PocketIcStartupConfig

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PocketIcStartupConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for PocketIcStartupConfig

impl PartialEq for PocketIcStartupConfig

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for PocketIcStartupConfig