Documentation
¶
Overview ¶
Package tmuxfixture gives tests a private tmux server that cannot reach a developer's real tmux server.
Isolation rules, all enforced before any tmux process is started:
- Every command is run as `tmux -S <socket> ...`. The socket is an absolute path inside a directory this fixture created; it never depends on TMUX, TMUX_TMPDIR or -L name resolution.
- The child environment has TMUX, TMUX_PANE and TMUX_TMPDIR removed, so nothing inherited from a surrounding tmux can select another server.
- Ownership is recorded on disk (owner.json with a random nonce) and is re-verified before each command. The socket must live inside the owned directory and must not be a default or inherited socket path.
- Callers cannot pass global options (-L, -S, -f, ...) or chain commands with ";". kill-server is never allowed.
- Sessions are created only through NewSession, which records the name before tmux runs. Cleanup kills exactly those recorded sessions with `kill-session -t =<name>`; it never kills the server.
Index ¶
- Variables
- func Env() []string
- func ExecTmux(argv []string, env []string) (string, error)
- func MaybeRunWrapper()
- func RunGuarded(m *testing.M) int
- func ShortTempBase() string
- func ValidateArgv(argv []string, socket, dir string) error
- type Executor
- type Fixture
- func (f *Fixture) Cleanup() ([]string, error)
- func (f *Fixture) CommandLogPath() string
- func (f *Fixture) Dir() string
- func (f *Fixture) KillSession(name string) error
- func (f *Fixture) NewSession(name, dir string, command ...string) error
- func (f *Fixture) Owner() (*Owner, error)
- func (f *Fixture) Owns(name string) bool
- func (f *Fixture) Run(args ...string) (string, error)
- func (f *Fixture) Socket() string
- type Options
- type Owner
- type Wrapped
Constants ¶
This section is empty.
Variables ¶
var ErrRejected = errors.New("tmuxfixture: rejected")
ErrRejected marks a command refused by the guard. A rejected command was never executed.
Functions ¶
func MaybeRunWrapper ¶
func MaybeRunWrapper()
MaybeRunWrapper must be the first call in TestMain. If this process was started as the tmux wrapper it never returns.
func RunGuarded ¶
RunGuarded is the TestMain for packages whose code runs tmux by name (cmd, session, web):
func TestMain(m *testing.M) { os.Exit(tmuxfixture.RunGuarded(m)) }
It (1) serves wrapper-mode invocations, (2) installs the test-only tmux wrapper so every real tmux exec carries an explicit owned -S socket, and sets a fake HOME so metadata side effects stay in a test store, (3) runs the tests, (4) removes any sessions left on the OWNED socket by exact name (never kill-server; nothing else lives on that socket), and removes the directory.
func ShortTempBase ¶
func ShortTempBase() string
ShortTempBase returns the directory fixture and wrapper dirs are created in: "/tmp" where it exists (short, because macOS limits socket paths to 104 bytes), otherwise the platform temp dir (e.g. on Windows, which has no /tmp; there are no tmux sockets there, but packages still install the guard in TestMain and must not fail before any test runs).
func ValidateArgv ¶
ValidateArgv checks a complete tmux argv just before execution: it must start with -S <socket> pointing inside the owned dir, carry no other global options, and never address a default/inherited server.
Types ¶
type Fixture ¶
type Fixture struct {
// contains filtered or unexported fields
}
Fixture is one private tmux server.
func New ¶
New creates a fresh fixture directory and ownership record. It does not start tmux; the server starts with the first NewSession.
func (*Fixture) Cleanup ¶
Cleanup kills exactly the recorded sessions (never the server) and returns the names it attempted. A session that is already gone is not an error.
func (*Fixture) CommandLogPath ¶
CommandLogPath is the durable audit log of every argv this fixture executed (one JSON array per line).
func (*Fixture) KillSession ¶
KillSession kills one fixture-owned session by exact name.
func (*Fixture) NewSession ¶
NewSession records name as owned, then creates it detached.
type Options ¶
type Options struct {
// BaseDir is where the fixture directory is created. Default "/tmp"
// (short, because macOS limits socket paths to 104 bytes).
BaseDir string
// Exec replaces the real tmux executor (tests of the guard itself).
Exec Executor
}
Options configures New.
type Owner ¶
type Owner struct {
Nonce string `json:"nonce"`
Socket string `json:"socket"`
Dir string `json:"dir"`
PID int `json:"pid"`
CreatedAt time.Time `json:"created_at"`
Sessions []string `json:"sessions"`
}
Owner is the durable ownership record written to <dir>/owner.json.
type Wrapped ¶
type Wrapped struct {
Dir string // fixture-owned directory
Socket string // owned socket every exec is pinned to
BinDir string // prepended to PATH
Home string // fake HOME for the package's tests
RealTmux string // absolute real tmux ("" if not installed)
}
Wrapped describes an installed wrapper.
func ActiveWrapper ¶
func ActiveWrapper() *Wrapped
ActiveWrapper returns the wrapper installed by RunGuarded, if any.
func InstallWrapper ¶
InstallWrapper creates the owned dir and socket record, a fake HOME, and the wrapper, and rewrites this process's environment:
PATH = <dir>/bin:<old PATH> (bin/tmux -> this test binary) HOME = <dir>/home (no real sessions.json/config) XDG_CONFIG_HOME, XDG_STATE_HOME, XDG_CACHE_HOME under the fake HOME TMUX, TMUX_PANE, TMUX_TMPDIR removed
If tmux is not installed the wrapper still installs, so a test that tries to exec tmux is rejected instead of finding one elsewhere.
func (*Wrapped) WrapperLogPath ¶
WrapperLogPath returns the audit log of a Wrapped install.
Source Files