Skip to content
Select theme
Select languageEnglish

Testing API

acdev/test exports test, expect, describe, beforeAll, beforeEach, afterAll, afterEach, and everything from acdev/driver, including the types (Fixtures, AppWindow, Locator, Acde, E2eSettings and the option and result types below; import { type AppWindow } from 'acdev/test'). acdev/driver depends only on node: modules, so you can use it on its own in Node.js / Bun scripts.

test(name: string, body: (fixtures: Fixtures) => unknown, options?: TestOptions): void
test(name: string, options: TestOptions, body: (fixtures: Fixtures) => unknown): void
test.only / test.skip / test.todo(name) / test.if(condition)
type TestOptions = number | {
timeout?: number
size?: [width: number, height: number]
localStorage?: Record<string, string>
}
interface Fixtures {
acde: Acde
app: AppWindow | null
home: string
settings: E2eSettings
}

A number is the timeout in milliseconds. localStorage is written before the page loads (app.seedLocalStorage), then size sets the page's size (app.resize); both need the app fixture.

expect(locator: Locator): LocatorAssertions
expect(window: AppWindow): WindowAssertions
expect(value): bun:test Matchers
expect.poll(read: () => T | Promise<T>, options?: { timeout?: number; message?: string }): bun:test Matchers, each returning a Promise
expect.soft(locator | window | value): the same assertions; a failure is recorded and the test fails at its end

LocatorAssertions (all support .not and accept {timeout}):

toBeVisible() toBeHidden() toHaveCount(n) toHaveText(text, {exact?}) toContainText(text) toHaveValue(text) toHaveState(state) toBeChecked() toBeDisabled() toBeEnabled() toBeFocused() toHaveAttribute(name, value?) toHaveClass(text) toHaveCSS(property, text) (the computed style) toHaveJSProperty(name, value) toBeEmpty() toBeEditable() toBeInViewport({ratio?}) toHaveScreenshot(name?, options?)

WindowAssertions: toBeOpen() toHaveTitle(text) toHaveScreenshot(name?, options?)

text is a string or a RegExp. toHaveText and toContainText both compare the element's text content, not its accessible name. Screenshot options: {maxDiffPixels, maxDiffPixelRatio, threshold, mask: Locator[], timeout}.

