Documentation
¶
Overview ¶
Package fake is a scriptable, contract-verified test double for invoke.Environment.
The fake simulates a small POSIX-ish target: a virtual filesystem, a minimal shell and builtin vocabulary, and full transfer semantics between the real host filesystem and the virtual one. It passes the same invoketest contract suite the real providers pass, so tests written against it exercise contract-accurate lifecycle, error, and stream behavior — not a mock that can be programmed into impossible states.
Consumer-registered handlers take precedence over the builtin vocabulary; commands that are neither registered nor builtin fail with invoke.ErrNotFound, exactly as a missing binary does on a real target.
What the shell runs ¶
invoke.Shell scripts are interpreted, not executed, and the interpreter covers a subset: sequencing with ; and &&, single and double quotes, $NAME expansion, $(command) substitution, redirection to /dev/null and between the two output streams, cd, and exit.
A script reaching outside that subset is refused — wrapping invoke.ErrNotSupported, before any process exists — rather than run wrongly. Pipelines, || lists, redirection to a file, input redirection, backquotes, newline-separated commands, background commands, and the special and positional parameters ($?, $1, $$) are all refused by name. The alternative was worse than useless: an unrecognized character is just another character to a tokenizer, so a pipeline used to become arguments to the first command and `false || echo rescued` exited 1 having printed nothing, where every real target exits 0 having printed. A test asserting that is not merely unverified — it asserts the opposite of the truth.
The builtins are likewise a vocabulary rather than an implementation: they cover the options the contract suite and ordinary shell-outs use. Notably cat reads standard input and ignores file arguments, echo takes no flags, and test and cd do not follow symbolic links. A script needing more than the subset belongs in a handler registered with Environment.Handle, or on a real target.
Index ¶
- type Environment
- func (e *Environment) Calls() []invoke.Command
- func (e *Environment) Capabilities() invoke.Capabilities
- func (e *Environment) Close() error
- func (e *Environment) Download(ctx context.Context, remotePath, localPath string, ...) error
- func (e *Environment) FS() fs.FS
- func (e *Environment) Handle(name string, h Handler)
- func (e *Environment) LookPath(ctx context.Context, name string) (string, error)
- func (e *Environment) OS() invoke.TargetOS
- func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
- func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, ...) error
- type Handler
- type Option
- type Session
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Environment ¶
type Environment struct {
// contains filtered or unexported fields
}
Environment is a simulated execution target.
func New ¶
func New(opts ...Option) *Environment
New returns a fresh simulated target with an empty /tmp, a small base environment, and no recorded calls.
func (*Environment) Calls ¶
func (e *Environment) Calls() []invoke.Command
Calls returns the commands started so far, in order. Probe and cleanup commands issued by test helpers appear too: the record is honest.
func (*Environment) Capabilities ¶
func (e *Environment) Capabilities() invoke.Capabilities
Capabilities reports the simulated target's features: signal delivery and symlink-preserving transfers work; TTY allocation is not simulated.
func (*Environment) Close ¶
func (e *Environment) Close() error
Close marks the fake closed and terminates simulated processes still running. It is idempotent.
func (*Environment) Download ¶
func (e *Environment) Download(ctx context.Context, remotePath, localPath string, opts ...invoke.TransferOption) error
Download copies a virtual file or tree out to the real host filesystem, atomically per file via temp-and-rename.
func (*Environment) FS ¶
func (e *Environment) FS() fs.FS
FS returns a read-only io/fs.FS view of the fake target's filesystem, for asserting on target state with standard tooling (fs.ReadFile, fs.WalkDir, fstest.TestFS). Paths are unrooted io/fs paths: the target's /tmp/app.txt is "tmp/app.txt", and "." is the root.
The view is live — it reflects mutations as commands and transfers make them — and implements fs.ReadLinkFS, so symlinks are inspectable.
func (*Environment) Handle ¶
func (e *Environment) Handle(name string, h Handler)
Handle registers a handler for commands whose Path equals name, overriding any builtin of the same name.
func (*Environment) OS ¶
func (e *Environment) OS() invoke.TargetOS
OS reports the simulated target's operating system.
func (*Environment) Start ¶
func (e *Environment) Start(ctx context.Context, cmd invoke.Command, stdio invoke.IO) (invoke.Process, error)
Start launches a simulated process for cmd.
func (*Environment) Upload ¶
func (e *Environment) Upload(ctx context.Context, localPath, remotePath string, opts ...invoke.TransferOption) error
Upload copies a real host file or tree into the fake target's virtual filesystem, with the full transfer semantics providers share: per-file atomicity (nothing commits unless the source was read completely), modes preserved or forced umask-proof, symlink policies with containment, special files erroring by name, and real progress totals.
type Handler ¶
Handler simulates one command: it reads and writes the session streams and returns the exit code. Honoring ctx cancellation keeps a scripted command responsive to the lifecycle machinery, which handles the resulting classification (cancellation, Close, signals) itself.
type Session ¶
type Session struct {
// Stdin is the invocation's standard input (never nil; empty when
// the caller wired none).
Stdin io.Reader
// Stdout and Stderr are the invocation's output streams (never
// nil; discarding when the caller wired none).
Stdout io.Writer
Stderr io.Writer
// Dir is the working directory the command was started with.
Dir string
// Env is the resolved environment: the fake's base environment with
// the command's overlay applied, in "KEY=VALUE" form.
Env []string
}
Session is the execution state a Handler runs with.
Source Files