Assertion API

Browser

(expect element).toBeVisible
(expect element).toBeEnabled
(expect element).toHaveValue expected
(expect machine.browser).toHaveLocation expectedSuffix
(expect machine.browser).toHaveTitle expectedTitle

Browser assertions use Playwright’s auto-waiting until timeout.

Containers

(expect container).toBeRunning
(expect container).toBeStopped

Desktop

(expect target).toBeVisible

Accepts desktop window and desktop text locators.

Filesystems and presence

(expect target).toExist
(expect target).toBeAbsent
(expect path).toBeFile
(expect path).toBeDirectory
(expect path).toBeSymlink
(expect path).toBeMounted
(expect target).toHaveContent expected
(expect target).toPointTo expected
(expect target).toHaveMode expected
(expect target).toBeOwnedBy user

Presence matchers accept path and user locators where applicable. Filesystem observations retry until the configured timeout.

HTTP

(expect response).toHaveStatus expected
(expect response).toHaveBody expected
(expect response).toHaveHeader { name, value }
(expect response).toHaveJsonValue { path, value }

HTTP matchers repeat the request until it matches or times out. Use them only with idempotent requests; use http.send for mutating requests.

Network endpoints

(expect endpoint).toBeReachable
(expect endpoint).toBeUnreachable

Endpoint observations retry until the configured timeout.

Saved results

(expect result).toHaveExitCode expected
(expect result).toHaveStdout expected
(expect result).toContainStdout expected

Result assertions inspect values saved by machine.run or http.send and do not repeat the original operation.

Services and command output

(expect service).toBeActive
(expect service).toBeInactive
(expect service).toBeFailed
(expect service).toHaveLog text
(expect target).toContain text
(expect machineCommand).toSucceed

Service targets may be system or user services. toContain accepts service logs and machine commands. All observations retry until timeout.

Users

(expect user).toBeMemberOf group

Use toExist and toBeAbsent for user existence.

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

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.