Actions Reference

Overview

CUP defines 15 canonical actions that map to native platform APIs. Every action works identically across Windows, macOS, Linux, and Web.

Element IDs are ephemeral — they're only valid for the most recent snapshot. Always re-capture after performing actions.

Click actions

click

Invoke or activate an element — the most common action.

session.action("e14", "click")

await session.action("e14", "click");

doubleclick

Double-click an element (e.g., to select a word in a text field).

session.action("e5", "doubleclick")

await session.action("e5", "doubleclick");

rightclick

Open a context menu.

session.action("e8", "rightclick")

await session.action("e8", "rightclick");

longpress

Long-press for touch/mobile interactions.

session.action("e3", "longpress")

await session.action("e3", "longpress");

Input actions

type

Type text into a text field. Replaces the current selection or appends at cursor.

session.action("e5", "type", value="hello world")

await session.action("e5", "type", { value: "hello world" });

setvalue

Set an element's value programmatically (e.g., slider, spinbutton, or text field).

session.action("e12", "setvalue", value="75")

await session.action("e12", "setvalue", { value: "75" });

toggle

Toggle a checkbox or switch element.

session.action("e9", "toggle")

await session.action("e9", "toggle");

scroll

Scroll a scrollable container in a direction.

session.action("e3", "scroll", direction="down")
session.action("e3", "scroll", direction="up")
session.action("e3", "scroll", direction="left")
session.action("e3", "scroll", direction="right")

await session.action("e3", "scroll", { direction: "down" });
await session.action("e3", "scroll", { direction: "up" });
await session.action("e3", "scroll", { direction: "left" });
await session.action("e3", "scroll", { direction: "right" });

select

Select an item in a list, tree, or tab.

session.action("e8", "select")

await session.action("e8", "select");

expand / collapse

Toggle the expanded/collapsed state of a tree item, accordion, or menu.

session.action("e4", "expand")
session.action("e4", "collapse")

await session.action("e4", "expand");
await session.action("e4", "collapse");

increment / decrement

Adjust the value of a slider or spinbutton.

session.action("e12", "increment")
session.action("e12", "decrement")

await session.action("e12", "increment");
await session.action("e12", "decrement");

focus

Move keyboard focus to an element.

session.action("e7", "focus")

await session.action("e7", "focus");

dismiss

Dismiss a dialog, popup, or notification.

session.action("e1", "dismiss")

await session.action("e1", "dismiss");

Session-level actions

These don't target a specific element:

press

Send a keyboard shortcut.

session.press("ctrl+s")       # Save
session.press("ctrl+shift+p") # Command palette
session.press("enter")        # Confirm
session.press("escape")       # Cancel
session.press("alt+f4")       # Close window

await session.press("ctrl+s");       // Save
await session.press("ctrl+shift+p"); // Command palette
await session.press("enter");        // Confirm
await session.press("escape");       // Cancel
await session.press("alt+f4");       // Close window

For executing multiple actions in sequence, see batch() in the Session API. For the ActionResult type returned by all actions, see Action results.