Terminal and Machine API

expect (terminal and machine)

These matchers receive locators created by either terminal interface implementation. They retry until they pass or the active backend times out.

toBeVisible

  (expect (terminal.getByText "ready")).toBeVisible

  (expect (machine.getByText "ready")).toBeVisible

Passes when the locator’s text appears in the visible terminal.

toEqual

  (expect (terminal.getByRegion region)).toEqual expected

  (expect (machine.getByRegion region)).toEqual expected

Passes when the selected terminal text equals expected. Trailing blank-cell whitespace is ignored, as are the surrounding newlines in a Nix multiline string.

getByRegion

terminal.getByRegion {
  left = 0;
  top = 0;
  width = 80;
  height = 10;
}

machine.getByRegion {
  left = 0;
  top = 0;
  width = 80;
  height = 10;
}

Selects a rectangle of terminal cells for use with (expect region).toEqual. Trailing blank-cell whitespace is omitted from the selected text. left and top default to 0; width and height default to the remaining visible grid. Coordinates are zero-based.

getByText

terminal.getByText text

machine.getByText text

Locates literal text in the visible terminal for use with (expect text).toBeVisible on either backend.

open

terminal.open commandOrPackage

machine.open commandOrPackage

Starts a command in a persistent terminal with the test filesystem root as its
working directory. Pass a package to resolve its executable with `lib.getExe`,
or a command string when arguments are needed. Only one terminal process is
active per test.

press

terminal.press keys

machine.press keys

Sends keys to the active terminal. Both backends recognize <leader>, <space>, <esc>, <escape>, <enter>, <cr>, <tab>, and <bs>. The machine backend additionally recognizes <c-w>.

print

terminal.print

machine.print

Prints the current terminal grid to the test log.

expect (machine command)

Machine matchers receive targets created by machine.command.

toEventuallySucceed

Retries the command until it succeeds or times out.

(expect (machine.command "test -e /run/example-ready")).toEventuallySucceed

toFail

Retries the command until it fails or the NixOS test driver times out.

(expect (machine.command "pgrep forbidden-process")).toFail

machine.configure

machine.configure {
  modules = [ module ];
}

Selects the NixOS machine backend and configures its NixOS modules. modules defaults to an empty list.

machine.getByPattern

machine.getByPattern "P.*ready"

Locates a regular expression in the visible machine terminal.