test_app: Test an app without a terminal

In termr: Modern Reactive Terminal Applications with Data Workflows

Test an app without a terminal

Description

Starts the app with a headless driver and returns a Pilot that simulates the user. Every action runs one tick of the real event loop (input -> events -> timers -> repaint), and the output goes through the real renderer into a virtual terminal, so tests see exactly what a user would see.

Usage

test_app(app, width = 80L, height = 24L, color_mode = "truecolor")

Arguments

app	An App or a widget.
width, height	Virtual terminal size.
color_mode	Colour support of the virtual terminal: "truecolor" (default), "256", "16" or "none" (monochrome, as with NO_COLOR).

Details

Pilot methods:

• press(...): press keys, e.g. press("tab", "enter", "ctrl+c");

• type(text): type characters;

• resize(width, height): resize the terminal;

• advance(seconds): let simulated time pass (fires timers);

• click(target, y = NULL, button = "left"): click a widget (a selector or widget; the centre of its visible part is used) or a position click(x, y);

• hover(target), scroll(target, direction = "down", times = 1): move the pointer, turn the mouse wheel;

• mouse(action, x, y, button, direction): send a raw mouse event;

• drag(from, to, button = "left", steps = 3): press, move and release between two positions (selectors, widgets or c(x, y));

• paste(text): deliver a bracketed paste; system_clipboard(): text of the last OSC 52 write;

• focus(target), find(selector): focus a widget, find one;

• wait_for(condition, timeout = 5): step the event loop (simulated time, real time while workers run) until condition(app) is TRUE;

• run_worker(fn, ..., wait = TRUE): start a worker and wait for it;

• wait_for_workers(timeout): wait for background workers to finish;

• screen_text(): the visible screen as a character vector;

• snapshot(): print the screen (for testthat::expect_snapshot());

• query_one(selector), query(selector): find widgets;

• stop(): exit the app and restore the (virtual) terminal.

Fields: app, driver, exited and value (the value passed to app$exit()).

Value

A Pilot object.

Examples

pilot <- test_app(app(input(id = "name")), width = 30, height = 5)
pilot$type("Ada")
pilot$query_one("#name")$value
pilot$stop()

termr documentation built on Oct. 21, 2026, 5:13 p.m.