Class: Commands

Provides debugging capabilities within a browser automation script. It allows setting breakpoints to pause script execution and inspect the current state.

Type:

Debug

error :function

Add a text that will be an error attached to the current page.

Type:

function

Example

await commands.error('My error message');

(async) find :function

Finds an element using a CSS selector, with optional waiting and visibility check.

Type:

function

Example

const element = await commands.find('.my-element', { timeout: 5000, visible: true });

js :JavaScript

Executes JavaScript in the browser context.

Type:

JavaScript

markAsFailure :function

Mark this run as an failure. Add a message that explains the failure.

Type:

function

Example

await commands.markAsFailure('My failure message');

measure :Measure

Provides functionality for measuring a navigation.

Type:

Measure

meta :Meta

Adds metadata to the user journey.

Type:

Meta

(async) navigate :function

Navigates to a specified URL and handles additional setup for a page visit.

Type:

function

Example

await commands.navigate('https://www.example.org');

Provides functionality to control browser navigation such as back, forward, and refresh actions.

Type:

Navigation

perfetto :PerfettoTrace

Provides functionality to collect perfetto traces.

Type:

PerfettoTrace

screenshot :Screenshot

Takes and manages screenshots.

Type:

Screenshot

scroll :Scroll

Provides functionality to control page scrolling in the browser.

Type:

Scroll

simpleperf :SimplePerfProfiler

Provides functionality to collect simpleperf profiles.

Type:

SimplePerfProfiler

stopWatch :StopWatch

Stopwatch utility for measuring time intervals.

Type:

StopWatch

switch :Switch

Switches context to different frames, windows, or tabs in the browser.

Type:

Switch

trace :ChromeTrace

Manages Chrome trace functionality, enabling custom profiling and trace collection in Chrome.

Type:

ChromeTrace

Methods

(async) addText(selector, text) → {Promise.<void>}

Add text to an element using a unified selector string.

Parameters:

Name	Type	Description
`selector`	string	The selector string.
`text`	string	The text to add.

Returns:

Type:: Promise.<void>

Examples

await commands.addText('#search-input', 'search term');

await commands.addText('id:username', 'myuser');

(async) check(selector) → {Promise.<void>}

Checks a checkbox or radio button. Does nothing if already checked.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

Type:: Promise.<void>

Examples

await commands.check('#agree-terms');

await commands.check('id:newsletter-opt-in');

(async) clear(selector) → {Promise.<void>}

Clears the content of a form element matching the selector.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

A promise that resolves when the element is cleared.

Type:: Promise.<void>

Examples

await commands.clear('#search-input');

await commands.clear('id:email');

(async) click(selector, clickOptionsopt) → {Promise.<void>}

Click on an element using a unified selector string. Supports CSS selectors (default), and prefixes: 'id:', 'xpath:', 'text:', 'link:', 'name:', 'class:'.

Parameters:

Name Type Attributes Description

selector string The selector string.

clickOptions

Object

Options for the click.

Properties

Name	Type	Attributes	Default	Description
`waitForNavigation`	boolean	<optional>	false	If true, waits for the page to complete loading after clicking.

Returns:

Type:: Promise.<void>

Examples

await commands.click('#login-btn');

await commands.click('id:login-btn');

await commands.click('text:Submit', { waitForNavigation: true });

(async) exists(selector, existsOptionsopt) → {Promise.<boolean>}

Checks if an element matching the selector exists in the DOM. Unlike find(), this does not throw if the element is not found.

Parameters:

Name Type Attributes Description

selector string The CSS selector or prefixed selector.

existsOptions

Object

Options.

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	0	Maximum time to wait for the element. Default 0 (no wait).

Returns:

True if the element exists.

Type:: Promise.<boolean>

Example

if (await commands.exists('#cookie-banner')) {
  await commands.click('#accept-cookies');
}

(async) fill(fields) → {Promise.<void>}

Fills multiple form fields at once. Each key is a selector, each value is the text to type.

Parameters:

Name	Type	Description
`fields`	Object.<string, string>	An object mapping selectors to values.

