ArgusJS API Reference

Announcements
1

ArgusJS Full API Reference

This topic is the public API reference for ArgusJS scripts.

ArgusJS Studio is optional. You can write scripts in VS Code, Notepad++, Android editors, or any other IDE. Studio helps with autocomplete, validation, protection, and deployment, but the runtime APIs below are available to scripts running in ArgusJS App.

Summary

ArgusJS APIs are exposed as global JavaScript functions and runtime objects.

API family Main requirement
Clicks, gestures, navigation, accessibility nodes Accessibility service
Screen capture, image search, OCR, color, PixelSet, PixelDNA, ML Kit Screen capture permission
IME-only typing APIs Argus Keyboard enabled and active
Files and persistence Selected ArgusJS project
HTTP, downloads, network time, email Network/email settings

Common object types

Most APIs return one of these runtime objects.

type Nullable<T> = T | null;
type HexColor = string;
type Direction = "up" | "down" | "left" | "right" | string;

interface Location {
  x: number;
  y: number;
  setLocation(x: number, y: number): Location;
  offset(dx: number, dy: number): Location;
  above(pixels: number): Location;
  below(pixels: number): Location;
  left(pixels: number): Location;
  right(pixels: number): Location;
  typeOf(): "Location";
}

interface Region {
  x: number;
  y: number;
  w: number;
  h: number;
  getRight(): number;
  getBottom(): number;
  isValid(): boolean;
  isEmpty(): boolean;
  getTopLeft(): Location;
  getTopRight(): Location;
  getBottomLeft(): Location;
  getBottomRight(): Location;
  getCenter(): Location;
  getTarget(): Location;
  offset(dx: number, dy: number): Region;
  above(pixels: number): Region;
  below(pixels: number): Region;
  left(pixels: number): Region;
  right(pixels: number): Region;
  click(): boolean;
  longClick(durationMillis?: number): boolean;
  dragDrop(target: ClickTarget): boolean;
  swipe(direction: Direction, durationMillis?: number): boolean;
  save(filename: string): boolean;
  saveColor(filename: string): boolean;
  highlight(...args: any[]): HighlightHandle | null;
  highlightOff(): void;
  find(pattern: Pattern): Match | null;
  findAll(pattern: Pattern): Match[];
  exists(pattern: Pattern): Match | null;
  waitFor(target: string | Pattern, seconds?: number): Match | null;
  waitVanish(target: string | Pattern, seconds?: number): boolean;
  waitAny(targets: Array<string | Pattern>, seconds?: number): Match | null;
  findText(text: string, caseSensitive?: boolean): TextMatch | null;
  findAllText(text: string, caseSensitive?: boolean): TextMatch[];
  waitText(text: string, seconds?: number, caseSensitive?: boolean): TextMatch | null;
  getWords(): TextMatch[];
  findColor(hexColor: HexColor, tolerance?: number): Location | null;
  findAllColor(hexColor: HexColor, tolerance?: number): Location[];
  contains(location: Location): boolean;
  findPixelSet(pixelSet: PixelSet | string, similarity?: number): Match | null;
  findAllPixelSet(pixelSet: PixelSet | string, similarity?: number): Match[];
  findPixelDNA(dna: PixelDNAInput): Region | null;
  findAllPixelDNA(dna: PixelDNAInput): Region[];
  typeOf(): "Region";
}

interface Screen {
  isRecycled(): boolean;
  isValid(): boolean;
  recycle(): void;
}

interface ScreenLeashedRegion extends Region {
  typeOf(): "ScreenLeashedRegion";
}

interface Match extends Region {
  score: number;
  typeOf(): "Match";
}

interface TextMatch extends Region {
  text: string;
  getText(): string;
  typeOf(): "TextMatch";
}

interface Pattern {
  fileName: string;
  similarity: number;
  useGrayscale: boolean;
  maskColor: string | null;
  similar(sim: number): Pattern;
  targetOffset(dx: number, dy: number): Pattern;
  getTargetOffset(): Location;
  color(): Pattern;
  grayscale(): Pattern;
  mask(hexColor?: HexColor): Pattern;
  inScreen(screen: Screen): Pattern;
  typeOf(): "Pattern";
}

Core and reports

Use these APIs for timing, script exit, logs, toast messages, success/cancel messages, and report output.

sleep(milliseconds: number): void;
scriptExit(message?: string): never;
scriptExit(isError: boolean): never;
setSuccessMessage(message: string): void;
setCancelMessage(message: string): void;
log(message: any): void;
toast(message: string): void;
toastLong(message: string, long?: boolean): void;
typeOf(obj: any): string;
safeValueToString(value: any, maxDepth?: number, maxItems?: number, maxString?: number): string;
setReferenceResolution(width: number, height: number): void;
getLastMatch(): Match | null;

reportStep(message: string, details?: any): string;
reportInfo(message: string, details?: any): string;
reportError(message: string, details?: any): string;
clearReport(): boolean;
getReport(): string;
saveReport(filePath?: string): boolean;
notifyProgress(title: string, message?: string, progress?: number, max?: number, ongoing?: boolean): boolean;
clearNotification(): boolean;

Geometry and screen objects

Use these APIs to create points and regions and to read screen size.

createLocation(x: number, y: number): Location;
createRegion(x: number, y: number, w: number, h: number): Region;
getScreenWidth(): number;
getScreenHeight(): number;
getStatusBarHeight(): number;
getAppUsableScreenSize(): Region | null;

Screen capture and cache

Screen capture is required for image matching, OCR, colors, PixelSet, PixelDNA, barcode scanning, labels, and object detection.

captureScreen(): Screen | null;
cacheScreen(): boolean;
refreshScreenCache(): boolean;
clearScreenCache(): boolean;
hasScreenCache(): boolean;
getScreenCacheAge(): number;
onScreen(screen: Screen): ScreenLeashedRegion | null;
withCapturedScreen(callback: (screen: Screen) => any): any;
withScreenCache<T = any>(callback: () => T, options?: ScreenCacheOptions): T;

