shotbox

Lint the accessibility tree for nodes a screen reader has no name to say for: controls, images (not inside a named control) and anything else that takes the focus. The answer: a tree line each, with bounds, then what's wrong; or "No problems.". Use it to check labels after a change; for colors, use check_contrast.

Check that text, buttons, links and images stand out from their background: WCAG's 4.5:1 for text (3 for large text) and 3:1 for images unless text_ratio and graphics say otherwise, and with edges, a button's or field's edge too. It raises the window and measures a picture of the screen in each node's bounds. The answer: each node that fails, a tree line with bounds, its ratio and colors, or "No problems."; with passes, then each that passes, the same; then what it couldn't measure, which doesn't fail unless strict (too small, off the screen, or GTK 4.14+'s, whose positions are wrong: of that, only text is measured, where it's found near them), then what's behind a modal dialog, not measured, which doesn't fail even with strict (check it with the dialog closed), and why. A window where nothing can be measured is an error, not a pass. Switches, sliders, check boxes, disabled nodes and what's scrolled out of view are skipped. For missing names, use check_accessible_names.

Check the keyboard focus order in one call: press Tab, or key, until the focus comes back round, and list where it went, a tree line each, after a "began in" line. Then the controls the key never reached, and how it ended: round again (fine), stuck (a trap, or a text view nothing leaves), not round after most presses, lost (no node has the focus), stopped (a text view closed as it was left), never in the page (with document, a page with controls), left the page (a web editor that keeps Tab, left by F6, and Tab never back), or nothing focused to begin with (click the window with click_element first). With visible, "focus not shown on N" counts stops that don't show it. A text view that takes Tab is left as a person would, with ctrl+Tab, shift+Tab, Escape or F6. The focus stays where it ended. To press a few keys yourself, use press_keys.

Click an element by its accessible name, or a point by x and y, on the screen or inside a window. By name is the one to use: it waits up to timeout seconds for the node to show, be placed and enabled, hold still and be uncovered (else it says which it isn't), raises its window and clicks its middle, and the answer gives the node and its bounds. When two nodes match it lists them, with where they are; when none does, the nearest names. A click gives a window the keyboard, which nothing else does on X11. hold and state, by x and y, hold the button as press_keys holds keys.

Read what a screen reader would find: every visible node, a line each, indented, with its role, name, description and the states a screen reader says (focusable, focused, checked...). The cheapest way to see what's on screen and what can be clicked by name. A node with an empty name ("") is one a screen reader can say nothing for. Use take_screenshot for how it looks.

Read the last lines (40, or lines) a spawned program wrote to stdout and stderr, after a line saying whether it's still running or exited, with its status. It works after the program has exited, until the session stops; for a program spawned more than once, it reads the latest. Use it when a window never comes up or a program seems to have crashed; to wait for a line in a log file, use wait_for line.

Hear what Orca, a real screen reader, says as the focus moves: it starts Orca in the session, presses Tab until the focus comes round (or keys, in turn), and answers a (start) line, then a line a press: the focused node's tree line, then what Orca said. Tab stops before a text view, which would take it as typing. Use it over get_accessible_tree when what's heard matters (labels, mnemonics, states, silent stops). Orca takes seconds to start.

List what programs in the session have announced to a screen reader since it started, oldest first, a line each with its politeness: "polite: Saved", "assertive: Error". That's GTK's announcements, a browser's live regions, alerts and info bars as they appear (GTK 3's, Qt's, libadwaita's) and the focus renamed. Reading doesn't clear them; "Nothing announced yet." means none so far. Use it to check what a screen reader user heard after an action; to wait for one, use wait_for announcement.

Press keys in turn, each a chord: Tab, Return, Escape, ctrl+s, alt+shift+Tab, F6. They go to whatever has the keyboard; click a window first with click_element if nothing does. hold presses them all together and keeps them down that long (walking while running); state down leaves them down, across calls, until a call with state up (move or click while a key is held). The answer says what it pressed.

