proc

Documentation

Overview

Package proc provides a small abstraction over os/exec so production code can take a dependency on Runner instead of calling exec.Command directly. Tests substitute Fake to script command output and assert on the call shape without spawning real subprocesses.

Index

• type Call
• type Cmd
• type Fake
  • func NewFake() *Fake
  • func (f *Fake) CallCount() int
  • func (f *Fake) Calls() []Call
  • func (f *Fake) On(m Matcher, resp Response) *Fake
  • func (f *Fake) OnExact(name string, args []string, resp Response) *Fake
  • func (f *Fake) Reset()
  • func (f *Fake) Run(_ context.Context, cmd Cmd) (Result, error)
• type Matcher
  • func MatchExact(name string, args ...string) Matcher
  • func MatchPrefix(name string, args ...string) Matcher
• type OS
  • func (OS) Run(ctx context.Context, cmd Cmd) (Result, error)
• type Response
• type Result
• type Runner

Types

type Call

type Call struct {
	Name string
	Args []string
	Dir  string
}

Call records a single invocation observed by Fake.

type Cmd

type Cmd struct {
	// Name is the executable to run (e.g. "git").
	Name string
	// Args are the arguments passed to Name.
	Args []string
	// Dir, if non-empty, sets the subprocess's working directory.
	Dir string
	// Env, if non-nil, replaces the subprocess's environment. nil
	// inherits the parent process's environment.
	Env []string
	// Stdin, if non-empty, is written to the subprocess's stdin.
	Stdin []byte
}

Cmd describes a command invocation. Zero values are sane defaults: no working directory override, no extra environment, empty stdin.

type Fake

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

Fake is a Runner that replays scripted responses based on Matcher rules and records every call it observes. Fake is safe for concurrent use.

When no rule matches an incoming Cmd, Run returns an error describing the unexpected call. This makes tests fail loudly when the code under test invokes commands the test did not anticipate.

func NewFake

func NewFake() *Fake

NewFake returns an empty Fake. Use On to register responses.

func (*Fake) CallCount

func (f *Fake) CallCount() int

CallCount returns how many calls Fake has observed.

func (*Fake) Calls

func (f *Fake) Calls() []Call

Calls returns a copy of every call observed so far, in invocation order. Args slices are also copied so callers can mutate the result safely.

func (*Fake) On

func (f *Fake) On(m Matcher, resp Response) *Fake

On registers resp as the response to commands matching m. Rules are evaluated in registration order; the first match wins.

func (*Fake) OnExact

func (f *Fake) OnExact(name string, args []string, resp Response) *Fake

OnExact is a convenience for On(MatchExact(name, args...), resp).

func (*Fake) Reset

func (f *Fake) Reset()

Reset clears observed calls. Registered rules are kept.

func (*Fake) Run

func (f *Fake) Run(_ context.Context, cmd Cmd) (Result, error)

Run records the call and returns the first matching response, or an error if no rule matches.

type Matcher

type Matcher func(Cmd) bool

Matcher decides whether a Cmd should produce a given Response.

func MatchExact

func MatchExact(name string, args ...string) Matcher

MatchExact returns a Matcher that requires Name and Args (in order) to equal the given values. Dir and Env are not compared.

func MatchPrefix

func MatchPrefix(name string, args ...string) Matcher

MatchPrefix returns a Matcher that requires Name to equal name and the first len(args) entries of Cmd.Args to equal args. Useful for matching "git diff ..." regardless of trailing arguments.

type OS

type OS struct{}

OS is a Runner backed by os/exec.

func (OS) Run

func (OS) Run(ctx context.Context, cmd Cmd) (Result, error)

Run implements Runner using exec.CommandContext.

type Response

type Response struct {
	Result Result
	Err    error
}

Response describes a scripted reply Fake should return for a matched call. Err, when non-nil, is returned as the second return from Run; otherwise Result is returned with err == nil.

type Result

type Result struct {
	Stdout   []byte
	Stderr   []byte
	ExitCode int
}

Result captures the outcome of running a Cmd. ExitCode is 0 on success, non-zero on failure, and -1 when the process could not be started or was killed before reporting status (e.g. context cancel).

type Runner

type Runner interface {
	// Run executes cmd and returns the result. Run returns an error
	// only when the command could not be invoked at all (e.g. binary
	// not found, context canceled). A non-zero ExitCode is reported
	// via Result, not error, so callers can decide whether non-zero
	// is a failure for their use case.
	Run(ctx context.Context, cmd Cmd) (Result, error)
}

Runner runs commands. Implementations must be safe for concurrent use.

var Default Runner = OS{}

Default is a process-wide OS runner for callers that cannot reach a composition root. Prefer injecting a Runner explicitly.