interface ScreenCacheOptions {
  refresh?: boolean;
  clearAfter?: boolean;
  maxAgeMs?: number;
}

Example:

withCapturedScreen(function (screen) {
  var region = onScreen(screen);
  log(region ? "Screen ready" : "Screen failed");
});

Image and pattern search

Use these APIs to find image assets on the screen. Image files should be inside the selected project.

createPattern(fileName: string): Pattern;
find(pattern: Pattern): Match | null;
findIn(region: Region, pattern: Pattern): Match | null;
findAll(pattern: Pattern): Match[];
findAllIn(region: Region, pattern: Pattern): Match[];
exists(target: string | Pattern, seconds?: number): Match | null;
waitFor(target: string | Pattern, seconds?: number): Match | null;
waitFor(target: string | Pattern, region: Region, seconds?: number): Match | null;
waitVanish(target: string | Pattern, seconds?: number): boolean;
waitVanish(target: string | Pattern, region: Region, seconds?: number): boolean;
waitAny(targets: Array<string | Pattern>, seconds?: number): Match | null;
waitAny(targets: Array<string | Pattern>, region: Region, seconds?: number): Match | null;
waitClick(pattern: string | Pattern, seconds?: number): Match | null;
existsClick(pattern: string | Pattern, seconds?: number): Match | null;
findAsync(pattern: Pattern): AsyncResult<Match | null>;
waitAsync(patternOrString: string | Pattern, seconds?: number): AsyncResult<Match | null> | null;
waitVanishAsync(patternOrString: string | Pattern, seconds?: number): AsyncResult<boolean> | null;

Example:

var button = createPattern("start_button.png").similar(0.85);
var match = waitFor(button, 5);

if (match) {
  click(match);
}

OCR and text

Use OCR APIs to read visible text from the screen or a region.

readText(): string;
readText(region: Region): string;
readText(screenLeashedRegion: ScreenLeashedRegion): string;
readTextAsync(region: Region | ScreenLeashedRegion): AsyncResult<string>;

getWords(): TextMatch[];
getWordsIn(region: Region): TextMatch[];
getWordsIn(region: Region, screen: Screen): TextMatch[];

findText(text: string, caseSensitive?: boolean): TextMatch | null;
findTextIn(region: Region, text: string, caseSensitive?: boolean): TextMatch | null;
findTextIn(region: Region, text: string, screen: Screen): TextMatch | null;
findTextIn(region: Region, text: string, screen: Screen, caseSensitive: boolean): TextMatch | null;

findAllText(text: string, caseSensitive?: boolean): TextMatch[];
findAllTextIn(region: Region, text: string, caseSensitive?: boolean): TextMatch[];
findAllTextIn(region: Region, text: string, screen: Screen): TextMatch[];
findAllTextIn(region: Region, text: string, screen: Screen, caseSensitive: boolean): TextMatch[];

waitText(text: string, seconds?: number, caseSensitive?: boolean): TextMatch | null;
waitTextIn(region: Region, text: string, seconds?: number, caseSensitive?: boolean): TextMatch | null;
waitAnyText(texts: string[], seconds?: number, caseSensitive?: boolean): WaitAnyTextResult | null;
waitAnyTextIn(region: Region, texts: string[], seconds?: number, caseSensitive?: boolean): WaitAnyTextResult | null;
existsText(text: string, seconds?: number, caseSensitive?: boolean): TextMatch | null;
existsTextIn(region: Region, text: string, seconds?: number, caseSensitive?: boolean): TextMatch | null;
waitVanishText(text: string, seconds?: number, caseSensitive?: boolean): boolean;
waitVanishTextIn(region: Region, text: string, seconds?: number, caseSensitive?: boolean): boolean;

waitTextAsync(text: string, seconds?: number, caseSensitive?: boolean): AsyncResult<TextMatch | null>;
waitTextInAsync(region: Region, text: string, seconds?: number, caseSensitive?: boolean): AsyncResult<TextMatch | null>;
waitVanishTextAsync(text: string, seconds?: number, caseSensitive?: boolean): AsyncResult<boolean>;
waitVanishTextInAsync(region: Region, text: string, seconds?: number, caseSensitive?: boolean): AsyncResult<boolean>;

text(): TextQuery<TextMatch>;
text(pattern: string): TextQuery<TextMatch>;

Example:

var continueText = waitText("Continue", 5);

if (continueText) {
  click(continueText);
}

Text query builder

interface TextQuery<TResult = TextMatch> {
  exact(): TextQuery<TResult>;
  contains(): TextQuery<TResult>;
  regex(): TextQuery<TResult>;
  startsWith(): TextQuery<TResult>;
  endsWith(): TextQuery<TResult>;
  caseSensitive(): TextQuery<TResult>;
  caseInsensitive(): TextQuery<TResult>;
  in(region: Region): TextQuery<TResult>;
  region(region: Region): TextQuery<TResult>;
  fullScreen(): TextQuery<TResult>;
  on(screen: Screen): TextQuery<TResult>;
  any(patterns: string[]): TextQuery<AnyTextResult>;
  find(): TResult | null;
  findAll(): TResult[];
  all(): TResult[];
  first(): TResult | null;
  wait(seconds?: number): TResult | null;
  exists(seconds?: number): TResult | null;
  waitVanish(seconds?: number): boolean;
  nth(index: number): TResult | null;
  click(): TResult | null;
  waitClick(seconds?: number): TResult | null;
  findAsync(): AsyncResult<TResult>;
  findAllAsync(): AsyncResult<TResult[]>;
  waitAsync(seconds?: number): AsyncResult<TResult>;
  existsAsync(seconds?: number): AsyncResult<TResult>;
  waitVanishAsync(seconds?: number): AsyncResult<boolean>;
  timeout(seconds: number): TextQuery<TResult>;
  pollInterval(milliseconds: number): TextQuery<TResult>;
  trim(): TextQuery<TResult>;
  normalizeSpaces(): TextQuery<TResult>;
  minLength(length: number): TextQuery<TResult>;
  maxLength(length: number): TextQuery<TResult>;
  debug(enabled?: boolean): TextQuery<TResult>;
  closestTo(target: TextQueryTarget): TextQuery<TResult>;
  above(target: TextQueryTarget): TextQuery<TResult>;
  below(target: TextQueryTarget): TextQuery<TResult>;
  leftOf(target: TextQueryTarget): TextQuery<TResult>;
  rightOf(target: TextQueryTarget): TextQuery<TResult>;
  sortByTop(): TextQuery<TResult>;
  sortByBottom(): TextQuery<TResult>;
  sortByLeft(): TextQuery<TResult>;
  sortByRight(): TextQuery<TResult>;
  sortByDistanceTo(target: TextQueryTarget): TextQuery<TResult>;
  limit(count: number): TextQuery<TResult>;
  words(): TextQuery<TResult>;
  lines(): TextQuery<TResult>;
  blocks(): TextQuery<TResult>;
  fullText(): TextQuery<TResult>;
}