Throws:

Throws an error if any element is not found.
Type Error

Returns:

A promise that resolves when all fields are filled.

Type:: Promise.<void>

Example

await commands.fill({
  '#username': 'admin',
  '#password': 'secret',
  'id:email': 'user@example.com'
});

(async) getAttribute(selector, attribute) → {Promise.<string>}

Gets an attribute value of an element matching the selector.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.
`attribute`	string	The attribute name.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

The attribute value.

Type:: Promise.<string>

Examples

const href = await commands.getAttribute('#my-link', 'href');

const dataId = await commands.getAttribute('id:item', 'data-id');

(async) getText(selector) → {Promise.<string>}

Gets the visible text of an element matching the selector.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

The visible text content.

Type:: Promise.<string>

Examples

const text = await commands.getText('#greeting');

const text = await commands.getText('id:heading');

(async) getTitle() → {Promise.<string>}

Gets the title of the current page.

Returns:

The page title.

Type:: Promise.<string>

Example

const title = await commands.getTitle();

(async) getUrl() → {Promise.<string>}

Gets the URL of the current page.

Returns:

The current URL.

Type:: Promise.<string>

Example

const url = await commands.getUrl();

(async) getValue(selector) → {Promise.<string>}

Gets the value of a form element matching the selector.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

The element's value.

Type:: Promise.<string>

Examples

const value = await commands.getValue('#price');

const value = await commands.getValue('id:email');

(async) hover(selector) → {Promise.<void>}

Hovers over an element matching the selector. This is a convenience alias for commands.mouse.moveTo(selector).

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

Type:: Promise.<void>

Examples

await commands.hover('#menu-item');

await commands.hover('id:tooltip-trigger');

(async) isChecked(selector) → {Promise.<boolean>}

Checks if a checkbox or radio button is selected/checked.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

True if the element is checked/selected.

Type:: Promise.<boolean>

Example

const checked = await commands.isChecked('#agree-checkbox');

(async) isEnabled(selector) → {Promise.<boolean>}

Checks if a form element matching the selector is enabled.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

True if the element is enabled.

Type:: Promise.<boolean>

Example

const enabled = await commands.isEnabled('#submit-btn');

(async) isVisible(selector) → {Promise.<boolean>}

Checks if an element matching the selector is visible/displayed.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

True if the element is visible.

Type:: Promise.<boolean>

Example

const visible = await commands.isVisible('#error-message');

(async) press(key) → {Promise.<void>}

Presses a keyboard key. Use key names like 'Enter', 'Tab', 'Escape', 'Backspace', 'ArrowUp', 'ArrowDown', etc.

Parameters:

Name	Type	Description
`key`	string	The key name to press (e.g. 'Enter', 'Tab', 'Escape').

Returns:

Type:: Promise.<void>

Examples

await commands.press('Enter');

await commands.press('Tab');

await commands.press('Escape');

(async) scrollIntoView(selector) → {Promise.<void>}

Scrolls the page so that the element matching the selector is visible in the viewport.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

Type:: Promise.<void>

Examples

await commands.scrollIntoView('#footer');

await commands.scrollIntoView('id:comments-section');

(async) select(selector, selectValue) → {Promise.<void>}

Select an option in a select element using a unified selector string.

Parameters:

Name	Type	Description
`selector`	string	The selector string for the select element.
`selectValue`	string	The value of the option to select.

Returns:

Type:: Promise.<void>

Examples

await commands.select('#country', 'SE');

await commands.select('id:language', 'en');

(async) set(selector, setValue, propertyopt) → {Promise.<void>}

Set a property on an element using a unified selector string.

Parameters:

Name	Type	Attributes	Default	Description
`selector`	string			The selector string for the element.
`setValue`	string			The value to set.
`property`	string	<optional>	'value'	The property: 'value', 'innerText', or 'innerHTML'.

Returns:

Type:: Promise.<void>

Examples

await commands.set('#field', 'new value');

await commands.set('id:title', '<h1>Hello</h1>', 'innerHTML');

