sandbox

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Mar 27, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Overview

Package sandbox provides comprehensive test environment setup for CLI application testing.

Sandbox bundles a jailed filesystem, test environment, test clock, logger, hasher, and stream into a single test harness. Use NewSandbox with functional options (WithEnv, WithClock, WithFixture, WithWd) to configure the test environment.

Process runs a Runner function in isolation with configurable I/O streams. Pipeline chains multiple stages with automatic stdout-to-stdin wiring between stages, enabling realistic multi-stage CLI testing.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Option added in v1.0.0 

type Option func(f *Sandbox)

Option is a function used to modify a Sandbox during construction.

func WithClock 

func WithClock(t0 time.Time) Option

WithClock returns an Option that sets the test clock to the provided time.

func WithEnv 

func WithEnv(key, val string) Option

WithEnv returns an Option that sets a single environment variable in the sandbox's Env.

func WithEnvMap 

func WithEnvMap(m map[string]string) Option

WithEnvMap returns an Option that seeds multiple environment variables.

func WithFixture 

func WithFixture(fixture string, path string) Option

WithFixture copies an embedded fixture directory into the sandbox jail.

func WithWd 

func WithWd(rel string) Option

WithWd returns an Option that sets the sandbox working directory.

type Options added in v1.0.0 

type Options struct {
	Data embed.FS
	Home string
	User string
}

Options holds optional settings provided to NewSandbox.

type Pipeline 

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

Pipeline manages execution of multiple stages with piped I/O.

func NewPipeline 

func NewPipeline(stages ...*PipelineStage) *Pipeline

NewPipeline constructs a Pipeline with the given stages.

func (*Pipeline) CaptureStderr 

func (p *Pipeline) CaptureStderr() *bytes.Buffer

CaptureStderr configures stderr capture and returns the buffer.

func (*Pipeline) CaptureStdout 

func (p *Pipeline) CaptureStdout() *bytes.Buffer

CaptureStdout configures stdout capture and returns the buffer.

func (*Pipeline) Run 

func (p *Pipeline) Run(ctx context.Context, rt *toolkit.Runtime) *PipelineResult

Run executes all stages concurrently with stdout piped stage-to-stage.

func (*Pipeline) RunWithTimeout 

func (p *Pipeline) RunWithTimeout(ctx context.Context, rt *toolkit.Runtime, timeout time.Duration) *PipelineResult

RunWithTimeout executes the pipeline with a deadline.

type PipelineResult 