Color

Use color APIs to read pixels, compare colors, and search for colors.

getColor(target: ColorTarget): ColorValue | null;
compareColor(x: number, y: number, hexColor: HexColor, tolerance?: number): boolean;
compareColor(target: ColorTarget, hexColor: HexColor, tolerance?: number): boolean;
getColorCount(region: Region, hexColor: HexColor, tolerance?: number): number;
waitColor(target: ColorTarget, hexColor: HexColor, seconds?: number, tolerance?: number): ColorValue | null;
waitCompareColor(target: ColorTarget, hexColor: HexColor, seconds?: number, tolerance?: number): boolean;
waitVanishColor(target: ColorTarget, hexColor: HexColor, seconds?: number, tolerance?: number): boolean;
waitColorAsync(target: ColorTarget, hexColor: HexColor, seconds?: number, tolerance?: number): AsyncResult;

findColor(hexColor: HexColor, tolerance?: number, screen?: Screen): Location | null;
findColorIn(hexColor: HexColor, region: Region, tolerance?: number, screen?: Screen): Location | null;
findAllColor(hexColor: HexColor, tolerance?: number, screen?: Screen): Location[];
findAllColorIn(hexColor: HexColor, region: Region, tolerance?: number, screen?: Screen): Location[];

findMultiColor(primaryColors: string | string[], secondaryColors?: string | string[], tolerance?: number, screen?: Screen): Location | null;
findMultiColorIn(primaryColors: string | string[], secondaryColors: string | string[], region: Region, tolerance?: number, screen?: Screen): Location | null;
findMultiColorIn(primaryColors: string | string[], region: Region, tolerance?: number, screen?: Screen): Location | null;
findAllMultiColor(primaryColors: string | string[], secondaryColors?: string | string[], tolerance?: number, screen?: Screen): Location[];
findAllMultiColorIn(primaryColors: string | string[], secondaryColors: string | string[], region: Region, tolerance?: number, screen?: Screen): Location[];
findAllMultiColorIn(primaryColors: string | string[], region: Region, tolerance?: number, screen?: Screen): Location[];

colorToHexString(color: ColorValue): string;
debugCompareInMemory(...args: any[]): void;

Async color search:

findColorAsync(hexColor: HexColor, tolerance?: number): AsyncResult | null;
findAllColorAsync(hexColor: HexColor, tolerance?: number): AsyncResult | null;
findMultiColorAsync(primaryColors: string | string[], secondaryColors?: string | string[], tolerance?: number): AsyncResult | null;
findAllMultiColorAsync(primaryColors: string | string[], secondaryColors?: string | string[], tolerance?: number): AsyncResult | null;
findColorInAsync(hexColor: HexColor, region: Region, tolerance?: number): AsyncResult;
findAllColorInAsync(hexColor: HexColor, region: Region, tolerance?: number): AsyncResult;
findMultiColorInAsync(primaryColors: string | string[], secondaryColors: string | string[], region: Region, tolerance?: number): AsyncResult;
findMultiColorInAsync(primaryColors: string | string[], region: Region, tolerance?: number): AsyncResult;
findAllMultiColorInAsync(primaryColors: string | string[], secondaryColors: string | string[], region: Region, tolerance?: number): AsyncResult;
findAllMultiColorInAsync(primaryColors: string | string[], region: Region, tolerance?: number): AsyncResult;

PixelSet and PixelDNA

Use PixelSet and PixelDNA for compact screen-pattern matching.

getPixelSet(target: ClickTarget, size?: number, useColor?: boolean): PixelSet | null;
findPixelSet(pixelSet: PixelSet | string, similarity?: number): Match | null;
findPixelSetIn(region: Region, pixelSet: PixelSet | string, similarity?: number): Match | null;
findAllPixelSet(pixelSet: PixelSet | string, similarity?: number): Match[];
findAllPixelSetIn(region: Region, pixelSet: PixelSet | string, similarity?: number): Match[];

findPixelSetAsync(pixelSet: PixelSet | string, similarity?: number): AsyncResult;
findPixelSetInAsync(region: Region, pixelSet: PixelSet | string, similarity?: number): AsyncResult;
findAllPixelSetAsync(pixelSet: PixelSet | string, similarity?: number): AsyncResult;
findAllPixelSetInAsync(region: Region, pixelSet: PixelSet | string, similarity?: number): AsyncResult;

getPixelDNA(target: ClickTarget, totalTarget?: number, size?: number, tolerance?: number, maxAttempts?: number): PixelDNA | null;
findPixelDNA(dna: PixelDNAInput): Region | null;
findPixelDNAIn(region: Region, dna: PixelDNAInput): Region | null;
findAllPixelDNA(dna: PixelDNAInput): Region[];
findAllPixelDNAIn(region: Region, dna: PixelDNAInput): Region[];
existsPixelDNA(dna: PixelDNAInput): Region | null;
existsPixelDNAIn(region: Region, dna: PixelDNAInput): Region | null;
waitPixelDNA(dna: PixelDNAInput, seconds?: number): Region | null;
waitPixelDNAIn(region: Region, dna: PixelDNAInput, seconds?: number): Region | null;
waitVanishPixelDNA(dna: PixelDNAInput, seconds?: number): boolean;
waitVanishPixelDNAIn(region: Region, dna: PixelDNAInput, seconds?: number): boolean;

