DOM automation API

Run safe, named DOM actions inside a controlled tab (no arbitrary code execution).
Docs updated: 2025-12-17

Basics

  • DOM actions are sent as type:"command" messages (wrapped by RTOForm.command()).
  • Most actions require { tabKey, selector }.
  • For dynamic pages, always call waitForSelector before click / getText / setValue.

Common examples

Login pattern

// Example: log in (pseudo example — do NOT put real passwords in logs)
const tabKey = "app";

// Wait for input
await RTOForm.waitForSelector({ tabKey, selector: "#email" }, { timeoutMs: 8000 });

// Fill fields
await RTOForm.setValue({ tabKey, selector: "#email", value: "user@example.com" });
await RTOForm.setValue({ tabKey, selector: "#password", value: "••••••••" });

// Submit
await RTOForm.click({ tabKey, selector: "button[type=submit]" });

// Wait for next page
await RTOForm.waitForSelector({ tabKey, selector: "#dashboard" }, { timeoutMs: 15000 });

Read + write HTML

// Read HTML from a remote element
const htmlData = await RTOForm.getHtml({ tabKey:"app", selector:"#content", prop:"innerHTML" });
console.log("html:", htmlData.html || htmlData);

// Write HTML into a remote element
await RTOForm.setInnerHtml({ tabKey:"app", selector:"#content", html:"<b>Hello</b>" });

Overlay (debug)

// Overlay helpers are for debugging:
// Show a label near a selector
await RTOForm.overlayLabel({ tabKey:"app", selector:"#submit", text:"Click here" });

// Move the label to another element
await RTOForm.overlayMoveTo({ tabKey:"app", selector:"#email" });

// Hide overlay
await RTOForm.overlayHide({ tabKey:"app" });

Button-driven helper

RTO_DOM_actions.js lets you wire buttons with data-attributes instead of writing JS.

<!-- Local textarea is edited by the user -->
<textarea id="localHtml" data-rto-mark-dirty="1" style="width:100%;min-height:140px"></textarea>

<!-- Buttons: read/write remote DOM -->
<button data-rto-action="read-block"  data-rto-tabKey="app" data-rto-selector="#content" data-rto-target="#localHtml">
  Read remote HTML
</button>

<button data-rto-action="write-block" data-rto-tabKey="app" data-rto-selector="#content" data-rto-target="#localHtml">
  Write remote HTML
</button>

<button data-rto-action="highlight" data-rto-tabKey="app" data-rto-selector="#content">Highlight</button>

<script src="../RTO_helpers/RTO_form_api.js"></script>
<script src="../RTO_helpers/RTO_DOM_actions.js"></script>

Selector tips

  • Prefer stable IDs: #login, #submit.
  • Prefer semantic attributes: [name=email], [data-test=submit].
  • Avoid fragile selectors: div:nth-child(3) > span.
  • If a selector fails, you will often see ELEMENT_NOT_FOUND.

Next