exec

Documentation

Overview

Package exec provides an abstraction over command execution for testability. It allows production code to use real exec.Command while tests can inject mock executors that return pre-recorded responses.

Index

• func SetDefaultExecutor(e CommandExecutor)
• type CommandExecutor
  • func GetDefaultExecutor() CommandExecutor
• type CommandHandle
• type CommandMatcher
• type MockCall
• type MockExecutor
  • func NewMockExecutor(fallback CommandExecutor) *MockExecutor
  • func (e *MockExecutor) AddExactMatch(name string, args []string, response MockResponse)
  • func (e *MockExecutor) AddPrefixMatch(name string, prefixArgs []string, response MockResponse)
  • func (e *MockExecutor) AddRule(match CommandMatcher, response MockResponse)
  • func (e *MockExecutor) ClearCalls()
  • func (e *MockExecutor) CombinedOutput(ctx context.Context, dir string, name string, args ...string) ([]byte, error)
  • func (e *MockExecutor) GetCalls() []MockCall
  • func (e *MockExecutor) Output(ctx context.Context, dir string, name string, args ...string) ([]byte, error)
  • func (e *MockExecutor) Run(ctx context.Context, dir string, name string, args ...string) (stdout, stderr []byte, err error)
  • func (e *MockExecutor) Start(ctx context.Context, dir string, name string, args ...string) (CommandHandle, error)
• type MockResponse
• type MockRule
• type RealExecutor
  • func NewRealExecutor() *RealExecutor
  • func (e *RealExecutor) CombinedOutput(ctx context.Context, dir string, name string, args ...string) ([]byte, error)
  • func (e *RealExecutor) Output(ctx context.Context, dir string, name string, args ...string) ([]byte, error)
  • func (e *RealExecutor) Run(ctx context.Context, dir string, name string, args ...string) (stdout, stderr []byte, err error)
  • func (e *RealExecutor) Start(ctx context.Context, dir string, name string, args ...string) (CommandHandle, error)

Functions

func SetDefaultExecutor

func SetDefaultExecutor(e CommandExecutor)

SetDefaultExecutor sets the global default executor.

Types

type CommandExecutor

type CommandExecutor interface {
	// Run executes a command and returns stdout, stderr, and any error.
	Run(ctx context.Context, dir string, name string, args ...string) (stdout, stderr []byte, err error)

	// Output executes a command and returns stdout, or error with stderr context.
	Output(ctx context.Context, dir string, name string, args ...string) ([]byte, error)

	// CombinedOutput executes a command and returns combined stdout+stderr.
	CombinedOutput(ctx context.Context, dir string, name string, args ...string) ([]byte, error)

	// Start starts a command without waiting for it to complete.
	// Returns a CommandHandle that can be used to wait for completion.
	Start(ctx context.Context, dir string, name string, args ...string) (CommandHandle, error)
}

CommandExecutor abstracts command execution for testability. Production code uses RealExecutor, while tests use MockExecutor.

func GetDefaultExecutor

func GetDefaultExecutor() CommandExecutor

GetDefaultExecutor returns the global default executor.

type CommandHandle

type CommandHandle interface {
	// Wait blocks until the command completes and returns stdout, stderr, error.
	Wait() (stdout, stderr []byte, err error)

	// StdoutPipe returns a reader for stdout.
	StdoutPipe() *bytes.Buffer

	// StderrPipe returns a reader for stderr.
	StderrPipe() *bytes.Buffer
}

CommandHandle represents a running command.

type CommandMatcher

type CommandMatcher func(dir, name string, args []string) bool

CommandMatcher is a function that determines if a command matches.

type MockCall

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

MockCall records a command invocation for verification.

type MockExecutor

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

MockExecutor returns pre-recorded responses for commands. Commands are matched in order of rule registration.

func NewMockExecutor

func NewMockExecutor(fallback CommandExecutor) *MockExecutor

NewMockExecutor creates a new MockExecutor. If fallback is provided, unmatched commands will be delegated to it.

func (*MockExecutor) AddExactMatch

func (e *MockExecutor) AddExactMatch(name string, args []string, response MockResponse)

AddExactMatch adds a rule that matches a specific command exactly.

func (*MockExecutor) AddPrefixMatch

func (e *MockExecutor) AddPrefixMatch(name string, prefixArgs []string, response MockResponse)

AddPrefixMatch adds a rule that matches commands starting with specific args.

func (*MockExecutor) AddRule

func (e *MockExecutor) AddRule(match CommandMatcher, response MockResponse)

AddRule adds a matching rule with its response.

func (*MockExecutor) ClearCalls

func (e *MockExecutor) ClearCalls()

ClearCalls clears the recorded command invocations.

func (*MockExecutor) CombinedOutput

func (e *MockExecutor) CombinedOutput(ctx context.Context, dir string, name string, args ...string) ([]byte, error)

CombinedOutput executes a mocked command.

func (*MockExecutor) GetCalls

func (e *MockExecutor) GetCalls() []MockCall

GetCalls returns all recorded command invocations.

func (*MockExecutor) Output

func (e *MockExecutor) Output(ctx context.Context, dir string, name string, args ...string) ([]byte, error)

Output executes a mocked command.

func (*MockExecutor) Run

func (e *MockExecutor) Run(ctx context.Context, dir string, name string, args ...string) (stdout, stderr []byte, err error)

Run executes a mocked command.

func (*MockExecutor) Start

func (e *MockExecutor) Start(ctx context.Context, dir string, name string, args ...string) (CommandHandle, error)

Start starts a mocked command (returns immediately with buffered response).

type MockResponse

type MockResponse struct {
	Stdout []byte
	Stderr []byte
	Err    error
}

MockResponse defines the response for a mocked command.

type MockRule

type MockRule struct {
	Match    CommandMatcher
	Response MockResponse
}

MockRule defines a matching rule and its response.

type RealExecutor

type RealExecutor struct{}

RealExecutor executes commands using os/exec.

func NewRealExecutor

func NewRealExecutor() *RealExecutor

NewRealExecutor returns a new RealExecutor.

func (*RealExecutor) CombinedOutput

func (e *RealExecutor) CombinedOutput(ctx context.Context, dir string, name string, args ...string) ([]byte, error)

CombinedOutput executes a command and returns combined stdout+stderr.

func (*RealExecutor) Output

func (e *RealExecutor) Output(ctx context.Context, dir string, name string, args ...string) ([]byte, error)

Output executes a command and returns stdout, or error with stderr context.

func (*RealExecutor) Run

func (e *RealExecutor) Run(ctx context.Context, dir string, name string, args ...string) (stdout, stderr []byte, err error)

Run executes a command and returns stdout, stderr, and any error.

func (*RealExecutor) Start

func (e *RealExecutor) Start(ctx context.Context, dir string, name string, args ...string) (CommandHandle, error)

Start starts a command without waiting for it to complete.