findPixelDNAAsync(dna: PixelDNAInput): AsyncResult;
findPixelDNAInAsync(region: Region, dna: PixelDNAInput): AsyncResult;
findAllPixelDNAAsync(dna: PixelDNAInput): AsyncResult;
findAllPixelDNAInAsync(region: Region, dna: PixelDNAInput): AsyncResult;
waitPixelDNAAsync(dna: PixelDNAInput, seconds?: number): AsyncResult;
waitPixelDNAInAsync(region: Region, dna: PixelDNAInput, seconds?: number): AsyncResult;
waitVanishPixelDNAAsync(dna: PixelDNAInput, seconds?: number): AsyncResult;
waitVanishPixelDNAInAsync(region: Region, dna: PixelDNAInput, seconds?: number): AsyncResult;

ML Kit

Use these APIs for barcode scanning, image labels, and object detection.

findBarcode(options?: BarcodeOptions): BarcodeResult | null;
findBarcodes(options?: BarcodeOptions): BarcodeResult[];
waitBarcode(options?: BarcodeOptions, seconds?: number): BarcodeResult | null;

labelScreen(options?: LabelOptions): LabelResult[];
labelRegion(region: Region, options?: LabelOptions): LabelResult[];
hasLabel(label: string, minConfidence?: number): boolean;

detectObjects(options?: ObjectDetectionOptions): ObjectResult[];
detectObjectsIn(region: Region, options?: ObjectDetectionOptions): ObjectResult[];
waitObject(options?: ObjectDetectionOptions, seconds?: number): ObjectResult | null;
trackObjects(options?: ObjectDetectionOptions): ObjectResult[];
startObjectTracking(options?: ObjectDetectionOptions): number;
stopObjectTracking(id: number): boolean;

interface BarcodeOptions {
  formats?: string | string[];
  region?: Region;
  rawValueContains?: string;
  valueType?: string;
}

interface LabelOptions {
  minConfidence?: number;
  maxResults?: number;
}

interface ObjectDetectionOptions {
  classify?: boolean;
  multipleObjects?: boolean;
  minConfidence?: number;
  label?: string;
  region?: Region;
  intervalMs?: number;
}

Touch, gestures, and navigation

Use these APIs for clicks, long clicks, swipes, drag/drop, gestures, Android global actions, wake, lock, and keyboard hiding.

click(x: number, y: number): boolean;
click(location: Location): boolean;
click(region: Region): boolean;
click(match: Match | TextMatch): boolean;
click(pattern: Pattern): boolean;
click(target: ClickTarget): boolean;
click(target: ClickTarget, randomPixels: number): boolean;

doubleClick(target: ClickTarget, intervalMs?: number): boolean;
longClick(target: ClickTarget, durationMillis?: number): boolean;
longPress(target: ClickTarget): boolean;
stopLongPress(): boolean;

gesture(points: GesturePoint[], durationMillis?: number, startDelayMillis?: number): boolean;
humanSwipe(from: ClickTarget, to: ClickTarget, durationMillis?: number, steps?: number): boolean;
continueClick(target: ClickTarget, options: ContinueClickOptions): boolean;

swipe(x1: number, y1: number, x2: number, y2: number, durationMillis?: number): boolean;
swipe(from: Location, to: Location, durationMillis?: number): boolean;
swipe(from: Region, to: Region, durationMillis?: number): boolean;

scroll(x: number, y: number, direction: Direction, distance?: number, durationMillis?: number): boolean;
scroll(region: Region, direction: Direction, distance?: number, durationMillis?: number): boolean;
scroll(location: Location, direction: Direction, distance?: number, durationMillis?: number): boolean;

dragDrop(from: ClickTarget, to: ClickTarget): boolean;
setDragTiming(pressMs: number, moveMs: number, releaseMs: number): any;
setDragStepCount(steps: number): any;

globalAction(actionCode: number): boolean;
pressHome(): boolean;
pressBack(): boolean;
pressRecents(): boolean;
openNotifications(): boolean;
wakeup(): boolean;
lockScreen(): boolean;
hideKeyboard(): boolean;

interface ContinueClickOptions {
  times?: number;
  duration?: number;
  interval?: number;
  randomize?: number;
  forever?: boolean;
}

Keyboard and text input

Use these APIs for general text input, clipboard-based input, keyboard actions, and IME-specific input.

type(text: string): boolean;
type(target: ClickTarget, text: string): boolean;
typeOnFocus(text: string): boolean;
typeOnFocus(target: ClickTarget, text: string): boolean;

setText(text: string): boolean;
clearText(): boolean;
selectAll(): boolean;
copy(): boolean;
cut(): boolean;
paste(): boolean;
paste(text: string): boolean;

pressEnter(): boolean;
pressBackspace(count?: number): boolean;
pressDelete(count?: number): boolean;
pressLeft(count?: number): boolean;
pressRight(count?: number): boolean;

backspace(count?: number): boolean;
deleteForward(count?: number): boolean;
enter(): boolean;
done(): boolean;
search(): boolean;
send(): boolean;
next(): boolean;
cursorLeft(count?: number): boolean;
cursorRight(count?: number): boolean;
pressKey(key: string): boolean;

pressEnterOnFocus(): boolean;
pressBackspaceOnFocus(count?: number): boolean;
cursorLeftOnFocus(count?: number): boolean;
cursorRightOnFocus(count?: number): boolean;
pasteOnFocus(): boolean;

Argus Keyboard / IME

argusKeyboardShow(): boolean;
argusKeyboardStealth(): boolean;
argusKeyboardHide(): boolean;
argusKeyboardToggle(): boolean;
argusKeyboardReset(): boolean;
argusKeyboardMode(): "full" | "stealth" | "hidden";
setArgusKeyboardMode(mode: string): boolean;
isArgusKeyboardActive(): boolean;
isArgusKeyboardVisible(): boolean;