type PipelineResult struct {
	Err      error
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

PipelineResult holds the outcome of pipeline execution.

type PipelineStage 

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

PipelineStage represents a single stage in a pipeline.

func Stage 

func Stage(name string, runner Runner) *PipelineStage

Stage constructs a PipelineStage with the given name and runner.

func StageWithName 

func StageWithName(name string, p *Process) *PipelineStage

StageWithName constructs a PipelineStage wrapping the provided Process.

type Process 

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

Process manages execution of a Runner with configurable streams.

func NewProcess 

func NewProcess(fn Runner, isTTY bool) *Process

NewProcess constructs a Process bound to a Runner function.

func NewProducer 

func NewProducer(interval time.Duration, lines []string) *Process

NewProducer constructs a Process that emits the provided lines to stdout.

func (*Process) CaptureStderr 

func (p *Process) CaptureStderr() *bytes.Buffer

CaptureStderr configures stderr capture and returns the buffer.

func (*Process) CaptureStdout 

func (p *Process) CaptureStdout() *bytes.Buffer

CaptureStdout configures stdout capture and returns the buffer.

func (*Process) Close 

func (p *Process) Close() error

Close closes the process stdin writer.

func (*Process) Run 

func (p *Process) Run(ctx context.Context, rt *toolkit.Runtime) *ProcessResult

Run executes the process runner synchronously using a cloned runtime.

func (*Process) RunWithIO added in v0.2.0 

func (p *Process) RunWithIO(ctx context.Context, rt *toolkit.Runtime, r io.Reader) *ProcessResult

func (*Process) SetArgs 

func (p *Process) SetArgs(args []string)

SetArgs sets the command-line arguments for the process.

func (*Process) SetStderr 

func (p *Process) SetStderr(w io.Writer)

SetStderr sets the error stream for the process.

func (*Process) SetStdin 

func (p *Process) SetStdin(r io.Reader)

SetStdin sets the input stream for the process.

func (*Process) SetStdout 

func (p *Process) SetStdout(w io.Writer)

SetStdout sets the output stream for the process.

func (*Process) StderrPipe 

func (p *Process) StderrPipe() io.Reader

StderrPipe returns a reader connected to the process stderr.

func (*Process) StdoutPipe 

func (p *Process) StdoutPipe() io.Reader

StdoutPipe returns a reader connected to the process stdout.

func (*Process) Write 

func (p *Process) Write(b []byte) (int, error)

Write writes data to the process stdin.

type ProcessResult 

type ProcessResult struct {
	Err      error
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

ProcessResult holds the outcome of process execution.

type Runner 

type Runner func(ctx context.Context, rt *toolkit.Runtime) (int, error)

Runner executes a unit of work using explicit runtime dependencies.

type Sandbox 

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

Sandbox bundles common test setup used by package tests.

func NewSandbox 

func NewSandbox(t *testing.T, options *Options, opts ...Option) *Sandbox

NewSandbox constructs a Sandbox and applies given options.

func (*Sandbox) AbsPath 

func (sandbox *Sandbox) AbsPath(rel string) (string, error)

AbsPath returns a runtime absolute path.

func (*Sandbox) Advance 

func (sandbox *Sandbox) Advance(d time.Duration)

Advance advances the sandbox test clock by the given duration.

func (*Sandbox) AtomicWriteFile 

func (sandbox *Sandbox) AtomicWriteFile(rel string, data []byte, perm os.FileMode) error

func (*Sandbox) Context 

func (sandbox *Sandbox) Context() context.Context

Context returns the sandbox context.

func (*Sandbox) DumpFileContent added in v1.0.0 

func (sandbox *Sandbox) DumpFileContent(rel string)

DumpFileContent reads and logs the content of a file in the sandbox.

func (*Sandbox) DumpJailTree 

func (sandbox *Sandbox) DumpJailTree(maxDepth int)

DumpJailTree logs a tree of files and directories rooted at the sandbox jail.

func (*Sandbox) GetHome 

func (sandbox *Sandbox) GetHome() (string, error)

GetHome returns the sandbox home.

func (*Sandbox) GetJail 

func (sandbox *Sandbox) GetJail() string

func (*Sandbox) Getwd 

func (sandbox *Sandbox) Getwd() (string, error)

Getwd returns the sandbox working directory.

func (*Sandbox) Mkdir 

func (sandbox *Sandbox) Mkdir(rel string, all bool) error

func (*Sandbox) MustReadFile 

func (sandbox *Sandbox) MustReadFile(rel string) []byte

MustReadFile reads a file under the jail and fails the test on error.

func (*Sandbox) MustWriteFile 

func (sandbox *Sandbox) MustWriteFile(path string, data []byte, perm os.FileMode)

MustWriteFile writes data under the jail and fails the test on error.

func (*Sandbox) Now 

func (sandbox *Sandbox) Now() time.Time

Now returns the current time from the sandbox test clock.

func (*Sandbox) ReadFile 

func (sandbox *Sandbox) ReadFile(rel string) ([]byte, error)

ReadFile reads a file located under the sandbox jail.

func (*Sandbox) ResolvePath 

func (sandbox *Sandbox) ResolvePath(rel string) (string, error)

ResolvePath returns an absolute runtime path with optional symlink resolution.

func (*Sandbox) Runtime added in v1.0.0 

func (sandbox *Sandbox) Runtime() *toolkit.Runtime

Runtime returns the sandbox runtime.

func (*Sandbox) Setwd 

func (sandbox *Sandbox) Setwd(dir string) error

Setwd sets the sandbox working directory.

func (*Sandbox) WriteFile 

func (sandbox *Sandbox) WriteFile(rel string, data []byte, perm os.FileMode) error

WriteFile writes data to a path under the sandbox jail.

type StageOption 

type StageOption func(s *PipelineStage)

StageOption configures a PipelineStage.

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.