Fixture API

browser

Browser actions run through Playwright on the machine backend. Access a bound browser through machine.browser.

machine.browser.start
machine.browser.open url
machine.browser.getByRole role { name ? ""; }
machine.browser.getByLabel label
machine.browser.getByPlaceholder placeholder
machine.browser.getByText text
machine.browser.getByTitle title

Locator methods return browser element locators. Action methods execute once.

container

container.locate machine name
(machine.container name).start
(machine.container name).stop
(machine.container name).restart
(machine.container name).run command

locate returns a declarative NixOS container locator. The remaining methods create one-shot actions for that container.

desktop

desktop.getByWindow machine title
desktop.getByText machine text
desktop.press machine keys
desktop.type machine text
desktop.screenshot machine name

Desktop tests use the machine backend. Locators can be passed to visibility matchers; input and screenshot methods execute once.

expect

Call expect with a locator to obtain its built-in and custom matchers. Matcher signatures are listed in the Assertion API.

filesystem

filesystem.path machine path
filesystem.file machine path
filesystem.directory machine path
filesystem.symlink machine path
filesystem.mount machine path
filesystem.jsonFile machine path
filesystem.root
filesystem.writeFile relativePath content
filesystem.makeDirectory relativePath
filesystem.copyFile source relativeDestination
filesystem.copyTree source relativeDestination
filesystem.symlinkFile target relativeLinkPath
filesystem.setMode relativePath mode
filesystem.remove relativePath

Locator methods observe paths on a supplied machine. Mutation methods prepare files under an isolated runtime root shared by terminal and default-machine tests. Relative paths cannot be empty, absolute, ., or contain ...

http

http.get machine request
http.getJson machine request
http.request machine method request
http.send machine {
  method = "POST";
  url = "http://localhost/items";
  headers = { };
  body = null;
  saveAs = "create-item";
}

A request may be a URL string or { url, headers ? { }, body ? null }. Observation methods return retryable locators and must be idempotent. send executes once and stores a command result under saveAs.

machine and machines

machine.configure { modules ? [ ]; }
machines.configure { server.modules = [ ]; client.modules = [ ]; }
machines.node name
machine.command command
machine.run { command, saveAs }
machine.service name
machine.userService user name
machine.file path
machine.directory path
machine.symlink path
machine.mount path
machine.user name
machine.container name
machine.endpoint.tcp portOrOptions
machine.endpoint.udp portOrOptions
machine.http.get request
machine.browser.start
machine.browser.open url
machine.browser.getByText text
machine.open commandOrPackage
machine.press keys
machine.print
machine.getByText text
machine.getByPattern pattern
machine.getByRegion { left ? 0, top ? 0, width ? null, height ? null }
machine.start
machine.shutdown
machine.reboot
machine.crash

machine addresses the default VM. machines.node name returns the same per-machine interface for a named VM. Lifecycle properties and print are actions, not functions. The default VM needs no explicit configuration. Use machine.configure to add NixOS modules and machines.configure to define named-machine topology.

network

network.endpoint {
  from = machine;
  host = "server";
  port = 8080;
  transport = "tcp";
}
network.partition { left = [ server ]; right = [ client ]; }
network.heal { left = [ server ]; right = [ client ]; }

host defaults to 127.0.0.1 and transport defaults to tcp. Ports must be integers from 1 through 65535. Partition and heal execute once.

result

result.command name
result.stdout name
result.exitCode name

These methods locate results saved by machine.run or http.send. Assertions inspect the saved value without repeating the original side effect.

service

(machine.service name).start
(machine.service name).stop
(machine.service name).restart
(machine.service name).reload
(machine.service name).logs

Targets come from machine.service, machine.userService, or user.service. Lifecycle methods execute once; logs returns a matcher target.

user

user.locate machine name
user.run target command
user.service target serviceName

locate returns a user locator. run executes a command once as that user, while service returns a user-level service locator.