imeType(text: string): boolean;
imeBackspace(count?: number): boolean;
imeDeleteForward(count?: number): boolean;
imeEnter(): boolean;
imePressKey(key: string): boolean;
imeCursorLeft(count?: number): boolean;
imeCursorRight(count?: number): boolean;
imeDone(): boolean;
imeSearch(): boolean;
imeSend(): boolean;
imeNext(): boolean;
imePaste(): boolean;
imePaste(text: string): boolean;
imeSelectAll(): boolean;
imeClearText(): boolean;
imeKeyEvent(keyCode: number): boolean;

Accessibility nodes

Accessibility nodes are useful for normal Android UI controls. Some games and custom-rendered views may not expose useful nodes.

dumpLayout(): string;
dumpLayout(options?: DumpLayoutOptions): string;

findNode(byText?: string, byContentDescription?: string, byViewId?: string, byClassName?: string): UINode | null;
findNode(options: NodeSearchOptions): UINode | null;

findAllNodes(byText?: string, byContentDescription?: string, byViewId?: string, byClassName?: string): UINode[];
findAllNodes(options: NodeSearchOptions): UINode[];

waitNode(options: NodeSearchOptions, seconds?: number): UINode | null;
waitStableNode(options: NodeSearchOptions, seconds?: number): UINode | null;
waitVanishNode(options: NodeSearchOptions, seconds?: number): boolean;
waitNodeAsync(options: NodeSearchOptions, seconds?: number): AsyncResult;
waitVanishNodeAsync(options: NodeSearchOptions, seconds?: number): AsyncResult;

clickNode(options: NodeClickOptions): NodeClickResult;
node(options?: NodeSearchOptions): NodeQuery;
getNodeAt(location: Location): UINode | null;

Example:

var ok = node().text("OK").target("smart").waitClick(5);

if (!ok.clicked) {
  log("OK button was not clicked: " + ok.error);
}

UINode

interface UINode {
  text: string | null;
  contentDescription: string | null;
  viewIdResourceName: string | null;
  widgetClassName: string | null;
  packageName: string | null;
  x: number;
  y: number;
  w: number;
  h: number;
  childCountValue: number;

  getText(): string | null;
  getDesc(): string | null;
  getId(): string | null;
  getClassName(): string | null;
  getPackageName(): string | null;
  getBounds(): Region | null;
  getCenter(): Location | null;
  getTarget(): Location | null;

  click(): boolean;
  longClick(): boolean;
  clickRegion(): boolean;
  clickSmart(): boolean;
  clickSmart(target: NodeClickSmartTarget): boolean;
  isChecked(): boolean;
  isEnabled(): boolean;
  isFocused(): boolean;
  isCheckable(): boolean;
  isScrollable(): boolean;
  isClickable(): boolean;
  isLongClickable(): boolean;
  isVisibleToUser(): boolean;
  isSelected(): boolean;
  isEditable(): boolean;
  isPassword(): boolean;
  isFocusable(): boolean;
  isAccessibilityFocused(): boolean;

  hasAction(actionName: string): boolean;
  getActionNames(): string[];
  scrollForward(): boolean;
  scrollBackward(): boolean;
  clearText(): boolean;
  setText(text: string): boolean;
  type(text: string): boolean;
  paste(): boolean;
  paste(text: string): boolean;
  setSelection(start: number, end: number): boolean;
  performAction(actionName: string): boolean;
  performAction(actionId: number): boolean;

  refresh(): boolean;
  isValid(): boolean;
  getParent(): UINode | null;
  getClickableParent(maxDepth?: number): UINode | null;
  getChild(index: number): UINode | null;
  getChildCount(): number;
  toRegion(): Region;
  toJSON(key?: string): string;
}

NodeSearchOptions

interface NodeSearchOptions {
  text?: string;
  textContains?: string;
  textStartsWith?: string;
  textEndsWith?: string;
  textRegex?: string;
  desc?: string;
  descContains?: string;
  descStartsWith?: string;
  descEndsWith?: string;
  descRegex?: string;
  viewId?: string;
  id?: string;
  viewIdContains?: string;
  idContains?: string;
  viewIdRegex?: string;
  idRegex?: string;
  className?: string;
  classNameContains?: string;
  classNameRegex?: string;
  packageName?: string;
  packageNameContains?: string;
  packageNameRegex?: string;

  enabled?: boolean;
  visible?: boolean;
  clickable?: boolean;
  longClickable?: boolean;
  focusable?: boolean;
  focused?: boolean;
  selected?: boolean;
  checked?: boolean;
  scrollable?: boolean;
  editable?: boolean;

  inRegion?: Region;
  sortBy?: string;
  index?: number;
  caseSensitive?: boolean;
  timeout?: number;
  pollMs?: number;
  stableMs?: number;
  target?: string;
  windowScope?: "active" | "all" | "nonArgus" | string;
  debug?: boolean;
}

NodeQuery

interface NodeQuery {
  text(value: string): NodeQuery;
  textContains(value: string): NodeQuery;
  textStartsWith(value: string): NodeQuery;
  textEndsWith(value: string): NodeQuery;
  textRegex(value: string): NodeQuery;
  desc(value: string): NodeQuery;
  descContains(value: string): NodeQuery;
  viewId(value: string): NodeQuery;
  id(value: string): NodeQuery;
  className(value: string): NodeQuery;
  packageName(value: string): NodeQuery;

  exact(enabled?: boolean): NodeQuery;
  contains(enabled?: boolean): NodeQuery;
  regex(enabled?: boolean): NodeQuery;
  caseSensitive(enabled?: boolean): NodeQuery;
  caseInsensitive(enabled?: boolean): NodeQuery;

  enabled(value?: boolean): NodeQuery;
  visible(value?: boolean): NodeQuery;
  clickable(value?: boolean): NodeQuery;
  scrollable(value?: boolean): NodeQuery;
  editable(value?: boolean): NodeQuery;
  in(region: Region): NodeQuery;
  sortBy(value: string): NodeQuery;
  index(value: number): NodeQuery;
  timeout(seconds: number): NodeQuery;
  pollMs(ms: number): NodeQuery;
  stable(ms: number): NodeQuery;
  target(value: string): NodeQuery;
  retries(value: number): NodeQuery;
  debug(value?: boolean): NodeQuery;