Record a session's sound and say how it was: call with action start, have the program play, then call with action stop. The session must have been started with audio. stop answers with the sound's length, its peak and RMS level in dBFS, the samples clipped, and each gap of silence between the first sound and the last (what a program that falls behind leaves), then any problem found. The sound itself isn't returned or kept; to keep it, use record_video with sound. Raise gap when the program is meant to fall silent between sounds, as between two beeps.

Record a video of the screen, or of one window, and save it as an .mp4: in the session's scratch directory, gone when the session stops, or at path. The answer is the saved path, how long the clip is, and up to 8 frames from it RETURNED AS ONE IMAGE, with the times they show: you can't play the clip, but a person or another tool can. A clip stops at 100 MB. sound also says what it heard, as record_audio does. until_line ends it at an event instead; the answer gives the line. For a few moments of motion, take_screenshot's burst is cheaper.

Turn the mouse wheel over a node by its name, found as click_element finds it (waiting for it, its window raised), or at a point by x and y, leaving the pointer there. Use it for what's past a list's, a page's or a window's edge, then wait_for stable and look again; to move the keyboard focus, use press_keys.

Start one of the programs the person allowed this server to run, by its name, in a session; nothing else can run. The answer gives its pid. Then wait_for its window, by the program's name, before looking at it. If it doesn't come up, get_program_output says why.

Start a sealed session: a display of its own (X11 under Xvfb, or Wayland under a headless sway), its own D-Bus and accessibility bus, and a scratch home. Nothing in it reaches the desktop of the person you're working for, and nothing of theirs reaches it. The answer gives its name, display and size, the programs spawn_program can start in it, and anything it couldn't seal. It lasts until stop_session.

Stop a session start_session made, when you're done with it: every program in it is killed, unsaved work and all, and its scratch directory is deleted, with any clip record_video saved there (one saved at a path is kept). In a session started with usage, the answer says its programs' peak memory and CPU time. You needn't stop sessions before the server ends: they all stop with it.

Take a picture of the screen, or of one window, RETURNED AS AN IMAGE for you to look at: the only way to see colors, layout and what's drawn. Pictures cost far more than get_accessible_tree; take the window rather than the screen, and crop when you need a part; zoom enlarges one to read small text. vision checks nothing is told apart by color alone; burst, as one image, is for motion, an animation or a transition. labels numbers each named node's box on it, to click by name what you see. The answer gives its size, if it's scaled or a part how an x,y on it maps to click_element's, and with labels each number's tree line.

Type text into whatever has the keyboard focus, a key at a time. ASCII only: a character with no key fails the call, once what's before it is typed. For keys and shortcuts (Return, ctrl+s), use press_keys.

Work a virtual gamepad, in a session started with gamepads: press buttons together, tapped, held for hold seconds, or with state down left down until a call with state up; push a stick to x, y; pull a trigger to value; or neutral, letting go of everything. A stick or trigger stays where it's put, unless hold says for how long. Programs in the session see a real Xbox 360 controller, and none of the machine's. For keys and the mouse, press_keys and click_element.

Wait until something is so, instead of sleeping; it fails after timeout seconds, saying so, and listing the windows there are when a window never came. what says what to wait for, and value which: window: a title, exactly or as a regex, app=RE, or the name a program was started by with spawn_program, for its window whatever its title; answers with the window's title, size and place. stable: the screen (or window) unchanged for value seconds (0.5; up to 60), as after a click, for the repaint. announcement: a regex in what was announced to a screen reader; each is waited for once. focus: the name of the node with the keyboard focus, as click_element takes one; answers with its tree line. node: a regex in the name or text of a node showing in the accessible tree, as a status line saying a page is drawn, where the screen holding still says nothing; answers with its tree line, and its text if that matched. match: a PNG's path, from the allow file's directory, that the screen (or window, cropped to crop) should look like; answers how long it took. change: any change from how it looked when the wait began; answers how long it took. line: a regex in a line of file written after the wait starts (or, with from_start, anywhere in it), for a program that logs its events; a file not there yet is waited for, and one rotated or rewritten is read from the top; answers with the line. To see how things are now, without waiting, use get_accessible_tree.