(async) type(selector, text) → {Promise.<void>}

Types text into an element identified by a CSS selector. This is a convenience method that wraps addText.bySelector with a more conventional parameter order (selector first, then text).

Parameters:

Name	Type	Description
`selector`	string	The CSS selector of the element.
`text`	string	The text to type into the element.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

A promise that resolves when the text has been added.

Type:: Promise.<void>

Example

await commands.type('#search-input', 'search term');

(async) uncheck(selector) → {Promise.<void>}

Unchecks a checkbox. Does nothing if already unchecked.

Parameters:

Name	Type	Description
`selector`	string	The CSS selector or prefixed selector.

Throws:

Throws an error if the element is not found.
Type Error

Returns:

Type:: Promise.<void>

Examples

await commands.uncheck('#agree-terms');

await commands.uncheck('id:newsletter-opt-in');

(async) wait(selector, waitOptionsopt) → {Promise.<void>}

Wait for an element using a unified selector string.

Parameters:

Name Type Attributes Description

selector string The selector string.

waitOptions

Object

Options for waiting.

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	6000	Maximum time to wait in ms.
`visible`	boolean	<optional>	false	Wait for visibility.

Returns:

Type:: Promise.<void>

Examples

await commands.wait('#my-element', { timeout: 5000 });

await commands.wait('id:loaded', { timeout: 3000, visible: true });

(async) waitForUrl(pattern, urlOptionsopt) → {Promise.<void>}

Waits until the browser's current URL contains the given string. Useful after form submissions, login redirects, or SPA navigation.

Parameters:

Name Type Attributes Description

pattern string The string to match against the current URL.

urlOptions

Object

Options.

Properties

Name	Type	Attributes	Default	Description
`timeout`	number	<optional>	10000	Maximum time to wait in milliseconds.

Throws:

Throws an error if the URL does not match within the timeout.
Type Error

Returns:

Type:: Promise.<void>

Examples

await commands.waitForUrl('dashboard');

await commands.waitForUrl('/account', { timeout: 10000 });

Classes

Members

action :Actions

android :AndroidCommand

bidi :Bidi

cache :Cache

cdp :ChromeDevelopmentToolsProtocol

cookie :Cookie

debug :Debug

error :function

(async) find :function

js :JavaScript

markAsFailure :function

measure :Measure

meta :Meta

(async) navigate :function

navigation :Navigation

perfetto :PerfettoTrace

screenshot :Screenshot

scroll :Scroll

simpleperf :SimplePerfProfiler

stopWatch :StopWatch

switch :Switch

trace :ChromeTrace

Methods

(async) addText(selector, text) → {Promise.<void>}

(async) check(selector) → {Promise.<void>}

(async) clear(selector) → {Promise.<void>}

(async) click(selector, clickOptionsopt) → {Promise.<void>}

Properties

(async) exists(selector, existsOptionsopt) → {Promise.<boolean>}

Properties

(async) fill(fields) → {Promise.<void>}

(async) getAttribute(selector, attribute) → {Promise.<string>}

(async) getText(selector) → {Promise.<string>}

(async) getTitle() → {Promise.<string>}

(async) getUrl() → {Promise.<string>}

(async) getValue(selector) → {Promise.<string>}

(async) hover(selector) → {Promise.<void>}

(async) isChecked(selector) → {Promise.<boolean>}

(async) isEnabled(selector) → {Promise.<boolean>}

(async) isVisible(selector) → {Promise.<boolean>}

(async) press(key) → {Promise.<void>}

(async) scrollIntoView(selector) → {Promise.<void>}

(async) select(selector, selectValue) → {Promise.<void>}

(async) set(selector, setValue, propertyopt) → {Promise.<void>}

(async) type(selector, text) → {Promise.<void>}

(async) uncheck(selector) → {Promise.<void>}

(async) wait(selector, waitOptionsopt) → {Promise.<void>}

Properties

(async) waitForUrl(pattern, urlOptionsopt) → {Promise.<void>}

Properties