Run JavaScript in browser

Runs JavaScript in the current tab of Safari or Chrome and returns the result.

Run script in the browser

Keyboard Maestro: ExecuteJavaScript

Details #

Runs your script inside the page in the front window's current tab and brings back what it returns as text. Use it to read a page's title, URL or selection, to click something inside a web page, or to fill a form.

Pick the browser with browser:

safari runs in Safari.
chrome runs in Google Chrome.
front (the default) runs in the front app if it is a known browser, otherwise in the first known browser that is running. Known browsers are Safari, Safari Technology Preview, Chrome, Arc, Brave, Microsoft Edge and Vivaldi.

There are two modes:

function (the default). Your script is the body of a function, so it can use return. The run's variables are in an object called vars. The returned value comes back as text: a string as it is, anything else as JSON. Returning nothing gives empty text.
expression. The script is sent as it is and the page reports the value of its last expression. If it mentions vars, the variables are defined first.

Only the variables your script reads are sent to the page, such as vars.name or vars["name"]. If it uses vars as a whole, such as Object.keys(vars), all variables are sent.

The step's output is an object with browser (the browser that ran it) and result (the text). The text also goes into the variable named in into, if you give one. Surrounding whitespace is trimmed unless you turn trim off.

Put the page title in a variable

Run JavaScript in the front browser “return document.title;”
Show “{{title}}” for 2 s

Open in Switchboard to try it

Parameters #

Parameter	Type	Required	Values	What it does
`script`	text	Yes		The JavaScript. Required.
`all`	yes / no
`browser`	one of		`safari` `chrome` `front`	`safari`, `chrome` or `front`.
`into`	text			The variable that receives the result.
`mode`	one of		`function` `expression`	`function` or `expression`.
`sample`	any value			The value `into` gets in a dry run, since the script is not run.
`tab`	any value			, world, all, via: Which tab, which world, every matching tab, and how to reach the browser (see Through the extension).
`timeout`	number			Seconds to allow the script. Defaults to the step timeout.
`trim`	yes / no			On by default. Turn off to keep leading and trailing whitespace.
`via`	one of		`auto` `extension` `appleScript`
`world`	one of		`main` `isolated`

Every step also accepts label, onFailure, timeout and dryRunSafe.

Examples #

Use a variable inside the page:

Search a page for a word (runs in the page; changes nothing)

Set word to “invoice”
Run JavaScript in the front browser “return document.body.innerText.includes…”
Show “Found: {{found}}” for 2 s

Open in Switchboard to try it

The same, as an expression, for Safari only:

Get the selected text in Safari

Run JavaScript in Safari “window.getSelection().toString()”

Open in Switchboard to try it

Gotchas #

A dry run does not run the script. into gets sample, or empty text.
The script runs in the current tab of the front window of that browser. With no window open, the step fails with "has no open window".
A script that throws is reported as "The page's JavaScript failed" with the first line of the error.
Scripts run in the page with the page's own access. They can click, fill and read what the site allows. This is separate from the javaScript step, which runs in Switchboard on its own and cannot see a web page.
A page that must finish loading first needs a Wait or a delay before the script.

Through the extension #

When the Switchboard extension is connected, the script can run in any tab, can await a promise, and works on pages with strict security rules, with no AppleScript setting to turn on:

tab is front (the default), trigger (the tab that started the run), a tab id, or a match like {"url": "github.com"}; all runs it in every tab that matches.
world is main (the default: the page's own variables) or isolated.
via is auto (the extension when connected, else AppleScript), extension or appleScript.

In Chrome this needs Allow User Scripts for the extension; without it the step falls back to AppleScript for the front tab, or fails with that instruction for any other. See Safari and Chrome.

Setting up the browser (AppleScript) #

The browser must allow scripts from outside. This is a setting you turn on once.

Safari. In Safari, choose Develop ▸ Developer Settings and turn on "Allow JavaScript from Apple Events". If there is no Develop menu, open Safari ▸ Settings ▸ Advanced and turn on "Show features for web developers".
Chrome and other Chromium browsers. Choose View ▸ Developer ▸ Allow JavaScript from Apple Events.
Automation permission. The first run asks to let Switchboard control the browser. If you said no, turn it on in System Settings ▸ Privacy & Security ▸ Automation.

When something is missing, the step fails with the instruction for that browser.

Details #

Parameters #

Examples #

Gotchas #

Through the extension #

Setting up the browser (AppleScript) #

See also #