  find(): UINode | null;
  first(): UINode | null;
  findAll(): UINode[];
  all(): UINode[];
  nth(index: number): UINode | null;
  exists(seconds?: number): UINode | null;
  wait(seconds?: number): UINode | null;
  waitStable(seconds?: number): UINode | null;
  waitVanish(seconds?: number): boolean;
  waitAsync(seconds?: number): AsyncResult;
  waitVanishAsync(seconds?: number): AsyncResult;
  click(): NodeClickResult;
  click(target: string): NodeClickResult;
  waitClick(seconds?: number): NodeClickResult;
  clickRegion(): boolean;
  clickSmart(): NodeClickResult;
  options(): NodeSearchOptions;
  toString(): string;
}

Continued in Post 2 → App and device, Files, Persistence, Clipboard/Audio/Overlays, Network, Timers, Dialogs, and Notes

5

ArgusJS Full API Reference — Part 2

Continued from Post 1 → Summary, Common types, Core, Geometry, Screen capture, Image search, OCR, Color, PixelSet/PixelDNA, ML Kit, Touch/Gestures, Keyboard, Accessibility nodes

App and device

Use these APIs to launch apps, check foreground state, close apps, read device info, and control some device features.

startApp(packageName: string): void;
runApp(packageName: string): void;
launchApp(packageName: string, options?: AppLaunchOptions): AppLaunchResult;
ensureApp(packageName: string, options?: EnsureAppOptions): AppLaunchResult;
app(packageName: string): AppQuery;

closeApp(packageName?: string): boolean;
closeAppByKillingProcess(): boolean;
closeAppEx(options?: AppCloseOptions): AppCloseResult;
killApp(packageName: string): boolean;
killAppEx(packageName: string): AppCloseResult;

getForegroundApp(): string | null;
getForegroundState(packageName?: string): AppStateResult;
isAppForeground(packageName: string): boolean;
isAppInstalled(packageName: string): boolean;
isAppLaunchable(packageName: string): boolean;
getAppState(packageName: string): AppStateResult;
waitApp(packageName: string, seconds?: number): boolean;
waitApp(packageName: string, options: AppWaitOptions): AppWaitResult;
waitForeground(options: AppForegroundWaitOptions): AppWaitResult;
waitAppVanish(packageName: string, seconds?: number): boolean;
waitAppVanishEx(packageName: string, options?: AppVanishOptions): AppWaitResult;

getOrientation(): string | null;
getLanguage(): string;
getCountry(): string;
getVersion(): string | null;
getAndroidVersion(): number;
getDeviceID(): string;
getIMEI(): string;
getSIMSerial(): string;
getIMSI(): string;
getWiFiMAC(): string;
getMacAddr(): string;
getBatteryLevel(): number;
isCharging(): boolean;
getNetworkType(): string;
isWifiConnected(): boolean;
getVolume(): number;
getMaxVolume(): number;
setVolume(level: number): boolean;
isScreenOn(): boolean;
vibrate(arg?: number | number[]): void;
alert(duration?: number): void;

AppQuery

interface AppQuery {
  timeout(seconds: number): AppQuery;
  pollMs(ms: number): AppQuery;
  stable(ms: number): AppQuery;
  retries(count: number): AppQuery;
  retryDelayMs(ms: number): AppQuery;
  debug(value?: boolean): AppQuery;
  wait(value?: boolean): AppQuery;
  allowSystemDialogs(value?: boolean): AppQuery;
  pressHome(value?: boolean): AppQuery;
  killBackground(value?: boolean): AppQuery;
  verifyVanish(value?: boolean): AppQuery;
  launch(): AppLaunchResult;
  launchAndWait(): AppLaunchResult;
  ensure(): AppLaunchResult;
  waitForeground(): AppWaitResult;
  waitVanish(): AppWaitResult;
  close(): AppCloseResult;
  kill(): AppCloseResult;
  state(): AppStateResult;
  foregroundState(): AppStateResult;
  isInstalled(): boolean;
  isLaunchable(): boolean;
  isForeground(): boolean;
}

Files and project

File paths are project-relative. Absolute paths and path traversal outside the selected project are rejected.

scriptPath(): string;
scanDir(subfolder: string): string[];
createDir(path: string): boolean;
readFile(filePath: string): string | null;
writeFile(filePath: string, content: string): boolean;
appendFile(filePath: string, content: string): boolean;
deleteFile(filePath: string): boolean;
deleteDirectory(path: string): boolean;
unzip(zipFileName: string, destFolder: string): boolean;
save(region: Region, filename: string): boolean;
saveColor(region: Region, filename: string): boolean;

Persistence

Persistence is project-scoped and stores JSON-like values.

saveVar(key: string, value: SaveVarValue): boolean;
loadVar<T extends JsonLike>(key: string, defaultValue: T): T | null;
loadVar(key: string, defaultValue?: JsonLike): JsonLike | null;
listVars(): string[];
removeVar(key: string): boolean;
clearVars(): boolean;

Example:

saveVar("runCount", 1);
var count = loadVar("runCount", 0);

Clipboard, audio, brightness, overlays, and highlights

getClipboardText(): string;
setClipboardText(text: string): boolean;

playMusic(filePath: string, options?: MusicOptions): boolean;
stopMusic(): void;
isMusicPlaying(): boolean;

setBrightness(level: number): void;
getBrightness(): number;
hideAllOverlays(): void;
showAllOverlays(): void;

highlight(target: HighlightTarget): HighlightHandle | null;
highlight(target: HighlightTarget, secondsOrMillis: number): HighlightHandle | null;
highlight(target: HighlightTarget, text: string): HighlightHandle | null;
highlight(target: HighlightTarget, text: string, secondsOrMillis: number): HighlightHandle | null;
highlight(target: HighlightTarget, options: HighlightOptions): HighlightHandle | null;
highlightOff(region: Region): void;
highlightOff(handle: HighlightHandle): void;
highlightOff(idOrKey: string): void;
highlightAllOff(): void;
highlightUpdate(region: Region, newText: string): void;
highlightUpdate(handle: HighlightHandle, newText: string): void;
highlightUpdate(idOrKey: string, newText: string): void;

