By.describe method signature
By.describe(description) returns a By. The description parameter is required and of type string. This method describes the element; the description is used in the trace viewer and reports.
Playwright · API reference · all subjects
core classes: signatures
69 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
By class: purpose and scope
The By class describes an element without being bound to a Page or Frame. It is built with the top-level Playwright.by object and turned into a regular Locator with Page.get(), Frame.get(), or Locator.get(). Since a By carries no page, it can be defined once at module scope and reused by every test, making it a natural fit for page objects.
By.altText method signature
By.altText(text, options) returns a By. The text parameter matches a descendant element by its alt attribute. The text parameter is required. The exact option is optional and works the same as locator text matching.
By.and method signature
By.and(by) returns a By. The by parameter is required and of type By. This method narrows down the match to elements that match both this and the given By.
By.filter method signature
By.filter(options) returns a By. The options object is optional and may include: has (type By, narrows results to those containing elements matching this relative By), hasNot (type By, matches elements that do not contain an element matching this relative By), hasText (optional, text-based filter), hasNotText (optional, negative text-based filter), and visible (optional, visibility filter).
By.first method signature
By.first() returns a By. This method matches the first matching element.
By.get method signature
By.get(selectorOrBy) returns a By. The selectorOrBy parameter is required and of type string or By. This method matches a descendant element by a selector string or by another By. Passing a By composes rather than replaces.
By.testId method signature
By.testId(testId) returns a By. The testId parameter is required. This method matches an element by the test id attribute. The test id attribute is resolved when the By is bound to a page, so a By built at module scope still honours Selectors.setTestIdAttribute() and the testIdAttribute option.
By.text method signature
By.text(text, options) returns a By. The text parameter is required. The exact option is optional. This method matches an element containing the given text.
By.title method signature
By.title(text, options) returns a By. The text parameter is required. The exact option is optional. This method matches an element by its title attribute.
By class example: module-scope reusable locators
Example showing By used for page objects: const saveButton = by.role('button', { name: 'Save' }); const todoItems = by.testId('todo-list').role('listitem'); test('saves a todo', async ({ page }) => { await page.get(saveButton).click(); await expect(page.get(todoItems)).toHaveCount(1); });
By chaining composition example
Example showing By chaining and composition: const rowWithButton = by.get('tr').filter({ hasText: 'text in column 1' }).filter({ has: by.role('button', { name: 'column 2 button' }) });
By.and and By.or chaining examples
Example showing By.and and By.or: const saveButton = by.role('button').and(by.title('Subscribe')); const dialogOrButton = by.role('dialog').or(by.role('button'));
By equivalence with Locator chains
A By chain resolves to the same element as the matching Locator chain. page.get(by.testId('list').text('Row')) and page.getByTestId('list').getByText('Row') are interchangeable. Chaining composes rather than replaces: page.get(outer.get(inner)) and page.get(outer).get(inner) describe the same element.
By.label method signature
By.label(text, options) returns a By. The text parameter is required. The exact option is optional. This method matches an input element by the text of the associated label element or aria-label attribute.
By.last method signature
By.last() returns a By. This method matches the last matching element.
By.nth method signature
By.nth(index) returns a By. The index parameter is required and of type int. This method matches the n-th matching element. It is zero based; nth(0) selects the first element.
By.or method signature
By.or(by) returns a By. The by parameter is required and of type By. This method matches elements matching either this or the given By.
By.placeholder method signature
By.placeholder(text, options) returns a By. The text parameter is required. The exact option is optional. This method matches an input element by the placeholder text.
By.role method signature
By.role(role, options) returns a By. The role parameter is required and specifies an ARIA role. The options object is optional and may include multiple options for filtering by ARIA attributes and accessible name, as well as a description option and an exact option.
Electron.launch timeout parameter
The timeout option is a float parameter representing maximum time in milliseconds to wait for the application to start. Defaults to 30000 (30 seconds). Pass 0 to disable timeout.
Electron.launch context option parameters
The Electron.launch method accepts the following context options: acceptDownloads, bypassCSP, colorScheme, extraHTTPHeaders, geolocation, httpCredentials, ignoreHTTPSErrors, locale, offline, recordHAR, recordHARPath, recordHAROmitContent, recordVideo, recordVideoDir, recordVideoSize, timezoneId, tracesDir, artifactsDir, and chromiumSandbox.
Electron.launch method signature and return type
The async method Electron.launch() returns an ElectronApplication instance. It launches an Electron application as specified in the launch options.
Electron.launch executablePath parameter
The executablePath option is a string parameter that specifies which Electron executable to launch. If not specified, it defaults to the Electron executable installed in the package at node_modules/.bin/electron.
Electron.launch args parameter
The args option is an Array of strings containing additional arguments to pass to the Electron application when launching. Typically used to pass the main script name.
Electron.launch cwd parameter
The cwd option is a string parameter that specifies the current working directory to launch the application from.
Electron.launch env parameter
The env option is an Object with string keys and string values that specifies environment variables visible to Electron. Defaults to process.env.
ElectronApplication.process method signature
ElectronApplication.process() is a synchronous method introduced in v1.21 that returns a ChildProcess object representing the main process for the Electron Application.
ElectronApplication class overview
ElectronApplication is a class introduced in v1.9 for representing Electron application instances. It is obtained via Electron.launch and allows control of the main Electron process and interaction with Electron windows.
ElectronApplication.browserWindow method signature
ElectronApplication.browserWindow(page) is an async method introduced in v1.11 that takes a Page parameter and returns a JSHandle representing the BrowserWindow object that corresponds to the given Playwright page.
ElectronApplication.close method signature
ElectronApplication.close() is an async method introduced in v1.9 that closes the Electron application.
ElectronApplication.context method signature
ElectronApplication.context() is a synchronous method introduced in v1.9 that returns a BrowserContext object which can be used for setting up context-wide routing.
ElectronApplication.evaluate method signature
ElectronApplication.evaluate(expression, arg) is an async method introduced in v1.9 that executes an expression in the Electron context and returns a Serializable value. It takes an optional EvaluationArgument parameter. If the expression returns a Promise, the method waits for it to resolve. Non-serializable values return undefined, except for special values: -0, NaN, Infinity, -Infinity.
ElectronApplication.evaluateHandle method signature
ElectronApplication.evaluateHandle(expression, arg) is an async method introduced in v1.9 that executes an expression in the Electron context and returns a JSHandle. It takes an optional EvaluationArgument parameter. If the expression returns a Promise, the method waits for it to resolve.
ElectronApplication.firstWindow method signature and timeout option
ElectronApplication.firstWindow(timeout) is an async method introduced in v1.9 that returns a Page object representing the first application window. The optional timeout parameter is a float in milliseconds with a default of 30000 (30 seconds). Pass 0 to disable timeout. The default can be changed via BrowserContext.setDefaultTimeout. This method was introduced in v1.33 for the timeout option.
ElectronApplication.waitForEvent method signature
ElectronApplication.waitForEvent(event, optionsOrPredicate) is an async method introduced in v1.9 that waits for an event to fire and returns any value. It accepts an optional optionsOrPredicate parameter which can be a function or an Object. When an Object, it contains: predicate (function, required) that receives event data and resolves to truthy value, and timeout (optional float in milliseconds, default 30000 or 30 seconds, 0 to disable). Throws an error if the application closes before the event fires.
ElectronApplication.windows method signature
ElectronApplication.windows() is a synchronous method introduced in v1.9 that returns an Array of Page objects representing all opened windows.
ElectronApplication example usage
const { _electron: electron } = require('playwright'); (async () => { const electronApp = await electron.launch({ args: ['main.js'] }); const appPath = await electronApp.evaluate(async ({ app }) => { return app.getAppPath(); }); console.log(appPath); const window = await electronApp.firstWindow(); console.log(await window.title()); await window.screenshot({ path: 'intro.png' }); window.on('console', console.log); await window.click('text=Click me'); await electronApp.close(); })();
ElectronApplication.firstWindow example usage
const electronApp = await electron.launch({ args: ['main.js'] }); const window = await electronApp.firstWindow();
ElectronApplication.waitForEvent example usage
const windowPromise = electronApp.waitForEvent('window'); await mainWindow.click('button'); const window = await windowPromise;
Android.connect method signature
Android.connect is an async method available since v1.28 that returns an AndroidDevice. It attaches Playwright to an existing Android device and accepts the following parameters: endpoint (string, required) which is a browser websocket endpoint to connect to; headers (Object<string, string>, optional) for additional HTTP headers to be sent with web socket connect request; slowMo (float, optional, defaults to 0) to slow down Playwright operations by specified milliseconds; timeout (float, optional, defaults to 30000) for maximum time in milliseconds to wait for connection establishment, with 0 disabling timeout.
Android.devices method signature
Android.devices is an async method available since v1.9 that returns Array<AndroidDevice> containing the list of detected Android devices. It accepts the following options: host (string, optional, defaults to 127.0.0.1) to establish ADB server connection; port (int, optional, defaults to 5037) to establish ADB server connection; omitDriverInstall (boolean, optional, available since v1.21) to prevent automatic playwright driver installation on attach.
Android.launchServer method signature
Android.launchServer is an async method available since v1.28 for JavaScript that returns a BrowserServer. It launches a Playwright Android server that clients can connect to. It accepts the following options: adbHost (string, optional, defaults to 127.0.0.1); adbPort (int, optional, defaults to 5037); omitDriverInstall (boolean, optional); deviceSerialNumber (string, optional) to specify which device to launch on; host (string, optional, available since v1.45, defaults to localhost) to set the web socket host; port (int, optional, defaults to 0) to set the web socket port; wsPath (string, optional) to specify the path at which to serve the Android Server, which defaults to an unguessable string.
AndroidDevice class overview
AndroidDevice represents a connected device, either real hardware or emulated. Devices can be obtained using Android.devices. The class has been available since v1.9.
AndroidDevice.close method signature
AndroidDevice.close() is an async method that disconnects from the device. It was added in v1.9. It takes no parameters and returns void.
AndroidDevice.drag method signature
AndroidDevice.drag(selector, dest, options) is an async method that drags the widget defined by selector towards dest point. Parameters: selector (AndroidSelector, required), dest (Object with x and y float properties, required). Options: speed (float, optional), timeout (optional, uses default android-timeout). It was added in v1.9.
AndroidDevice.fill method signature
AndroidDevice.fill(selector, text, options) is an async method that fills the specific selector input box with text. Parameters: selector (AndroidSelector, required), text (string, required). Options: timeout (optional, uses default android-timeout). It was added in v1.9.
AndroidDevice.fling method signature
AndroidDevice.fling(selector, direction, options) is an async method that flings the widget defined by selector in the specified direction. Parameters: selector (AndroidSelector, required), direction (AndroidFlingDirection with values 'down', 'up', 'left', 'right', required). Options: speed (float, optional), timeout (optional, uses default android-timeout). It was added in v1.9.
AndroidDevice.info method signature
AndroidDevice.info(selector) is an async method that returns information about a widget defined by selector. Parameters: selector (AndroidSelector, required). Returns: AndroidElementInfo. It was added in v1.9.
AndroidDevice.input property
AndroidDevice.input is a property of type AndroidInput. It was added in v1.9.
AndroidDevice.installApk method signature
AndroidDevice.installApk(file, options) is an async method that installs an apk on the device. Parameters: file (string or Buffer, required) - either a path to the apk file or apk file content. Options: args (Array of strings, optional) - optional arguments to pass to the shell:cmd package install call. Defaults to '-r -t -S'. It was added in v1.9.
AndroidDevice.launchBrowser method signature
AndroidDevice.launchBrowser(options) is an async method that launches Chrome browser on the device and returns its persistent context. Returns: BrowserContext. Options: pkg (string, optional) - optional package name to launch instead of default Chrome for Android; proxy (optional, uses browser-option-proxy); args (optional, uses browser-option-args); shares inline context parameters. It was added in v1.9, with proxy and args options added in v1.29.
AndroidDevice.longTap method signature
AndroidDevice.longTap(selector, options) is an async method that performs a long tap on the widget defined by selector. Parameters: selector (AndroidSelector, required). Options: timeout (optional, uses default android-timeout). It was added in v1.9.
AndroidDevice.model method signature
AndroidDevice.model() is a method that returns the device model as a string. It was added in v1.9.
AndroidDevice.open method signature
AndroidDevice.open(command) is an async method that launches a process in the shell on the device and returns a socket to communicate with the launched process. Parameters: command (string, required) - shell command to execute. Returns: AndroidSocket. It was added in v1.9.
AndroidDevice.pinchOpen method signature
AndroidDevice.pinchOpen(selector, percent, options) is an async method that pinches the widget defined by selector in the open direction. Parameters: selector (AndroidSelector, required), percent (float, required) - the size of the pinch as a percentage of the widget's size. Options: speed (float, optional), timeout (optional, uses default android-timeout). It was added in v1.9.
AndroidDevice.press method signature
AndroidDevice.press(selector, key, options) is an async method that presses the specific key in the widget defined by selector. Parameters: selector (AndroidSelector, required), key (AndroidKey, required). Options: timeout (optional, uses default android-timeout). It was added in v1.9.
AndroidDevice.push method signature
AndroidDevice.push(file, path, options) is an async method that copies a file to the device. Parameters: file (string or Buffer, required) - either a path to the file or file content, path (string, required) - path to the file on the device. Options: mode (int, optional) - optional file mode, defaults to 644 (rw-r--r--). It was added in v1.9.
AndroidDevice.screenshot method signature
AndroidDevice.screenshot(options) is an async method that returns the buffer with the captured screenshot of the device. Returns: Buffer. Options: path (path, optional) - the file path to save the image to. If path is a relative path, it is resolved relative to the current working directory. If no path is provided, the image won't be saved to the disk. It was added in v1.9.
AndroidDevice.scroll method signature
AndroidDevice.scroll(selector, direction, percent, options) is an async method that scrolls the widget defined by selector in the specified direction. Parameters: selector (AndroidSelector, required), direction (AndroidScrollDirection with values 'down', 'up', 'left', 'right', required), percent (float, required) - distance to scroll as a percentage of the widget's size. Options: speed (float, optional), timeout (optional, uses default android-timeout). It was added in v1.9.