Built-in commands cover most automation workflows. When you need custom logic that cannot be expressed with standard blocks, the run_script command gives you full control.

The run_script Command

run_script expects a complete Deno module string. The module must export a default async function with exactly four parameters in this order: page (Playwright Page), context (Browser Context), state (variable and memory store), and helpers (flat helper functions). Do not use arrow-function syntax for the exported function.

{
  "command": "run_script",
  "params": {
    "script": "export default async function(page, context, state, helpers) { return await helpers.safeGoto('https://learn.rtila.com/scenarios/ecommerce/1'); }"
  }
}

Network Helpers

Network helpers are available directly on helpers. Use waitForApiResponse to wait for a matching API response, interceptApiData to attach a temporary response listener, and waitForNetworkIdle to pause until network activity settles.

Navigation Helpers

Navigation helpers also live at the top level of helpers. safeGoto opens a URL and returns the resolved final URL. handleConsent auto-clicks common consent banners, while resolveFinalUrl returns the current URL and its query parameters.

Element Helpers

Element helpers find elements, read attributes, extract text, and simulate clicks. Common helpers include isVisible, isElementPresent, clickAndWait, waitForElement, and fillInput. Use them with try/catch inside the script for local error recovery.

Scroll and Data Helpers

Scroll helpers include autoScroll, which handles infinite scrolling and pagination without writing a manual loop. Data helpers include extractData for dataset extraction and saveData for storing structured results.

{
  "command": "run_script",
  "params": {
    "script": "export default async function(page, context, state, helpers) { return await helpers.extractData('products', { append: true }); }"
  }
}

Script State Management

The state argument contains variables for values that persist across commands. It also contains memory for per-URL scratch state that persists across iterations within a single URL. Keep state minimal and prefer passing data through command output rather than global mutable variables.

Best Practices

• Keep scripts small and testable.
• Use helper utilities instead of direct document.querySelector calls whenever possible.
• Return structured data rather than printing it.
• Avoid external fetch unless the endpoint is inside the target site.
• Write the exported default function with export default async function(page, context, state, helpers), never as an arrow function.

Try It Yourself

Run API Interception scenario 1 to see scripts inspect network responses. Then run E-Commerce scenario 3 for a script that combines product details with API data.