class Acde {
static launch(options?: {
dirs?: string[]; desktop?: string; app?: string; out?: string
cwd?: string; env?: Record<string, string>; headless?: boolean
timeout?: number; startTimeout?: number; force?: boolean
}): Promise<Acde>
static attach(options?: { session?: number; cwd?: string; env?: Record<string, string>; timeout?: number }): Promise<Acde>
readonly desktop: AppWindow
readonly trace: Trace
window(match: string | { ref?: string; id?: number; app?: string; title?: string | RegExp }): AppWindow
open(name: string, options?: { timeout?: number }): Promise<AppWindow>
webs(): Promise<Web[]>
windows(): Promise<InspectWindow[]>
evaluate<T>(web: string, code: string): Promise<T>
snapshot(options?): Promise<{ text; windows; trees }>
query(options: { selector: string; window?: string; ref?: string; limit?: number; attributes?: string[] }): Promise<QueryResult>
act(ref: string, action: InspectAction, arg?): Promise<ActResult>
run(steps): Promise<ActResult>
screenshot(web: string, options?: { path?: string }): Promise<Shot>
screen(options?: { path?: string }): Promise<Shot>
console(options?: { web?; since?; limit?; level? }): Promise<{ entries; next; dropped }>
network(options?: { web?; since?; limit?; failed? }): Promise<{ entries; next; dropped }>
waitForRequest(url: string | RegExp, options?: { method?; web?; timeout? }): Promise<RequestEntry>
waitForConsole(text: string | RegExp, options?: { level?; web?; timeout? }): Promise<ConsoleEntry>
emulate(options: { colorScheme?: 'light' | 'dark' | null }): Promise<...>
chooseFolder(folder: string | null): Promise<void>
chooseFiles(files: string | string[] | null): Promise<void>
chooseSaveFile(file: string | null): Promise<void>
route(url: string | RegExp, response: RouteResponse, options?: { method?; web?; times? }): Promise<number>
unroute(id?: number): Promise<{ removed: number; left: number }>
pointer(x: number, y: number): Promise<{ x: number; y: number }> // a real pointer move to screen coordinates
clipboard(): Promise<string>
setClipboard(text: string): Promise<void>
addInitScript(code: string, options?: { web?: string; once?: boolean }): Promise<number>
removeInitScript(id?: number): Promise<{ removed: number; left: number }>
reload(web: string): Promise<void>
resize(web: string, width: number, height: number): Promise<{ width: number; height: number }>
answerDialog(web: string, answer?: { accept?: boolean; text?: string }): Promise<void>
dialogs(options?: { web?: string }): Promise<Dialog[]>
waitForDialog(options?: { web?: string; type?: 'alert' | 'confirm' | 'prompt'; timeout?: number }): Promise<Dialog>
input(web: string, events: InputEvent[]): Promise<ActResult>
permissions(): Promise<{ pending: PermissionPrompt[]; decisions: PermissionDecision[] }>
waitForPrompt(match?: { app?: string; capability?: string; timeout?: number }): Promise<PermissionPrompt>
allow(match?: { app?: string; capability?: string; timeout?: number }): Promise<PermissionPrompt>
deny(match?: { app?: string; capability?: string; timeout?: number }): Promise<PermissionPrompt>
answer(prompt: PermissionPrompt | number, allow: boolean): Promise<void>
revoke(app: string, capability: string): Promise<boolean>
drop(files: string | string[], options?: { web?: string; x?: number; y?: number }): Promise<{ web; window; files }>
ready(): Promise<boolean>
readonly closed: boolean
close(): Promise<void>
}
interface ActResult {
ok: boolean
text: string
ended?: true
}
  • launch starts an acdev dev session on the project's own runtime (Bun or Node.js) and waits until the windows of all pages have appeared, or an approval prompt waits (startTimeout, 120 seconds by default). With force, it starts even when another acdev dev runs the project (acdev dev --force); without it, that case is an error. When the session does not start, it ends that acdev dev and throws a LaunchError (an Error, exported by acdev/driver). Its message says how far the start got and ends with the last 40 lines of the output of acdev dev; logs holds the whole output (error.logs.tail(5000).text), and phase is:
    • 'exited': acdev dev exited (1) before it was ready:; code is the exit code (null in the other phases).
    • 'session': acdev dev (pid 4242) did not register a session within 120 s in <dir>, then the line no session yet: its build did not finish, or acdev runtime did not start listening; last output:.
    • 'window': acdev dev did not start within 120 s:, then the line acdev runtime runs and answers, but no window appeared (pages: 0, windows: 0) and no approval prompt waits; last output:.
    • 'failed': anything else that went wrong while it waited (the message is that error's, which is also the cause).
  • close() ends the session that launch started: it asks acdev runtime to quit, so acdev runtime and acdev dev end on their own. On macOS and Linux it also sends SIGTERM to acdev dev, then SIGKILL after 10 seconds. On Windows it waits up to 10 seconds for them to exit, then ends acdev dev and acdev runtime together (the whole process tree). On a session from attach it only disconnects; requests still waiting fail at once.
  • act answers ok: false when the action was not done. In a session that runs a single app, closing the app's only window ends the session, by design: the close that did it resolves with ok: true, ended: true and the text closed w1; acdev runtime exited with it, so acdev dev <pid> ended; closed becomes true, and every later request rejects with acdev dev <pid> is no longer connected. Any other request during which the runtime goes away rejects with acdev runtime closed the connection (also a close in a desktop session, and a run whose steps close the window).
  • choose* answers, in advance, the next picker of that kind the page opens; null means the user cancelled; relative paths resolve against the current directory. A headless session has no picker dialog, so a picker opened without an answer fails and the page sees it as cancelled.
  • Call waitFor* before the action that triggers it.
  • addInitScript registers code that runs before a page's own scripts on every load (once: on the next load only); web is a page name or an app id, and without it every page runs the code. It returns an id for removeInitScript, which removes every script when no id is given.
  • answerDialog answers the page's next alert / confirm / prompt in advance: accept: false cancels, text is what a prompt answers. Without an answer confirm gives false and prompt null. Dialog is { type, message, defaultValue, answered, accept, text }.
  • input sends raw events at page coordinates: { type: 'move' | 'down' | 'up' | 'wheel', x, y, button?, dx?, dy? }, { type: 'keydown' | 'keyup', key } and { type: 'text', text }. app.mouse and app.keyboard are built on it.
  • Camera and microphone prompts (PermissionPrompt is { id, app, label, capability, reason }, PermissionDecision is { app, label, capability, decision: 'granted' | 'denied' }): allow and deny wait for a prompt that matches (any prompt when nothing is given), answer it and return it; waitForPrompt only waits; answer answers a prompt you already have. Nothing answers a prompt by itself: getUserMedia() waits until the test answers. revoke takes a decision back and returns whether there was one. See Approvals in tests.
  • drop drops files from the system onto a page (default: the middle of the desktop page; web picks a page, x and y a point in it). The page gets a standard drop event a moment after the call returns, so wait for what the page does with it.
type RouteResponse =
| { status?: number; statusText?: string; headers?: Record<string, string>; contentType?: string; body?: string | Uint8Array; json?: unknown }
| { abort: true | string }

url is a glob (** matches anything, * matches anything except /; a glob starting with / is matched against the path plus query, otherwise against the whole URL) or a RegExp. Rules added later match first; a rule is removed automatically once its times are used up. Only fetch / XHR are affected, not WebSocket / EventSource.

class AppWindow {
getByRole(role: string, options?: RoleOptions): Locator
getByText(text: string | RegExp, options?: { exact?: boolean }): Locator
getByLabel / getByPlaceholder / getByTitle / getByAltText (text, options?): Locator
getByTestId(id: string): Locator
locator(selector: string): Locator
info(options?): Promise<InspectWindow>
isOpen(): Promise<boolean>
waitFor(options?: { state?: 'open' | 'closed'; timeout?: number }): Promise<void>
web(): Promise<string>
evaluate<T>(code: string): Promise<T>
snapshot(options?: { find?: string; diff?: boolean }): Promise<string>
screenshot(options?: { path?: string; mask?: Locator[] }): Promise<Shot>
press(keys: string): Promise<ActResult>
focus() / minimize() / restore() / fill() / fullscreen() / close(): Promise<ActResult>
readonly mouse: Mouse
readonly keyboard: Keyboard
readonly clock: Clock
addInitScript(code: string, options?: { once?: boolean }): Promise<number>
reload(options?: { timeout?: number }): Promise<void>
resize(width: number, height: number, options?: { timeout?: number }): Promise<{ width: number; height: number }>
seedLocalStorage(entries: Record<string, string>, options?: { timeout?: number }): Promise<void>
answerDialog(answer?: { accept?: boolean; text?: string }): Promise<void>
dialogs(): Promise<Dialog[]>
waitForDialog(options?: { type?: 'alert' | 'confirm' | 'prompt'; timeout?: number }): Promise<Dialog>
route / waitForRequest / waitForConsole / console / network / drop // as on Acde, scoped to this window
}
interface RoleOptions {
name?: string | RegExp; exact?: boolean
checked?: boolean; disabled?: boolean; selected?: boolean
expanded?: boolean; pressed?: boolean; focused?: boolean; level?: number
}

AppWindow looks itself up in the window table again on every use, so it keeps working if the window is closed and reopened.

info() is the window's row in that table: ref, id, app, title, state (normal, minimized, filled, fullscreen), focus, hidden and more. While a window is minimized, state is minimized, hidden is true, and locators find no element in it: toBeHidden() passes, and an action waits until its timeout (no element matches). restore() brings the window and its elements back. fill() fills the desktop's work area with the window and fullscreen() covers the whole host window with it (state filled / fullscreen); restore() sets either back to normal. Both are refused for the desktop and for a window that already fills the host window (a single-app session).

reload() waits until the new page has loaded; resize() sets the size of the page without the title bar and waits until innerWidth and innerHeight have it (a window that fills the screen resizes the host window, which Windows cannot do yet); seedLocalStorage() writes the entries before the page's scripts run, by reloading the page once.

class Mouse {
move(x: number, y: number, options?: { steps?: number }): Promise<ActResult>
down(options?: { button?: 'left' | 'right' | 'middle' }): Promise<ActResult>
up(options?: { button?: 'left' | 'right' | 'middle' }): Promise<ActResult>
click(x: number, y: number, options?: { button?; clickCount?: number; modifiers?: Modifier[] }): Promise<ActResult>
dblclick(x: number, y: number, options?: { button?; modifiers?: Modifier[] }): Promise<ActResult>
wheel(deltaX: number, deltaY: number): Promise<ActResult>
}
class Keyboard {
down(key: string) / up(key: string): Promise<ActResult>
press(keys: string): Promise<ActResult> // "Enter", "Control+a"
type(text: string): Promise<ActResult> // key presses; characters without a key are inserted as text
insertText(text: string): Promise<ActResult> // as the input method commits it, no key events
}
class Clock {
install(options?: { time?: number | string | Date }): Promise<ClockState>
fastForward(duration: number | string) / runFor(duration: number | string): Promise<ClockState>
pauseAt(time) / setFixedTime(time) / setSystemTime(time): Promise<ClockState>
resume() / state(): Promise<ClockState>
}
type Modifier = 'Shift' | 'Control' | 'Alt' | 'Meta' | 'ControlOrMeta'

Coordinates are CSS pixels of the page, as getBoundingClientRect() gives them. ControlOrMeta is Control on every system. A time is milliseconds since 1970, a Date or a date string; a duration is milliseconds, "mm:ss" or "hh:mm:ss". ClockState is { installed, paused, now, performanceNow, fixed, timers }. fastForward fires each timer that is due once, runFor fires every timer at its own time; setFixedTime makes Date stand still while timers go on, setSystemTime moves Date only.

close() waits until the window is gone. Closing the only window of a session that runs a single app ends the session: the call resolves with ended: true and a text that says so (see act under Acde), and the session takes no more requests. A test has no need to close that window, since its session ends with the test.

class Locator {
getByRole / getByText / getByLabel / … / locator(...) // search within this element
filter(options: { hasText?: string | RegExp; hasNotText?: string | RegExp; has?: Locator; hasNot?: Locator }): Locator
or(other: Locator) / and(other: Locator): Locator
nth(index: number) / first() / last(): Locator
count(): Promise<number>
all(): Promise<Locator[]>
isVisible(): Promise<boolean>
textContent(): Promise<string> // the text inside the element (what toHaveText compares)
text() / name() / value() / states() / ref() / node(): Promise<...>
waitFor(options?: { state?: 'visible' | 'hidden'; timeout?: number }): Promise<void>
click(options?: { button?: 'left' | 'right'; clickCount?: 1 | 2; modifiers?: Modifier[]; timeout?: number }): Promise<ActResult>
dblclick(options?: { modifiers?: Modifier[] }) / hover(options?: { modifiers?: Modifier[] }): Promise<ActResult>
focus() / clear(): Promise<ActResult>
evaluate<T>(fn: string | ((element, arg) => T), arg?: unknown): Promise<T>
fill(text: string) / type(text: string) / press(keys: string): Promise<ActResult>
scroll(dy?: number): Promise<ActResult>
selectOption(values: string | string[]): Promise<ActResult>
check() / uncheck() / setChecked(checked: boolean): Promise<void>
dragTo(target: Locator): Promise<ActResult>
screenshot(options?: { path?: string; mask?: Locator[] }): Promise<Shot>
}

When an action fails (ok: false), it is retried until the timeout, then ActError is thrown.

evaluate calls the function in the page with the element and arg (JSON), and returns its JSON result; fn may also be the source of such a function.

getByRole, getByText and getByLabel search the runtime's semantic tree, not the DOM:

  • Elements with opacity: 0 are not in it, so these locators do not find them.
  • getByText compares accessible names.

CSS locators (locator, getByTestId, getByPlaceholder, getByTitle, getByAltText) search the DOM and also match elements that are not rendered; toBeVisible, toBeHidden, isVisible() and waitFor({ state }) tell the two apart, and actions wait until the element is rendered.

Png.decode(bytes), Png.encode(image), Png.diff(actual, expected, {threshold}): PNG encoding/decoding using only node:zlib, plus a pixelmatch-style comparison. The screenshot assertions are built on it. Png.animate(frames) joins PNGs of one size ({ png, ms } each) into an animated PNG; Video.start(acdev) records the screen with it (stop(), then write(path)), which is what acdev test --video keeps.