LibTmux.Testing 0.0.0-alpha.22

LibTmux.Testing

Scoped tmux servers, sessions and windows for testing code that drives tmux, on top of LibTmux.

Each scope owns what it created and tears it down on dispose, including after a failure, so a test that throws does not leave a server behind.

Add it to your test project:

$ dotnet package add LibTmux.Testing --prerelease

Alpha. The public API will change between prereleases without notice, so pin an exact version.

Quick start

Give a test a tmux server of its own, type into its pane, and wait for the result. The block uses ct from your test:

TmuxTestFactory factory = new();
await using TemporaryHierarchyScope scope = await factory.CreateHierarchyAsync(cancellationToken: ct);

await scope.Pane.SendTextAsync("echo $((6 * 7))", cancellationToken: ct);
await scope.Pane.EnterAsync(ct);

// The product is printed only once the shell has run the line.
string screen = await TmuxWait.UntilAsync(
    async token => string.Join('\n', await scope.Pane.CaptureAsync(cancellationToken: token)),
    text => text.Contains("42", StringComparison.Ordinal),
    TimeSpan.FromSeconds(10),
    TimeSpan.FromMilliseconds(20));

It prints nothing and returns once the pane shows 42. Disposing the scope kills the server, even when an assertion above it throws.

Create the scopes a test needs

TmuxTestFactory: a server, session, window, or whole hierarchy

CreateHierarchyAsync starts a server on a socket of its own, with one session, window, and pane.

The TemporaryServerScope, TemporarySessionScope, and TemporaryWindowScope types stop at the level their name gives. TmuxNameGenerator hands out names no live session is using.

TmuxWait.UntilAsync: wait for a state

It polls a state until a condition holds or a timeout passes, and it replaces a sleep. It ships in LibTmux, because reading back what a command produced is ordinary client work.

What it leaves out

• Test scaffolding in your application. This ships apart from LibTmux, so an application that references the client carries no test scaffolding in its output or its trim closure.
• Your own tmux. Left alone, a test gets a socket nothing else can use, so a throwaway server never points at your tmux or kills it on the way out.

Support and status

• Alpha. Any release may change or remove exported identifiers. Pin an exact version.
• Dependencies. LibTmux.
• tmux and .NET. The tmux versions LibTmux supports, on net8.0 and net10.0.
• Systems. Linux, including WSL. CI also runs macOS arm64 and builds on Windows x64.

Documentation

• Testing with libtmux on libtmux.org: an isolated server and cleanup failures
• TmuxTestFactory and TemporaryHierarchyScope
• Source: src/LibTmux.Testing; issues and history on GitHub

License

MIT