Contents

Scripting API

The script passed to Recce is injected into every execution context created by a page. This includes the root page itself, any iframes, and background workers. Scripts are executed in a closure, with the recce scripting API namespace injected as a preamble.

Methods

await_idle

async recce.await_idle(lull = 2000, timeout = 15000)

Wait for the page to be idle. We use a number of heuristics to judge when a page has loaded or completed pending actions.

Arguments:

  • lull (Integer) - pages which do not have any activity for this length of time, in milliseconds, will be considered idle.
  • timeout (Integer) - the maximum time to wait, in milliseconds, before a page is considered idle.

Returned value: null

done

async recce.done()

Mark this script as done. When all scripts are done, capture may exit. This function is implicitly called when we reach the end of a script.

Arguments: No arguments.

Returned value: null

input

async recce.input(text)

Simulate keystrokes to enter the text. Focus should be handled elsewhere.

Arguments:

  • text (String): string to input.

Returned value: null

fill

async recce.fill(element, text, clear = false, keydelay = 0)

Fill an element with a given text. The element is first scrolled into view, then clicked to give it focus, and then keystrokes are simulated to enter the text.

Arguments:

  • element (Element): DOM element you get from document.getElementById, document.querySelector and other similar methods. More - https://developer.mozilla.org/en-US/docs/Web/API/Element.
  • text (String): string to input.
  • clear (Boolean): clear the element input if true.
  • keydelay (Integer): milliseconds to wait between keystrokes.

Returned value: null

annotate

async recce.annotate(typ, value)

Save passed type-value to recce DB.

Arguments:

  • typ (String)
  • value (Object): any JSON serializable object.

Returned value: null

leak_sentinel

async recce.leak_sentinel(sentinel, data)

Save passed sentinel and related data to recce DB.

Arguments:

  • sentinel (String): sentinel value for leakage detection.
  • data (Object): any JSON serializable object.

Returned value: null

tag_origin

async recce.tag_origin(tag)

Mark origin with a tag.

Arguments:

  • tag (String)

Returned value: null

tag_snapshot

async recce.tag_snapshot(tag, snapshot_id)

Mark snapshot with a tag.

Arguments:

  • tag (String)
  • snapshot_id (String)

Returned value: null

snapshot

async recce.snapshot(type = "full")

Captures a snapshot of the current page.

Arguments:

  • type ("full" | "state"): snapshot type. Full mode captures all data from the page. State mode captures only cookies and web storage (local storage + session storage).

Returned value: snapshot id (String).

axrole_query

async recce.axrole_query(roles)

Search the DOM tree for nodes with a given accessibility role. This function pierces shadow DOM boundaries.

Arguments:

  • roles (Array[String]): array of ARIA accessibility roles from https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles.

Returned value: list of elements and corresponding axnodes (Array[{element: Element, ax: AxNode}]). Element is https://developer.mozilla.org/en-US/docs/Web/API/Element AxNode is https://chromedevtools.github.io/devtools-protocol/tot/Accessibility/#type-AXNode.

log

async recce.log(...objects)

Print objects to recce log output, while avoiding the use of the browser console.

Arguments:

  • objects (Object, ..., Object): arbitrary number of objects to log.

Returned value: null

frame_loaded

async recce.frame_loaded()

Wait until the frame loaded event has triggered for the current frame.

Arguments: No arguments.

Returned value: null

frame_info

async recce.frame_info()

Get contextual information about the current frame and the origin of the session.

Arguments: No arguments.

Returned value: object with type

type FrameInfo {
    /// The target ID of the current frame
    target_id: String;
    /// The ID of the current frame
    frame_id: String;
    url: String;
    mime_type: String;
    /// True if we're the root frame
    root_frame_id: String;
    root_url: String;
    root_mime_type: String;
}

sleep

async recce.sleep(milliseconds)

Sleep for a given number of milliseconds.

Arguments:

  • milliseconds (Integer): number of milliseconds to sleep.

Returned value: null

randstr

async recce.randstr(length)

Generate a random string.

Arguments:

  • length (Integer): random string length.

Returned value: random string (String)

kv_get

async recce.kv_get(key)

Get item from internal recce storage.

Arguments:

  • key (String): storage key.

Returned value: parsed json value (Any JSON-compatible)

kv_set

async recce.kv_set(key, value)

Set item for internal recce storage.

Arguments:

  • key (String): storage key.
  • value (Any JSON-compatible): storage value.

Returned value: null

parse_domain

async recce.parse_domain(domain)

Get info about specified domain.

Arguments:

  • domain (String)

Returned value: object with type

type DomainInfo {
    // The root domain (the registrable part)
    root: String;
    // The part before the root domain (aka. subdomain)
    prefix: String;
    // The domain name suffix (extension)
    suffix: String;
    // Whether the suffix of the domain name is in the Public Suffix List
    known_suffix: bool;
    // Whether this an ICANN delegated suffix
    // ICANN domains are those delegated by ICANN or part of the IANA root zone database
    is_icann: bool;
    // Whether this is a private party delegated suffix
    // PRIVATE domains are amendments submitted by the domain holder, as an expression of how they operate their domain security policy
    is_private: bool;
}

async recce.navigate(url)

Go to specified URL.

Arguments:

  • url (String)

Returned value: null