setTouchEventStyle(argbColor: string): void;
setTouchEventStyle(color: string, alpha: number): void;
getTouchEvent(): ArgusTouchEvent | null;
recordTouchEvent(): ArgusTouchEvent | null;
recordAndReplayEvent(): ArgusTouchEvent | null;
replayTouchEvent(event: ArgusTouchEvent | Record<string, any>): boolean;
replayTouchEvents(events: Array<ArgusTouchEvent | Record<string, any>>): boolean;
recordEvent(): ArgusTouchEvent | null;

Network and email

httpGet(url: string, options?: { headers?: HttpHeaders } | null): HTTPResponse | null;
httpPost(url: string, data?: string | object | null, options?: HttpOptions | null): HTTPResponse | null;
httpPut(url: string, data?: string | object | null, options?: HttpOptions | null): HTTPResponse | null;
httpDelete(url: string, data?: string | object | null, options?: HttpOptions | null): HTTPResponse | null;
httpRequest(options: HttpRequestOptions | null): HTTPResponse | null;
httpDownload(url: string, fileName: string): boolean;
openUrl(url: string): void;
sendEmail(options: SendEmailOptions): boolean;
sendTestEmail(): boolean;
getNetworkTime(ntpServer?: string): number;

interface HTTPResponse {
  status: number;
  body: string | null;
  headers: { [name: string]: string };
  error: string | null;
}

interface HttpRequestOptions {
  url: string;
  method: string;
  data?: string | object | null;
  headers?: { [headerName: string]: string };
  contentType?: string;
}

interface SendEmailOptions {
  to?: string;
  subject?: string;
  body?: string;
  attachReport?: boolean;
  attachScreenshot?: boolean;
}

Timers, watchers, and async

setInterval(callback: () => any, intervalMs: number): number;
setTimeout(callback: () => any, delayMs: number): number;
runAsync(callback: () => any): number;
clearInterval(id: number): void;
getInterval(id: number): TimerInfo | null;
getIntervals(): TimerInfo[];
clearAllIntervals(): void;

watch(name: string, callback: () => any, intervalMs?: number): number;
getWatcher(name: string): TimerInfo | null;
stopWatcher(name: string): boolean;
clearWatchers(): void;
getWatchers(): TimerInfo[];

race(jobs: AsyncResult[]): RaceResult | null;
awaitAll(jobs: AsyncResult[]): any[];
clearAllAsyncJobs(): void;
waitUntil(callback: () => any, seconds?: number, intervalMs?: number): any;
retry(times: number, callback: () => any, delayMs?: number): any;
repeatUntil(action: () => any, condition: () => any, maxRuns?: number, delayMs?: number): any;

interface AsyncResult<TResult = any> {
  type(): string;
  isStarted(): boolean;
  isCompleted(): boolean;
  isCancelled(): boolean;
  getResult(): TResult | null;
  getError(): string | null;
  cancel(): boolean;
}

interface TimerInfo {
  id: number;
  type: string;
  intervalMs: number;
  runningForMs: number;
  runCount: number;
  lastRunTime: number;
  lastResult: any;
  lastError: string | null;
  completed: boolean;
  name?: string;
}

Dialogs

ArgusJS supports two dialog styles:

  1. Global builder: dialogInit(...), add*, then dialogShow(...)
  2. Chain builder: dialog("Title").text(...).switch(...).show(...)
dialogInit(title: string): void;
newRow(): void;
dialog(title: string): ChainDialogBuilder;

addLabel(label: string): void;
addInput(id: string, label: string, defaultValue?: string, inputType?: string, requiredOrOptions?: boolean | DialogFieldOptions): void;
addCheckbox(id: string, label: string, isChecked?: boolean, options?: DialogFieldOptions): void;
addSwitch(id: string, label: string, isChecked?: boolean, options?: DialogFieldOptions): void;
addDropdown(id: string, items: string[], defaultValue?: string | null): void;
addComboBox(id: string, items: string[], defaultValue?: string | null): void;
addSlider(id: string, min: number, max: number, defaultValue?: number, options?: DialogFieldOptions): void;
addSeparator(): void;
addMultiSelect(id: string, items: string[], defaultItems?: string[], options?: DialogFieldOptions): void;
addImage(fileName: string): void;
addWheelSpinner(id: string, items: string[], defaultValue?: string | null, options?: DialogFieldOptions): void;
addTab(title: string): void;
addRadioGroup(id: string, label: string, items: string[], defaultValue?: string | null, requiredOrOptions?: boolean | DialogFieldOptions): void;
addTextArea(id: string, label: string, defaultValue?: string, lines?: number, requiredOrOptions?: boolean | DialogFieldOptions): void;
addPassword(id: string, label: string, defaultValue?: string, requiredOrOptions?: boolean | DialogFieldOptions, showToggle?: boolean): void;
addNumberInput(id: string, label: string, defaultValue?: any, min?: number | null, max?: number | null, step?: number | null, requiredOrOptions?: boolean | DialogFieldOptions): void;
addDatePicker(id: string, label: string, defaultValue?: string, requiredOrOptions?: boolean | DialogFieldOptions): void;
addTimePicker(id: string, label: string, defaultValue?: string, requiredOrOptions?: boolean | DialogFieldOptions): void;
addColorPicker(id: string, label: string, defaultValue?: string, requiredOrOptions?: boolean | DialogColorPickerOptions): void;
addFilePicker(id: string, label: string, extensions?: string[], requiredOrOptions?: boolean | DialogPickerOptions): void;
addFolderPicker(id: string, label: string, requiredOrOptions?: boolean | DialogPickerOptions): void;
addLocationPicker(id: string, label: string, options?: DialogPickerOptions): void;
addRegionPicker(id: string, label: string, options?: DialogPickerOptions): void;
addNodePicker(id: string, label: string, options?: DialogPickerOptions): void;
addImageTargetPicker(id: string, label: string, options?: DialogPickerOptions): void;
addTextTargetPicker(id: string, label: string, options?: DialogPickerOptions): void;
addChipGroup(id: string, items: string[], defaultItems?: string[], options?: DialogFieldOptions): void;
addButtonGroup(id: string, label: string, items: string[], defaultValue?: string | null, requiredOrOptions?: boolean | DialogFieldOptions): void;
addInfoBox(text: string, type?: string): void;
addCodeBlock(text: string, language?: string | null): void;
addProgress(id: string, label: string, value?: number, max?: number): void;
addLoading(label?: string | null): void;

