Evaluate JS

Evaluate JS

Type: page-evaluate  ·  Package: Browser v1.0.9  ·  Output: object

Runs JavaScript code in the context of the page and returns the result. It’s an advanced activity: it gives you direct access to the DOM and the page’s APIs for cases the other activities don’t cover — reading a computed value, handling a tricky element, or calling one of the page’s own functions.

For users with JavaScript knowledge

It requires knowing JavaScript and understanding the page. For normal tasks (click, fill, read text), use the specific activities — they’re simpler, more robust and wait on their own for the element to be ready. Turn to Evaluate JS only when there’s no other way.

How it works

It runs the script on the page. It can be an expression (document.title) or a function that receives an argument ((arg) => arg.total * 2), in which case the value of the arg parameter is passed to it. If the script returns a promise, the activity waits for it to resolve. It returns whatever the script returns.

• The script is written as real JavaScript, without quotes around it: it runs in the browser, not in the expression engine. Playbook values are passed through arg, not concatenated into the code.
• arg must be serializable (text, number, boolean, list or dictionary).
• It doesn’t wait for any element and has no timeout: if the script looks for something that isn’t there yet, put a Wait For first.
• The result isn’t written to the log (it may contain page data): the log only says whether there was a result.

Required parameters

Parameter	Type	Default	Description
script	string	—	JavaScript expression or function. E.g. document.title or (arg) => arg.total * 2.

Optional parameters

Parameter	Type	Default	Description
page	ZoanPageSession	—	The page session. Omit it inside a body; outside, pass the session variable (e.g. page = page).
arg	object	—	Argument passed to the script if it is a function.

Output

Returns an object with the value the script returns, serialized: text, number, boolean, list or object. If the script returns nothing (undefined) or returns null, the output is empty. A DOM element is of no use outside the page: return its text or its attributes.

Example

Page Evaluate   script = document.title   → output: titulo

Page Evaluate
  script = () => Array.from(document.querySelectorAll('.price')).map(e => e.innerText)
  → output: precios
For Each   items = precios   itemVariable = precio
 └─ activities:
      Log   message = "Price: " + precio

Pass a playbook value with arg:

Page Evaluate   script = (code) => document.querySelector(`[data-code="${code}"]`)?.innerText   arg = codigoProducto   → output: descripcion

Common errors

Message	Cause and fix
'script' is required.	The script is empty.
JavaScript error (e.g. ReferenceError: x is not defined, TypeError: Cannot read properties of null)	The script failed inside the page. Try it first in the browser console (F12) and guard access to elements that may not exist (?.).
'page' must be a ZoanPageSession.	page is empty outside a body.

Related activities

• Get Text / Get Attribute — simple, recommended options for reading data.
• Click — standard interaction without JavaScript.