Waiting and retrying

After sending input or starting a process, wait for the state your next step requires. Pane interaction covers waiting for screen text. This page covers arbitrary conditions and tmux’s named $wait-for signal channels.

Polling a condition¶

Polling checks a condition repeatedly until it succeeds or a deadline expires. Set a deadline and choose an interval that limits unnecessary tmux commands.

Helper: ftmuxtest.WaitFor(ctx, interval, condition)

Where it lives: tmuxtest, a separate test-support package from tmux

Examples¶

ftmuxtest.WaitFor probes immediately, then at the requested positive interval. It returns a probe error or context error unchanged. Each probe must read fresh state and honor its context. mSession.Windows() only reads a stored snapshot; use mSession.SearchWindows to query tmux on every probe.

waitCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
err := tmuxtest.WaitFor(waitCtx, 50*time.Millisecond, func(ctx context.Context) (bool, error) {
	windows, err := session.SearchWindows(ctx, nil)
	if err != nil {
		return false, err
	}
	for _, w := range windows {
		if name, ok := w.Name(); ok && name == "build" {
			return true, nil
		}
	}
	return false, nil
})
if err != nil {
    return fmt.Errorf("wait for build window: %w", err)
}

tmux’s own $wait-for channel¶

Use $tmux wait-for -S <channel> to signal and tmux wait-for <channel> to block until signalled. This avoids repeated screen captures when the command can announce its own completion:

Call mServer.WaitFor with a SWaitForRequest. Set its mode to kWaitForModeSignal to signal the channel; the zero-value mode waits.

if err := server.WaitFor(ctx, tmux.WaitForRequest{
    Channel: "built", Mode: tmux.WaitForModeSignal,
}); err != nil {
    return err
}
if err := server.WaitFor(ctx, tmux.WaitForRequest{Channel: "built"}); err != nil {
    return err
}

tmux remembers a signal sent before a waiter starts. The next wait on that channel returns immediately, so completion is not lost when the command finishes first.

A raw wait-for client can exit zero when the server dies, as well as when the channel is signalled. Verify server liveness when a lost server must be treated as a failed task.

Use a channel name specific to the task. A remembered signal can otherwise satisfy an unrelated later wait.