Helper Utilities

Utils

Random gesture helpers, server connectivity, and node waiting utilities

Access these methods through agent.utils. Utility methods for human-like interactions, server connectivity, and waiting for UI elements.

`randomClick()`

TypeScript

randomClick(x1: number, y1: number, x2: number, y2: number): void

Performs a tap at a random position within the specified rectangle. Useful for making automations appear more human-like.

Parameters

Name	Type	Description
`x1`	`number`	Left boundary
`y1`	`number`	Top boundary
`x2`	`number`	Right boundary
`y2`	`number`	Bottom boundary

Examples

Using node.randomClick (preferred)

TypeScript

const button = screen.findTextOne("Submit");
if (button) {
  button.randomClick();
}

Using agent.utils.randomClick (legacy)

TypeScript

const { left, top, right, bottom } = button.boundsInScreen;
agent.utils.randomClick(left, top, right, bottom);

`randomSwipe()`

TypeScript

randomSwipe(x1: number, y1: number, x2: number, y2: number, direction: "up" | "down" | "left" | "right"): void

Performs a swipe starting from a random position within the rectangle, moving in the specified direction.

Parameters

Name	Type	Description
`x1`	`number`	Left boundary
`y1`	`number`	Top boundary
`x2`	`number`	Right boundary
`y2`	`number`	Bottom boundary
`direction`	`"up" \| "down" \| "left" \| "right"`	Swipe direction

Examples

Using node.randomSwipe (preferred)

TypeScript

const scrollView = screen.findAdvanced(f => f.isScrollable());
if (scrollView) {
  scrollView.randomSwipe("up");
}

Using agent.utils.randomSwipe (legacy)

TypeScript

agent.utils.randomSwipe(100, 500, 900, 1500, "up");

`isServerReachable()`

TypeScript

isServerReachable(): Promise<{ reachable: true } | { reachable: false; error: string }>

Checks if the server is reachable. Useful for verifying connectivity before performing server-dependent operations.

Returns

{ reachable: true } | { reachable: false; error: string }Object indicating server reachability status

Examples

TypeScript

const status = await agent.utils.isServerReachable();
if (status.reachable) {
  console.log("Server is reachable");
  // Proceed with server operations
} else {
  console.log("Server unreachable:", status.error);
  // Handle offline scenario
}

`recordStat()`

TypeScript

recordStat(stat: string): Promise<{ success: true } | { success: false; error: string }>

Records a stat event for the current automation. Stats are free-form strings (max 64 characters) counted over time — call it any time, as often as you like, to track anything worth graphing. Each stat is recorded locally (no API call) together with the time elapsed since automation start, and sent to the server automatically with the final job.submitTask submission. Recorded stats are shown on the performance page's "Stats" tab, with one line per distinct stat string plus its average duration.

Parameters

Name	Type	Description
`stat`	`string`	The stat string to record (1-64 characters)

Returns

{ success: true } | { success: false; error: string }Success flag, or error message for an invalid stat string

Examples

TypeScript

// Count how often specific situations occur
await agent.utils.recordStat("captcha-shown");
await agent.utils.recordStat("login-retried");

// Stats are sent automatically when the task is submitted —
// view counts and average durations on the performance page's Stats tab

`waitForNode()`

TypeScript

waitForNode(condition: (node: AndroidNode) => boolean, durationMs?: number, intervalMs?: number): Promise<boolean>

Waits for a node matching the condition to appear on screen. Polls the screen at regular intervals until the condition is met or timeout is reached.

Parameters

Name	Type	Description
`condition`	`(node: AndroidNode) => boolean`	Function that returns true when the desired node is found
`durationMs?`	`number`	Maximum time to wait in milliseconds(default: `30000`)
`intervalMs?`	`number`	Polling interval in milliseconds(default: `500`)

Returns

booleantrue if the node was found, false if timeout was reached

Examples

Wait for a button to appear

TypeScript

const found = await agent.utils.waitForNode(
  node => node.text === "Continue" && node.isClickable,
  10000, // 10 second timeout
  500    // Check every 500ms
);

if (found) {
  const screen = await agent.actions.screenContent();
  screen.findTextOne("Continue")?.click();
}

Wait for loading to complete

TypeScript

// Wait for progress indicator to disappear and content to load
const contentLoaded = await agent.utils.waitForNode(
  node => node.contentDescription?.includes("Main content"),
  15000
);

if (!contentLoaded) {
  console.log("Timeout waiting for content to load");
}

`waitForNodeGone()`

TypeScript

waitForNodeGone(condition: (node: AndroidNode) => boolean, durationMs?: number, intervalMs?: number): Promise<boolean>

Waits for a node matching the condition to disappear from screen. Polls the screen at regular intervals until the node is gone or timeout is reached.

Parameters

Name	Type	Description
`condition`	`(node: AndroidNode) => boolean`	Function that identifies the node to wait for disappearance
`durationMs?`	`number`	Maximum time to wait in milliseconds(default: `30000`)
`intervalMs?`	`number`	Polling interval in milliseconds(default: `500`)

Returns

booleantrue if the node disappeared, false if timeout was reached

Examples

Wait for loading spinner to disappear

TypeScript

const spinnerGone = await agent.utils.waitForNodeGone(
  node => node.className?.includes("ProgressBar"),
  20000 // 20 second timeout
);

if (spinnerGone) {
  console.log("Loading complete");
} else {
  console.log("Loading took too long");
}

Wait for dialog to close

TypeScript

// Click dismiss and wait for dialog to close
screen.findTextOne("Dismiss")?.click();

const dialogClosed = await agent.utils.waitForNodeGone(
  node => node.text === "Are you sure?",
  5000
);