confirm(message: string, titleOrOptions?: string | DialogShowOptions, options?: DialogShowOptions): boolean;
prompt(message: string, defaultValue?: string | null, titleOrOptions?: string | DialogShowOptions, options?: DialogShowOptions): string | null;
choose(titleOrMessage: string, items: string[], defaultValueOrOptions?: string | DialogShowOptions | null, options?: DialogShowOptions): string | null;
multiChoose(titleOrMessage: string, items: string[], defaultItemsOrOptions?: string[] | DialogShowOptions | null, options?: DialogShowOptions): string[] | null;
dialogAlert(message: string, titleOrOptions?: string | DialogShowOptions, options?: DialogShowOptions): boolean;
dialogShow(options?: DialogShowOptions): DialogResult | null;
dialogShowFullScreen(options?: DialogFullScreenOptions): DialogResult | null;

ChainDialogBuilder

interface ChainDialogBuilder {
  title(title: string): ChainDialogBuilder;
  message(text: string): ChainDialogBuilder;
  tab(title: string): ChainDialogBuilder;
  section(title: string): ChainDialogBuilder;
  description(text: string): ChainDialogBuilder;
  spacer(size?: number): ChainDialogBuilder;
  info(text: string, type?: string): ChainDialogBuilder;
  code(text: string, language?: string): ChainDialogBuilder;
  label(text: string): ChainDialogBuilder;
  input(id: string, label: string, defaultValue?: string, inputType?: string, options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  text(id: string, label: string, defaultValue?: string, options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  textArea(id: string, label: string, defaultValue?: string, lines?: number, options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  password(id: string, label: string, defaultValue?: string, options?: boolean | DialogPasswordOptions): ChainDialogBuilder;
  number(id: string, label: string, defaultValue?: number | string, options?: DialogFieldOptions): ChainDialogBuilder;
  checkbox(id: string, label: string, checked?: boolean, options?: DialogFieldOptions): ChainDialogBuilder;
  switch(id: string, label: string, checked?: boolean, options?: DialogFieldOptions): ChainDialogBuilder;
  dropdown(id: string, items: string[], defaultValue?: string | null, options?: boolean | DialogChoiceFieldOptions): ChainDialogBuilder;
  comboBox(id: string, items: string[], defaultValue?: string | null, options?: boolean | DialogChoiceFieldOptions): ChainDialogBuilder;
  select(id: string, items: string[], defaultValue?: string | null, options?: boolean | DialogChoiceFieldOptions): ChainDialogBuilder;
  slider(id: string, min: number, max: number, defaultValue?: number, options?: DialogFieldOptions): ChainDialogBuilder;
  multiSelect(id: string, items: string[], defaultItems?: string[], options?: DialogFieldOptions): ChainDialogBuilder;
  chipGroup(id: string, label: string, items: string[], defaultItems?: string[], options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  buttonGroup(id: string, label: string, items: string[], defaultValue?: string | null, options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  wheel(id: string, items: string[], defaultValue?: string | null, options?: DialogFieldOptions): ChainDialogBuilder;
  radioGroup(id: string, label: string, items: string[], defaultValue?: string | null, options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  image(fileName: string): ChainDialogBuilder;
  separator(): ChainDialogBuilder;
  datePicker(id: string, label: string, defaultValue?: string, options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  timePicker(id: string, label: string, defaultValue?: string, options?: boolean | DialogFieldOptions): ChainDialogBuilder;
  colorPicker(id: string, label: string, defaultValue?: string, options?: boolean | DialogColorPickerOptions): ChainDialogBuilder;
  filePicker(id: string, label: string, extensions?: string[], options?: boolean | DialogPickerOptions): ChainDialogBuilder;
  folderPicker(id: string, label: string, options?: boolean | DialogPickerOptions): ChainDialogBuilder;
  locationPicker(id: string, label: string, options?: DialogPickerOptions): ChainDialogBuilder;
  regionPicker(id: string, label: string, options?: DialogPickerOptions): ChainDialogBuilder;
  imageTargetPicker(id: string, label: string, options?: DialogPickerOptions): ChainDialogBuilder;
  nodePicker(id: string, label: string, options?: DialogPickerOptions): ChainDialogBuilder;
  textTargetPicker(id: string, label: string, options?: DialogPickerOptions): ChainDialogBuilder;
  positive(text: string): ChainDialogBuilder;
  negative(text: string): ChainDialogBuilder;
  neutral(text: string): ChainDialogBuilder;
  cancelable(value: boolean): ChainDialogBuilder;
  timeout(seconds: number): ChainDialogBuilder;
  fullScreen(value?: boolean): ChainDialogBuilder;
  show(options?: DialogShowOptions): DialogResult | null;
  showFullScreen(options?: DialogFullScreenOptions): DialogResult | null;
}

Example:

var result = dialog("Bot Settings")
  .text("name", "Name", "", { required: true })
  .switch("enabled", "Enabled", true)
  .show({ positiveButton: "Save", negativeButton: "Cancel" });

if (result) {
  log("Name: " + result.name);
}

Notes for users not using ArgusJS Studio

  • You can write scripts in any text editor.
  • Save scripts as .js files unless you are using protected .argusx scripts.
  • Use this topic as the public API list.
  • For autocomplete in another IDE, copy the latest argusjs.d.ts file from ArgusJS Studio into your editor workspace as a declaration file.
  • If an API returns null, false, or an empty array, check permissions first, then check whether the target app exposes the needed screen, text, or accessibility data.