Control browser
Controls Safari or Chrome: tabs, windows, the page address and title, links, forms and fields.
In the browser, command url
Keyboard Maestro: SafariControl, SafariControlText, SetSafariFieldToText, SetVariableToSafariField, SetSafariCheckbox, SetSafariRadio
Details #
One step for the common things you do in a browser. Pick the command, and the browser: safari, chrome, or front (the default). front uses the browser that is frontmost; if neither is, it uses Safari when running, otherwise Chrome.
Tab and window commands drive the real browser app:
newTabandnewWindow: open one, going to url if given. They open a window first if none is open.nextTabandpreviousTab: move through the front window's tabs, wrapping around.selectTab: choose a tab by number (index), or by part of its title.setURL: send the current tab to a new address (url or value).
Page commands run JavaScript in the front tab:
setTitle: set the page's title to value.clickLink: click a link by its exact text, then by id, name or address, then by part of its text. Its address is the output.focusField,selectField: focus a field, or focus it and select its contents.getField: read a field's value. A checkbox or radio gives its value when checked and empty when not.setField: set a field's value, then fire the page'sinputandchangeevents.setCheckbox: tick or untick, using checked (default true).setRadio: pick the radio button with the group field and the value value.submitForm,resetForm: act on the first form, or the one named in value (name, id or number).waitForLoad: wait until the page has finished loading.
A field is found by its id, its name, its position (a number, counting inputs, selects and text areas on the page) or a CSS selector.
The output is the value read or set, the address for clickLink, or the browser's name for tab and window commands. into stores it in a variable.
Parameters #
| Parameter | Type | Required | Values | What it does |
|---|---|---|---|---|
command | one of | Yes | newTab newWindow nextTab previousTab selectTab setURL setTitle waitForLoad clickLink focusField selectField submitForm resetForm getField setField setCheckbox setRadio | What to do. One of newTab, newWindow, nextTab, previousTab, selectTab, setURL, setTitle, waitForLoad, clickLink, focusField, selectField, submitForm, resetForm, getField, setField, setCheckbox, setRadio. Required. |
browser | one of | safari chrome front | safari, chrome or front. Default front. | |
checked | yes / no | For setCheckbox. Default true. | ||
field | text | The field for the field commands: id, name, number or CSS selector. Required for them. For setRadio it is the group's name. | ||
index | text | The tab for selectTab: a number, or part of the title. | ||
into | text | The variable that receives the output. | ||
tab | text | Another spelling of index. | ||
text | text | Another spelling of value. | ||
timeout | number | Seconds for waitForLoad. Defaults to just under the step's timeout. | ||
url | text | The address for newTab, newWindow and setURL. | ||
value | text | The text for setURL, setTitle, clickLink, setField and setRadio, and the form for submitForm and resetForm. Also used as the address or tab when url or index is empty. |
Every step also accepts label, onFailure, timeout and dryRunSafe.
Examples #
- Browser: wait for load
- Run JavaScript in the front browser “document.title”
- Show “Page: {{ title }}” for 2 s
- Browser: new tab
Gotchas #
The first time, macOS asks to let Switchboard control the browser. If you decline, the step fails and points to System Settings > Privacy & Security > Automation.
Page commands act on the browser's front tab. Switch tabs first if you need another.
Field commands fail with
no field "x" on the page, and link commands withno link "x" on the page.selectTabwith no number or text,setURLwith no address, and a field command with no field all fail with a message saying what is missing.With
frontand neither Safari nor Chrome running, the step fails with "no Safari or Chrome is running".waitForLoadfails with "the page didn't finish loading within N s".In a dry run the step is simulated and the browser is not touched.