# Playwright
Extends Helper
Uses Playwright (opens new window) library to run tests inside:
- Chromium
- Firefox
- Webkit (Safari)
This helper works with a browser out of the box with no additional tools required to install.
Requires playwright
or playwright-core
package version ^1 to be installed:
npm i playwright@^1.18 --save
or
npm i playwright-core@^1.18 --save
Breaking Changes: if you use Playwright v1.38 and later, it will no longer download browsers automatically.
Run npx playwright install
to download browsers after npm install
.
Using playwright-core package, will prevent the download of browser binaries and allow connecting to an existing browser installation or for connecting to a remote one.
# Configuration
This helper should be configured in codecept.conf.(js|ts)
Type: object (opens new window)
# Properties
url
string (opens new window)? base url of website to be testedbrowser
("chromium"
|"firefox"
|"webkit"
|"electron"
)? a browser to test on, either:chromium
,firefox
,webkit
,electron
. Default: chromium.show
boolean (opens new window)? show browser window.restart
(string (opens new window) | boolean (opens new window))? restart strategy between tests. Possible values:* 'context' or false - restarts browser context (opens new window) but keeps running browser. Recommended by Playwright team to keep tests isolated.- 'browser' or true - closes browser and opens it again between tests.
- 'session' or 'keep' - keeps browser context and session, but cleans up cookies and localStorage between tests. The fastest option when running tests in windowed mode. Works with
keepCookies
andkeepBrowserState
options. This behavior was default before CodeceptJS 3.1
timeout
number (opens new window)? * timeout (opens new window) in ms of all Playwright actions .disableScreenshots
boolean (opens new window)? don't save screenshot on failure.emulate
any? browser in device emulation mode.video
boolean (opens new window)? enables video recording for failed tests; videos are saved intooutput/videos
folderkeepVideoForPassedTests
boolean (opens new window)? save videos for passed tests; videos are saved intooutput/videos
foldertrace
boolean (opens new window)? record tracing information (opens new window) with screenshots and snapshots.keepTraceForPassedTests
boolean (opens new window)? save trace for passed tests.fullPageScreenshots
boolean (opens new window)? make full page screenshots on failure.uniqueScreenshotNames
boolean (opens new window)? option to prevent screenshot override if you have scenarios with the same name in different suites.keepBrowserState
boolean (opens new window)? keep browser state between tests whenrestart
is set to 'session'.keepCookies
boolean (opens new window)? keep cookies between tests whenrestart
is set to 'session'.waitForAction
number (opens new window)? how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.waitForNavigation
("load"
|"domcontentloaded"
|"commit"
)? When to consider navigation succeeded. Possible options:load
,domcontentloaded
,commit
. Choose one of those options is possible. See Playwright API (opens new window).pressKeyDelay
number (opens new window)? Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendFieldgetPageTimeout
number (opens new window)? config option to set maximum navigation time in milliseconds.waitForTimeout
number (opens new window)? default wait* timeout in ms. Default: 1000.basicAuth
object (opens new window)? the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}windowSize
string (opens new window)? default window size. Set a dimension like640x480
.colorScheme
("dark"
|"light"
|"no-preference"
)? default color scheme. Possible values:dark
|light
|no-preference
.userAgent
string (opens new window)? user-agent string.locale
string (opens new window)? locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...manualStart
boolean (opens new window)? do not start browser before a test, start it manually inside a helper withthis.helpers["Playwright"]._startBrowser()
.chromium
object (opens new window)? pass additional chromium optionsfirefox
object (opens new window)? pass additional firefox optionselectron
object (opens new window)? (pass additional electron optionschannel
any? (While Playwright can operate against the stock Google Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels of these browsers. See Google Chrome & Microsoft Edge (opens new window).ignoreLog
Array (opens new window)<string (opens new window)>? An array with console message types that are not logged to debug log. Default value is['warning', 'log']
. E.g. you can set[]
to log all messages. See all possible values (opens new window).ignoreHTTPSErrors
boolean (opens new window)? Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value isfalse
bypassCSP
boolean (opens new window)? bypass Content Security Policy or CSPhighlightElement
boolean (opens new window)? highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).recordHar
object (opens new window)? record HAR and will be saved tooutput/har
. See more of HAR options (opens new window).testIdAttribute
string (opens new window)? locate elements based on the testIdAttribute. See more of locate by test id (opens new window).
# Video Recording Customization
By default, video is saved to output/video
dir. You can customize this path by passing dir
option to recordVideo
option.
video
: enables video recording for failed tests; videos are saved into output/videos
folder
keepVideoForPassedTests
: - save videos for passed testsrecordVideo
: additional options for videos customization (opens new window)
# Trace Recording Customization
Trace recording provides complete information on test execution and includes DOM snapshots, screenshots, and network requests logged during run.
Traces will be saved to output/trace
trace
: enables trace recording for failed tests; trace are saved intooutput/trace
folderkeepTraceForPassedTests
: - save trace for passed tests
# HAR Recording Customization
A HAR file is an HTTP Archive file that contains a record of all the network requests that are made when a page is loaded.
It contains information about the request and response headers, cookies, content, timings, and more. You can use HAR files to mock network requests in your tests.
HAR will be saved to output/har
. More info could be found here https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har (opens new window).
...
recordHar: {
mode: 'minimal', // possible values: 'minimal'|'full'.
content: 'embed' // possible values: "omit"|"embed"|"attach".
}
...
# Example #1: Wait for 0 network connections.
{
helpers: {
Playwright : {
url: "http://localhost",
restart: false,
waitForNavigation: "networkidle0",
waitForAction: 500
}
}
}
# Example #2: Wait for DOMContentLoaded event
{
helpers: {
Playwright : {
url: "http://localhost",
restart: false,
waitForNavigation: "domcontentloaded",
waitForAction: 500
}
}
}
# Example #3: Debug in window mode
{
helpers: {
Playwright : {
url: "http://localhost",
show: true
}
}
}
# Example #4: Connect to remote browser by specifying websocket endpoint (opens new window)
{
helpers: {
Playwright: {
url: "http://localhost",
chromium: {
browserWSEndpoint: 'ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a',
cdpConnection: false // default is false
}
}
}
}
# Example #5: Testing with Chromium extensions
official docs (opens new window)
{
helpers: {
Playwright: {
url: "http://localhost",
show: true // headless mode not supported for extensions
chromium: {
// Note: due to this would launch persistent context, so to avoid the error when running tests with run-workers a timestamp would be appended to the defined folder name. For instance: playwright-tmp_1692715649511
userDataDir: '/tmp/playwright-tmp', // necessary to launch the browser in normal mode instead of incognito,
args: [
`--disable-extensions-except=${pathToExtension}`,
`--load-extension=${pathToExtension}`
]
}
}
}
}
# Example #6: Launch tests emulating iPhone 6
const { devices } = require('playwright');
{
helpers: {
Playwright: {
url: "http://localhost",
emulate: devices['iPhone 6'],
}
}
}
# Example #7: Launch test with a specific user locale
{
helpers: {
Playwright : {
url: "http://localhost",
locale: "fr-FR",
}
}
}
# Example #8: Launch test with a specific color scheme
{
helpers: {
Playwright : {
url: "http://localhost",
colorScheme: "dark",
}
}
}
# Example #9: Launch electron test
{
helpers: {
Playwright: {
browser: 'electron',
electron: {
executablePath: require("electron"),
args: [path.join('../', "main.js")],
},
}
},
}
Note: When connecting to remote browser show
and specific chrome
options (e.g. headless
or devtools
) are ignored.
# Access From Helpers
Receive Playwright client from a custom helper by accessing browser
for the Browser object or page
for the current Page object:
const { browser } = this.helpers.Playwright;
await browser.pages(); // List of pages in the browser
// get current page
const { page } = this.helpers.Playwright;
await page.url(); // Get the url of the current page
const { browserContext } = this.helpers.Playwright;
await browserContext.cookies(); // get current browser context
# Parameters
config
# _addPopupListener
Add the 'dialog' event listener to a page
# Parameters
page
# _contextLocator
Grab Locator if called within Context
# Parameters
locator
any
# _createContextPage
Create a new browser context with a page.
Usually it should be run from a custom helper after call of _startBrowser()
# Parameters
contextOptions
object (opens new window)? See https://playwright.dev/docs/api/class-browser#browser-new-context (opens new window)
# _getPageUrl
Gets page URL including hash.
# _locate
Get elements by different locator types, including strict locator Should be used in custom helpers:
const elements = await this.helpers['Playwright']._locate({name: 'password'});
# Parameters
locator
# _locateCheckable
Find a checkbox by providing human-readable text: NOTE: Assumes the checkable element exists
this.helpers['Playwright']._locateCheckable('I agree with terms and conditions').then // ...
# Parameters
locator
providedContext
# _locateClickable
Find a clickable element by providing human-readable text:
this.helpers['Playwright']._locateClickable('Next page').then // ...
# Parameters
locator
# _locateElement
Get the first element by different locator types, including strict locator Should be used in custom helpers:
const element = await this.helpers['Playwright']._locateElement({name: 'password'});
# Parameters
locator
# _locateFields
Find field elements by providing human-readable text:
this.helpers['Playwright']._locateFields('Your email').then // ...
# Parameters
locator
# _setPage
Set current page
# Parameters
page
object (opens new window) page to set
# acceptPopup
Accepts the active JavaScript native popup window, as created by window.alert|window.confirm|window.prompt. Don't confuse popups with modal windows, as created by various libraries (opens new window).
# amAcceptingPopups
Set the automatic popup response to Accept. This must be set before a popup is triggered.
I.amAcceptingPopups();
I.click('#triggerPopup');
I.acceptPopup();
# amCancellingPopups
Set the automatic popup response to Cancel/Dismiss. This must be set before a popup is triggered.
I.amCancellingPopups();
I.click('#triggerPopup');
I.cancelPopup();
# amOnPage
Opens a web page in a browser. Requires relative or absolute url.
If url starts with /
, opens a web page of a site defined in url
config parameter.
I.amOnPage('/'); // opens main page of website
I.amOnPage('https://github.com'); // opens github
I.amOnPage('/login'); // opens a login page
# Parameters
url
string (opens new window) url path or global url.
Returns void automatically synchronized promise through #recorder
# appendField
Appends text to a input field or textarea. Field is located by name, label, CSS or XPath
I.appendField('#myTextField', 'appended');
// typing secret
I.appendField('password', secret('123456'));
# Parameters
field
(string (opens new window) | object (opens new window)) located by label|name|CSS|XPath|strict locatorvalue
string (opens new window) text value to append.
Returns void automatically synchronized promise through #recorder
# attachFile
Attaches a file to element located by label, name, CSS or XPath Path to file is relative current codecept directory (where codecept.conf.ts or codecept.conf.js is located). File will be uploaded to remote system (if tests are running remotely).
I.attachFile('Avatar', 'data/avatar.jpg');
I.attachFile('form input[name=avatar]', 'data/avatar.jpg');
# Parameters
locator
(string (opens new window) | object (opens new window)) field located by label|name|CSS|XPath|strict locator.pathToFile
string (opens new window) local file path relative to codecept.conf.ts or codecept.conf.js config file.
Returns void automatically synchronized promise through #recorder
# blockTraffic
Blocks traffic of a given URL or a list of URLs.
Examples:
I.blockTraffic('http://example.com/css/style.css');
I.blockTraffic('http://example.com/css/*.css');
I.blockTraffic('http://example.com/**');
I.blockTraffic(/.css$/);
I.blockTraffic(['http://example.com/css/style.css', 'http://example.com/css/*.css']);
# Parameters
urls
(string (opens new window) | Array (opens new window) | RegExp (opens new window)) URL or a list of URLs to block . URL can contain * for wildcards. Example: https://www.example.com (opens new window)** to block all traffic for that domain. Regexp are also supported.
# blur
Remove focus from a text input, button, etc. Calls blur (opens new window) on the element.
Examples:
I.blur('.text-area')
//element `#product-tile` is focused
I.see('#add-to-cart-btn');
I.blur('#product-tile')
I.dontSee('#add-to-cart-btn');
# Parameters
locator
(string (opens new window) | object (opens new window)) field located by label|name|CSS|XPath|strict locator.options
any? Playwright only: Additional options (opens new window) for available options object as 2nd argument.
Returns void automatically synchronized promise through #recorder
# cancelPopup
Dismisses the active JavaScript popup, as created by window.alert|window.confirm|window.prompt.
# checkOption
Additional options (opens new window) for check available as 3rd argument.
Examples:
// click on element at position
I.checkOption('Agree', '.signup', { position: { x: 5, y: 5 } })
β οΈ To avoid flakiness, option
force: true
is set by default
Selects a checkbox or radio button. Element is located by label or name or CSS or XPath.
The second parameter is a context (CSS or XPath locator) to narrow the search.
I.checkOption('#agree');
I.checkOption('I Agree to Terms and Conditions');
I.checkOption('agree', '//form');
# Parameters
field
(string (opens new window) | object (opens new window)) checkbox located by label | name | CSS | XPath | strict locator.context
(string (opens new window)? | object (opens new window)) (optional,null
by default) element located by CSS | XPath | strict locator.options
Returns void automatically synchronized promise through #recorder
# clearCookie
Clears a cookie by name, if none provided clears all cookies.
I.clearCookie();
I.clearCookie('test'); // Playwright currently doesn't support clear a particular cookie name
# Parameters
cookie
string (opens new window)? (optional,null
by default) cookie name
# clearField
Clears the text input element: <input>
, <textarea>
or [contenteditable]
.
Examples:
I.clearField('.text-area')
// if this doesn't work use force option
I.clearField('#submit', { force: true })
Use force
to bypass the actionability (opens new window) checks.
# Parameters
locator
(string (opens new window) | object (opens new window)) field located by label|name|CSS|XPath|strict locator.options
any? Additional options (opens new window) for available options object as 2nd argument.
# click
Perform a click on a link or a button, given by a locator. If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string. For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched. For images, the "alt" attribute and inner text of any parent links are searched.
The second parameter is a context (CSS or XPath locator) to narrow the search.
// simple link
I.click('Logout');
// button of form
I.click('Submit');
// CSS button
I.click('#form input[type=submit]');
// XPath
I.click('//form/*[@type=submit]');
// link in context
I.click('Logout', '#nav');
// using strict locator
I.click({css: 'nav a.login'});
# Parameters
locator
(string (opens new window) | object (opens new window)) clickable link or button located by text, or any element located by CSS|XPath|strict locator.context
(string (opens new window)? | object (opens new window) | null) (optional,null
by default) element to search in CSS|XPath|Strict locator.options
any? Additional options (opens new window) for click available as 3rd argument.
# Examples
```js
// click on element at position
I.click('canvas', '.model', { position: { x: 20, y: 40 } })
// make ctrl-click
I.click('.edit', null, { modifiers: ['Ctrl'] } )
```
Returns void automatically synchronized promise through #recorder
# clickLink
Clicks link and waits for navigation (deprecated)
# Parameters
locator
context
# closeCurrentTab
Close current tab and switches to previous.
I.closeCurrentTab();
# closeOtherTabs
Close all tabs except for the current one.
I.closeOtherTabs();
# dontSee
Opposite to see
. Checks that a text is not present on a page.
Use context parameter to narrow down the search.
I.dontSee('Login'); // assume we are already logged in.
I.dontSee('Login', '.nav'); // no login inside .nav element
# Parameters
text
string (opens new window) which is not present.context
(string (opens new window) | object (opens new window))? (optional) element located by CSS|XPath|strict locator in which to perfrom search.
Returns void automatically synchronized promise through #recorder
# dontSeeCheckboxIsChecked
Verifies that the specified checkbox is not checked.
I.dontSeeCheckboxIsChecked('#agree'); // located by ID
I.dontSeeCheckboxIsChecked('I agree to terms'); // located by label
I.dontSeeCheckboxIsChecked('agree'); // located by name
# Parameters
field
(string (opens new window) | object (opens new window)) located by label|name|CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# dontSeeCookie
Checks that cookie with given name does not exist.
I.dontSeeCookie('auth'); // no auth cookie
# Parameters
name
string (opens new window) cookie name.
Returns void automatically synchronized promise through #recorder
# dontSeeCurrentUrlEquals
Checks that current url is not equal to provided one. If a relative url provided, a configured url will be prepended to it.
I.dontSeeCurrentUrlEquals('/login'); // relative url are ok
I.dontSeeCurrentUrlEquals('http://mysite.com/login'); // absolute urls are also ok
# Parameters
url
string (opens new window) value to check.
Returns void automatically synchronized promise through #recorder
# dontSeeElement
Opposite to seeElement
. Checks that element is not visible (or in DOM)
I.dontSeeElement('.modal'); // modal is not shown
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|Strict locator.
Returns void automatically synchronized promise through #recorder
# dontSeeElementInDOM
Opposite to seeElementInDOM
. Checks that element is not on page.
I.dontSeeElementInDOM('.nav'); // checks that element is not on page visible or not
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|Strict locator.
Returns void automatically synchronized promise through #recorder
# dontSeeInCurrentUrl
Checks that current url does not contain a provided fragment.
# Parameters
url
string (opens new window) value to check.
Returns void automatically synchronized promise through #recorder
# dontSeeInField
Checks that value of input field or textarea doesn't equal to given value
Opposite to seeInField
.
I.dontSeeInField('email', '[email protected]'); // field by name
I.dontSeeInField({ css: 'form input.email' }, '[email protected]'); // field by CSS
# Parameters
field
(string (opens new window) | object (opens new window)) located by label|name|CSS|XPath|strict locator.value
(string (opens new window) | object (opens new window)) value to check.
Returns void automatically synchronized promise through #recorder
# dontSeeInSource
Checks that the current page does not contains the given string in its raw source code.
I.dontSeeInSource('<!--'); // no comments in source
# Parameters
text
value
string (opens new window) to check.
Returns void automatically synchronized promise through #recorder
# dontSeeInTitle
Checks that title does not contain text.
I.dontSeeInTitle('Error');
# Parameters
text
string (opens new window) value to check.
Returns void automatically synchronized promise through #recorder
# dontSeeTraffic
Verifies that a certain request is not part of network traffic.
Examples:
I.dontSeeTraffic({ name: 'Unexpected API Call', url: 'https://api.example.com' });
I.dontSeeTraffic({ name: 'Unexpected API Call of "user" endpoint', url: /api.example.com.*user/ });
# Parameters
opts
Object (opens new window) options when checking the traffic network.opts.name
string (opens new window) A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.opts.url
(string (opens new window) | RegExp (opens new window)) Expected URL of request in network traffic. Can be a string or a regular expression.
Returns void automatically synchronized promise through #recorder
# doubleClick
Performs a double-click on an element matched by link|button|label|CSS or XPath. Context can be specified as second parameter to narrow search.
I.doubleClick('Edit');
I.doubleClick('Edit', '.actions');
I.doubleClick({css: 'button.accept'});
I.doubleClick('.btn.edit');
# Parameters
locator
(string (opens new window) | object (opens new window)) clickable link or button located by text, or any element located by CSS|XPath|strict locator.context
(string (opens new window)? | object (opens new window)) (optional,null
by default) element to search in CSS|XPath|Strict locator.
Returns void automatically synchronized promise through #recorder
# dragAndDrop
// specify coordinates for source position
I.dragAndDrop('img.src', 'img.dst', { sourcePosition: {x: 10, y: 10} })
When no option is set, custom drag and drop would be used, to use the dragAndDrop API from Playwright, please set options, for example
force: true
Drag an item to a destination element.
I.dragAndDrop('#dragHandle', '#container');
# Parameters
srcElement
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.destElement
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.options
any? Additional options (opens new window) can be passed as 3rd argument.
Returns void automatically synchronized promise through #recorder
# dragSlider
Drag the scrubber of a slider to a given position For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
I.dragSlider('#slider', 30);
I.dragSlider('#slider', -70);
# Parameters
locator
(string (opens new window) | object (opens new window)) located by label|name|CSS|XPath|strict locator.offsetX
number (opens new window) position to drag.
Returns void automatically synchronized promise through #recorder
# executeScript
Executes a script on the page:
I.executeScript(() => window.alert('Hello world'));
Additional parameters of the function can be passed as an object argument:
I.executeScript(({x, y}) => x + y, {x, y});
You can pass only one parameter into a function, or you can pass in array or object.
I.executeScript(([x, y]) => x + y, [x, y]);
If a function returns a Promise it will wait for its resolution.
# Parameters
fn
(string (opens new window) | function (opens new window)) function to be executed in browser context.arg
any? optional argument to pass to the function
Returns Promise (opens new window)
# fillField
Fills a text field or textarea, after clearing its value, with the given string. Field is located by name, label, CSS, or XPath.
// by label
I.fillField('Email', '[email protected]');
// by name
I.fillField('password', secret('123456'));
// by CSS
I.fillField('form#login input[name=username]', 'John');
// or by strict locator
I.fillField({css: 'form#login input[name=username]'}, 'John');
# Parameters
field
(string (opens new window) | object (opens new window)) located by label|name|CSS|XPath|strict locator.value
(string (opens new window) | object (opens new window)) text value to fill.
Returns void automatically synchronized promise through #recorder
# flushNetworkTraffics
Resets all recorded network requests.
I.flushNetworkTraffics();
# flushWebSocketMessages
Resets all recorded WS messages.
# focus
Calls focus (opens new window) on the matching element.
Examples:
I.dontSee('#add-to-cart-btn');
I.focus('#product-tile')
I.see('#add-to-cart-bnt');
# Parameters
locator
(string (opens new window) | object (opens new window)) field located by label|name|CSS|XPath|strict locator.options
any? Playwright only: Additional options (opens new window) for available options object as 2nd argument.
Returns void automatically synchronized promise through #recorder
# forceClick
Perform an emulated click on a link or a button, given by a locator. Unlike normal click instead of sending native event, emulates a click with JavaScript. This works on hidden, animated or inactive elements as well.
If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string. For buttons, the "value" attribute, "name" attribute, and inner text are searched. For links, the link text is searched. For images, the "alt" attribute and inner text of any parent links are searched.
The second parameter is a context (CSS or XPath locator) to narrow the search.
// simple link
I.forceClick('Logout');
// button of form
I.forceClick('Submit');
// CSS button
I.forceClick('#form input[type=submit]');
// XPath
I.forceClick('//form/*[@type=submit]');
// link in context
I.forceClick('Logout', '#nav');
// using strict locator
I.forceClick({css: 'nav a.login'});
# Parameters
locator
(string (opens new window) | object (opens new window)) clickable link or button located by text, or any element located by CSS|XPath|strict locator.context
(string (opens new window)? | object (opens new window)) (optional,null
by default) element to search in CSS|XPath|Strict locator.
Returns void automatically synchronized promise through #recorder
# grabAttributeFrom
Retrieves an attribute from an element located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async with await
operator.
If more than one element is found - attribute of first element is returned.
let hint = await I.grabAttributeFrom('#tooltip', 'title');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.attr
string (opens new window) attribute name.
Returns Promise (opens new window)<string (opens new window)> attribute value
# grabAttributeFromAll
Retrieves an array of attributes from elements located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async with await
operator.
let hints = await I.grabAttributeFromAll('.tooltip', 'title');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.attr
string (opens new window) attribute name.
Returns Promise (opens new window)<Array (opens new window)<string (opens new window)>> attribute value
# grabBrowserLogs
Get JS log from browser.
const logs = await I.grabBrowserLogs();
const errors = logs.map(l => ({ type: l.type(), text: l.text() })).filter(l => l.type === 'error');
console.log(JSON.stringify(errors));
Learn more about console messages (opens new window)
Returns Promise (opens new window)<Array (opens new window)
# grabCheckedElementStatus
Return the checked status of given element.
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.options
object (opens new window)? See https://playwright.dev/docs/api/class-locator#locator-is-checked (opens new window)
Returns Promise (opens new window)<boolean (opens new window)>
# grabCookie
Returns cookie in JSON format. If name not passed returns all cookies for this domain.
Gets a cookie object by name.
If none provided gets all cookies.
Resumes test execution, so should be used inside async function with await
operator.
let cookie = await I.grabCookie('auth');
assert(cookie.value, '123456');
# Parameters
name
string (opens new window)? cookie name.
Returns any attribute value
# grabCssPropertyFrom
Grab CSS property for given locator
Resumes test execution, so should be used inside an async function with await
operator.
If more than one element is found - value of first element is returned.
const value = await I.grabCssPropertyFrom('h3', 'font-weight');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.cssProperty
string (opens new window) CSS property name.
Returns Promise (opens new window)<string (opens new window)> CSS value
# grabCssPropertyFromAll
Grab array of CSS properties for given locator
Resumes test execution, so should be used inside an async function with await
operator.
const values = await I.grabCssPropertyFromAll('h3', 'font-weight');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.cssProperty
string (opens new window) CSS property name.
Returns Promise (opens new window)<Array (opens new window)<string (opens new window)>> CSS value
# grabCurrentUrl
Get current URL from browser. Resumes test execution, so should be used inside an async function.
let url = await I.grabCurrentUrl();
console.log(`Current URL is [${url}]`);
Returns Promise (opens new window)<string (opens new window)> current URL
# grabDataFromPerformanceTiming
Grab the data from performance timing using Navigation Timing API. The returned data will contain following things in ms:
- responseEnd,
- domInteractive,
- domContentLoadedEventEnd,
- loadEventEnd
Resumes test execution, so should be used inside an async function with
await
operator.
await I.amOnPage('https://example.com');
let data = await I.grabDataFromPerformanceTiming();
//Returned data
{ // all results are in [ms]
responseEnd: 23,
domInteractive: 44,
domContentLoadedEventEnd: 196,
loadEventEnd: 241
}
Returns void automatically synchronized promise through #recorder
# grabDisabledElementStatus
Return the disabled status of given element.
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.options
object (opens new window)? See https://playwright.dev/docs/api/class-locator#locator-is-disabled (opens new window)
Returns Promise (opens new window)<boolean (opens new window)>
# grabElementBoundingRect
Grab the width, height, location of given locator.
Provide width
or height
as second param to get your desired prop.
Resumes test execution, so should be used inside an async function with await
operator.
Returns an object with x
, y
, width
, height
keys.
const value = await I.grabElementBoundingRect('h3');
// value is like { x: 226.5, y: 89, width: 527, height: 220 }
To get only one metric use second parameter:
const width = await I.grabElementBoundingRect('h3', 'width');
// width == 527
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.prop
elementSize
string (opens new window)? x, y, width or height of the given element.
Returns (Promise (opens new window)
# grabHTMLFrom
Retrieves the innerHTML from an element located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async function with await
operator.
If more than one element is found - HTML of first element is returned.
let postHTML = await I.grabHTMLFrom('#post');
# Parameters
locator
element
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.
Returns Promise (opens new window)<string (opens new window)> HTML code for an element
# grabHTMLFromAll
Retrieves all the innerHTML from elements located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async function with await
operator.
let postHTMLs = await I.grabHTMLFromAll('.post');
# Parameters
locator
element
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.
Returns Promise (opens new window)<Array (opens new window)<string (opens new window)>> HTML code for an element
# grabMetrics
Return a performance metric from the chrome cdp session. Note: Chrome-only
Examples:
const metrics = await I.grabMetrics();
// returned metrics
[
{ name: 'Timestamp', value: 1584904.203473 },
{ name: 'AudioHandlers', value: 0 },
{ name: 'AudioWorkletProcessors', value: 0 },
{ name: 'Documents', value: 22 },
{ name: 'Frames', value: 10 },
{ name: 'JSEventListeners', value: 366 },
{ name: 'LayoutObjects', value: 1240 },
{ name: 'MediaKeySessions', value: 0 },
{ name: 'MediaKeys', value: 0 },
{ name: 'Nodes', value: 4505 },
{ name: 'Resources', value: 141 },
{ name: 'ContextLifecycleStateObservers', value: 34 },
{ name: 'V8PerContextDatas', value: 4 },
{ name: 'WorkerGlobalScopes', value: 0 },
{ name: 'UACSSResources', value: 0 },
{ name: 'RTCPeerConnections', value: 0 },
{ name: 'ResourceFetchers', value: 22 },
{ name: 'AdSubframes', value: 0 },
{ name: 'DetachedScriptStates', value: 2 },
{ name: 'ArrayBufferContents', value: 1 },
{ name: 'LayoutCount', value: 0 },
{ name: 'RecalcStyleCount', value: 0 },
{ name: 'LayoutDuration', value: 0 },
{ name: 'RecalcStyleDuration', value: 0 },
{ name: 'DevToolsCommandDuration', value: 0.000013 },
{ name: 'ScriptDuration', value: 0 },
{ name: 'V8CompileDuration', value: 0 },
{ name: 'TaskDuration', value: 0.000014 },
{ name: 'TaskOtherDuration', value: 0.000001 },
{ name: 'ThreadTime', value: 0.000046 },
{ name: 'ProcessTime', value: 0.616852 },
{ name: 'JSHeapUsedSize', value: 19004908 },
{ name: 'JSHeapTotalSize', value: 26820608 },
{ name: 'FirstMeaningfulPaint', value: 0 },
{ name: 'DomContentLoaded', value: 1584903.690491 },
{ name: 'NavigationStart', value: 1584902.841845 }
]
Returns Promise (opens new window)<Array (opens new window)<Object (opens new window)>>
# grabNumberOfOpenTabs
Grab number of open tabs.
Resumes test execution, so should be used inside async function with await
operator.
let tabs = await I.grabNumberOfOpenTabs();
Returns Promise (opens new window)<number (opens new window)> number of open tabs
# grabNumberOfVisibleElements
Grab number of visible elements by locator.
Resumes test execution, so should be used inside async function with await
operator.
let numOfElements = await I.grabNumberOfVisibleElements('p');
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.
Returns Promise (opens new window)<number (opens new window)> number of visible elements
# grabPageScrollPosition
Retrieves a page scroll position and returns it to test.
Resumes test execution, so should be used inside an async function with await
operator.
let { x, y } = await I.grabPageScrollPosition();
Returns Promise (opens new window)
# grabPopupText
Grab the text within the popup. If no popup is visible then it will return null
await I.grabPopupText();
Returns Promise (opens new window)<(string (opens new window) | null)>
# grabRecordedNetworkTraffics
Grab the recording network traffics
const traffics = await I.grabRecordedNetworkTraffics();
expect(traffics[0].url).to.equal('https://reqres.in/api/comments/1');
expect(traffics[0].response.status).to.equal(200);
expect(traffics[0].response.body).to.contain({ name: 'this was mocked' });
Returns Array (opens new window) recorded network traffics
# grabSource
Retrieves page source and returns it to test.
Resumes test execution, so should be used inside async function with await
operator.
let pageSource = await I.grabSource();
Returns Promise (opens new window)<string (opens new window)> source code
# grabTextFrom
Retrieves a text from an element located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async with await
operator.
let pin = await I.grabTextFrom('#pin');
If multiple elements found returns first element.
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.
Returns Promise (opens new window)<string (opens new window)> attribute value
# grabTextFromAll
Retrieves all texts from an element located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async with await
operator.
let pins = await I.grabTextFromAll('#pin li');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.
Returns Promise (opens new window)<Array (opens new window)<string (opens new window)>> attribute value
# grabTitle
Retrieves a page title and returns it to test.
Resumes test execution, so should be used inside async with await
operator.
let title = await I.grabTitle();
Returns Promise (opens new window)<string (opens new window)> title
# grabTrafficUrl
Returns full URL of request matching parameter "urlMatch".
Examples:
I.grabTrafficUrl('https://api.example.com/session');
I.grabTrafficUrl(/session.*start/);
# Parameters
urlMatch
(string (opens new window) | RegExp (opens new window)) Expected URL of request in network traffic. Can be a string or a regular expression.
Returns Promise (opens new window)
# grabValueFrom
Retrieves a value from a form element located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async function with await
operator.
If more than one element is found - value of first element is returned.
let email = await I.grabValueFrom('input[name=email]');
# Parameters
locator
(string (opens new window) | object (opens new window)) field located by label|name|CSS|XPath|strict locator.
Returns Promise (opens new window)<string (opens new window)> attribute value
# grabValueFromAll
Retrieves an array of value from a form located by CSS or XPath and returns it to test.
Resumes test execution, so should be used inside async function with await
operator.
let inputs = await I.grabValueFromAll('//form/input');
# Parameters
locator
(string (opens new window) | object (opens new window)) field located by label|name|CSS|XPath|strict locator.
Returns Promise (opens new window)<Array (opens new window)<string (opens new window)>> attribute value
# grabWebElement
Grab WebElement for given locator
Resumes test execution, so should be used inside an async function with await
operator.
const webElement = await I.grabWebElement('#button');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.
Returns Promise (opens new window)
# grabWebElements
Grab WebElements for given locator
Resumes test execution, so should be used inside an async function with await
operator.
const webElements = await I.grabWebElements('#button');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.
Returns Promise (opens new window)
# grabWebSocketMessages
Grab the recording WS messages
Returns Array (opens new window)
# handleDownloads
Handles a file download. A file name is required to save the file on disk. Files are saved to "output" directory.
Should be used with FileSystem helper (opens new window) to check that file were downloaded correctly.
I.handleDownloads('downloads/avatar.jpg');
I.click('Download Avatar');
I.amInPath('output/downloads');
I.waitForFile('avatar.jpg', 5);
# Parameters
fileName
string (opens new window) set filename for downloaded file
Returns Promise (opens new window)
# makeApiRequest
Performs api request (opens new window) using the cookies from the current browser session.
const users = await I.makeApiRequest('GET', '/api/users', { params: { page: 1 }});
users[0]
I.makeApiRequest('PATCH', )
This is Playwright's built-in alternative to using REST helper's sendGet, sendPost, etc methods.
# Parameters
method
string (opens new window) HTTP methodurl
string (opens new window) endpointoptions
object (opens new window) request options depending on method used
Returns Promise (opens new window)<object (opens new window)> response
# mockRoute
Mocks network request using browserContext.route
(opens new window) of Playwright
I.mockRoute(/(.png$)|(.jpg$)/, route => route.abort());
This method allows intercepting and mocking requests & responses. Learn more about it (opens new window)
# Parameters
url
(string (opens new window) | RegExp (opens new window))? URL, regex or pattern for to match URLhandler
function (opens new window)? a function to process request
# mockTraffic
Mocks traffic for URL(s). This is a powerful feature to manipulate network traffic. Can be used e.g. to stabilize your tests, speed up your tests or as a last resort to make some test scenarios even possible.
Examples:
I.mockTraffic('/api/users/1', '{ id: 1, name: 'John Doe' }');
I.mockTraffic('/api/users/*', JSON.stringify({ id: 1, name: 'John Doe' }));
I.mockTraffic([/^https://api.example.com/v1/, 'https://api.example.com/v2/**'], 'Internal Server Error', 'text/html');
# Parameters
urls
string|Array These are the URL(s) to mock, e.g. "/fooapi/" or "['/fooapi_1/', '/barapi_2/*']". Regular expressions are also supported.responseString
string The string to return in fake response's body.contentType
Content type of fake response. If not specified default value 'application/json' is used.
# moveCursorTo
Moves cursor to element matched by locator. Extra shift can be set with offsetX and offsetY options.
I.moveCursorTo('.tooltip');
I.moveCursorTo('#submit', 5,5);
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.offsetX
number (opens new window) (optional,0
by default) X-axis offset.offsetY
number (opens new window) (optional,0
by default) Y-axis offset.
Returns void automatically synchronized promise through #recorder
# openNewTab
Open new tab and automatically switched to new tab
I.openNewTab();
You can pass in page options (opens new window) to emulate device on this page
// enable mobile
I.openNewTab({ isMobile: true });
# Parameters
options
# pressKey
Note: Shortcuts like 'Meta'
+ 'A'
do not work on macOS (GoogleChrome/Puppeteer#1313 (opens new window)).
Presses a key in the browser (on a focused element).
Hint: For populating text field or textarea, it is recommended to use fillField
.
I.pressKey('Backspace');
To press a key in combination with modifier keys, pass the sequence as an array. All modifier keys ('Alt'
, 'Control'
, 'Meta'
, 'Shift'
) will be released afterwards.
I.pressKey(['Control', 'Z']);
For specifying operation modifier key based on operating system it is suggested to use 'CommandOrControl'
.
This will press 'Command'
(also known as 'Meta'
) on macOS machines and 'Control'
on non-macOS machines.
I.pressKey(['CommandOrControl', 'Z']);
Some of the supported key names are:
'AltLeft'
or'Alt'
'AltRight'
'ArrowDown'
'ArrowLeft'
'ArrowRight'
'ArrowUp'
'Backspace'
'Clear'
'ControlLeft'
or'Control'
'ControlRight'
'Command'
'CommandOrControl'
'Delete'
'End'
'Enter'
'Escape'
'F1'
to'F12'
'Home'
'Insert'
'MetaLeft'
or'Meta'
'MetaRight'
'Numpad0'
to'Numpad9'
'NumpadAdd'
'NumpadDecimal'
'NumpadDivide'
'NumpadMultiply'
'NumpadSubtract'
'PageDown'
'PageUp'
'Pause'
'Return'
'ShiftLeft'
or'Shift'
'ShiftRight'
'Space'
'Tab'
# Parameters
key
(string (opens new window) | Array (opens new window)<string (opens new window)>) key or array of keys to press.
Returns void automatically synchronized promise through #recorder
# pressKeyDown
Presses a key in the browser and leaves it in a down state.
To make combinations with modifier key and user operation (e.g. 'Control'
+ click
).
I.pressKeyDown('Control');
I.click('#element');
I.pressKeyUp('Control');
# Parameters
key
string (opens new window) name of key to press down.
Returns void automatically synchronized promise through #recorder
# pressKeyUp
Releases a key in the browser which was previously set to a down state.
To make combinations with modifier key and user operation (e.g. 'Control'
+ click
).
I.pressKeyDown('Control');
I.click('#element');
I.pressKeyUp('Control');
# Parameters
key
string (opens new window) name of key to release.
Returns void automatically synchronized promise through #recorder
# refreshPage
Reload the current page.
I.refreshPage();
Returns void automatically synchronized promise through #recorder
# replayFromHar
Replaying from HAR
// Replay API requests from HAR.
// Either use a matching response from the HAR,
// or abort the request if nothing matches.
I.replayFromHar('./output/har/something.har', { url: "*/**/api/v1/fruits" });
I.amOnPage('https://demo.playwright.dev/api-mocking');
I.see('CodeceptJS');
# Parameters
harFilePath
string (opens new window) Path to recorded HAR fileopts
object (opens new window)? Options for replaying from HAR (opens new window)
Returns any Promise
# resizeWindow
Unlike other drivers Playwright changes the size of a viewport, not the window! Playwright does not control the window of a browser, so it can't adjust its real size. It also can't maximize a window.
Update configuration to change real window size on start:
// inside codecept.conf.js
// @codeceptjs/configure package must be installed
{ setWindowSize } = require('@codeceptjs/configure');
Resize the current window to provided width and height.
First parameter can be set to maximize
.
# Parameters
width
number (opens new window) width in pixels ormaximize
.height
number (opens new window) height in pixels.
Returns void automatically synchronized promise through #recorder
# restartBrowser
Restart browser with a new context and a new page
// Restart browser and use a new timezone
I.restartBrowser({ timezoneId: 'America/Phoenix' });
// Open URL in a new page in changed timezone
I.amOnPage('/');
// Restart browser, allow reading/copying of text from/into clipboard in Chrome
I.restartBrowser({ permissions: ['clipboard-read', 'clipboard-write'] });
# Parameters
contextOptions
object (opens new window)? Options for browser context (opens new window) when starting new browser
# rightClick
Performs right click on a clickable element matched by semantic locator, CSS or XPath.
// right click element with id el
I.rightClick('#el');
// right click link or button with text "Click me"
I.rightClick('Click me');
// right click button with text "Click me" inside .context
I.rightClick('Click me', '.context');
# Parameters
locator
(string (opens new window) | object (opens new window)) clickable element located by CSS|XPath|strict locator.context
(string (opens new window)? | object (opens new window)) (optional,null
by default) element located by CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# saveElementScreenshot
Saves screenshot of the specified locator to ouput folder (set in codecept.conf.ts or codecept.conf.js). Filename is relative to output folder.
I.saveElementScreenshot(`#submit`,'debug.png');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.fileName
string (opens new window) file name to save.
Returns void automatically synchronized promise through #recorder
# saveScreenshot
Saves a screenshot to ouput folder (set in codecept.conf.ts or codecept.conf.js).
Filename is relative to output folder.
Optionally resize the window to the full available page scrollHeight
and scrollWidth
to capture the entire page by passing true
in as the second argument.
I.saveScreenshot('debug.png');
I.saveScreenshot('debug.png', true) //resizes to available scrollHeight and scrollWidth before taking screenshot
# Parameters
fileName
string (opens new window) file name to save.fullPage
boolean (opens new window) (optional,false
by default) flag to enable fullscreen screenshot mode.
Returns void automatically synchronized promise through #recorder
# scrollPageToBottom
Scroll page to the bottom.
I.scrollPageToBottom();
Returns void automatically synchronized promise through #recorder
# scrollPageToTop
Scroll page to the top.
I.scrollPageToTop();
Returns void automatically synchronized promise through #recorder
# scrollTo
Scrolls to element matched by locator. Extra shift can be set with offsetX and offsetY options.
I.scrollTo('footer');
I.scrollTo('#submit', 5, 5);
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.offsetX
number (opens new window) (optional,0
by default) X-axis offset.offsetY
number (opens new window) (optional,0
by default) Y-axis offset.
Returns void automatically synchronized promise through #recorder
# see
Checks that a page contains a visible text. Use context parameter to narrow down the search.
I.see('Welcome'); // text welcome on a page
I.see('Welcome', '.content'); // text inside .content div
I.see('Register', {css: 'form.register'}); // use strict locator
# Parameters
text
string (opens new window) expected on page.context
(string (opens new window)? | object (opens new window)) (optional,null
by default) element located by CSS|Xpath|strict locator in which to search for text.
Returns void automatically synchronized promise through #recorder
# seeAttributesOnElements
Checks that all elements with given locator have given attributes.
I.seeAttributesOnElements('//form', { method: "post"});
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.attributes
object (opens new window) attributes and their values to check.
Returns void automatically synchronized promise through #recorder
# seeCheckboxIsChecked
Verifies that the specified checkbox is checked.
I.seeCheckboxIsChecked('Agree');
I.seeCheckboxIsChecked('#agree'); // I suppose user agreed to terms
I.seeCheckboxIsChecked({css: '#signup_form input[type=checkbox]'});
# Parameters
field
(string (opens new window) | object (opens new window)) located by label|name|CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# seeCookie
Checks that cookie with given name exists.
I.seeCookie('Auth');
# Parameters
name
string (opens new window) cookie name.
Returns void automatically synchronized promise through #recorder
# seeCssPropertiesOnElements
Checks that all elements with given locator have given CSS properties.
I.seeCssPropertiesOnElements('h3', { 'font-weight': "bold"});
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.cssProperties
object (opens new window) object with CSS properties and their values to check.
Returns void automatically synchronized promise through #recorder
# seeCurrentUrlEquals
Checks that current url is equal to provided one. If a relative url provided, a configured url will be prepended to it. So both examples will work:
I.seeCurrentUrlEquals('/register');
I.seeCurrentUrlEquals('http://my.site.com/register');
# Parameters
url
string (opens new window) value to check.
Returns void automatically synchronized promise through #recorder
# seeElement
Checks that a given Element is visible Element is located by CSS or XPath.
I.seeElement('#modal');
# Parameters
locator
(string (opens new window) | object (opens new window)) located by CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# seeElementInDOM
Checks that a given Element is present in the DOM Element is located by CSS or XPath.
I.seeElementInDOM('#modal');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# seeInCurrentUrl
Checks that current url contains a provided fragment.
I.seeInCurrentUrl('/register'); // we are on registration page
# Parameters
url
string (opens new window) a fragment to check
Returns void automatically synchronized promise through #recorder
# seeInField
Checks that the given input field or textarea equals to given value. For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
I.seeInField('Username', 'davert');
I.seeInField({css: 'form textarea'},'Type your comment here');
I.seeInField('form input[type=hidden]','hidden_value');
I.seeInField('#searchform input','Search');
# Parameters
field
(string (opens new window) | object (opens new window)) located by label|name|CSS|XPath|strict locator.value
(string (opens new window) | object (opens new window)) value to check.
Returns void automatically synchronized promise through #recorder
# seeInPopup
Checks that the active JavaScript popup, as created by window.alert|window.confirm|window.prompt
, contains the
given string.
I.seeInPopup('Popup text');
# Parameters
text
string (opens new window) value to check.
Returns void automatically synchronized promise through #recorder
# seeInSource
Checks that the current page contains the given string in its raw source code.
I.seeInSource('<h1>Green eggs & ham</h1>');
# Parameters
text
string (opens new window) value to check.
Returns void automatically synchronized promise through #recorder
# seeInTitle
Checks that title contains text.
I.seeInTitle('Home Page');
# Parameters
text
string (opens new window) text value to check.
Returns void automatically synchronized promise through #recorder
# seeNumberOfElements
Asserts that an element appears a given number of times in the DOM. Element is located by label or name or CSS or XPath.
I.seeNumberOfElements('#submitBtn', 1);
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.num
number (opens new window) number of elements.
Returns void automatically synchronized promise through #recorder
# seeNumberOfVisibleElements
Asserts that an element is visible a given number of times. Element is located by CSS or XPath.
I.seeNumberOfVisibleElements('.buttons', 3);
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.num
number (opens new window) number of elements.
Returns void automatically synchronized promise through #recorder
# seeTextEquals
Checks that text is equal to provided one.
I.seeTextEquals('text', 'h1');
# Parameters
text
string (opens new window) element value to check.context
(string (opens new window) | object (opens new window))? element located by CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# seeTitleEquals
Checks that title is equal to provided one.
I.seeTitleEquals('Test title.');
# Parameters
text
string (opens new window) value to check.
Returns void automatically synchronized promise through #recorder
# seeTraffic
Verifies that a certain request is part of network traffic.
// checking the request url contains certain query strings
I.amOnPage('https://openai.com/blog/chatgpt');
I.startRecordingTraffic();
await I.seeTraffic({
name: 'sentry event',
url: 'https://images.openai.com/blob/cf717bdb-0c8c-428a-b82b-3c3add87a600',
parameters: {
width: '1919',
height: '1138',
},
});
// checking the request url contains certain post data
I.amOnPage('https://openai.com/blog/chatgpt');
I.startRecordingTraffic();
await I.seeTraffic({
name: 'event',
url: 'https://cloudflareinsights.com/cdn-cgi/rum',
requestPostData: {
st: 2,
},
});
# Parameters
opts
Object (opens new window) options when checking the traffic network.opts.name
string (opens new window) A name of that request. Can be any value. Only relevant to have a more meaningful error message in case of fail.opts.url
string (opens new window) Expected URL of request in network trafficopts.parameters
Object (opens new window)? Expected parameters of that request in network trafficopts.requestPostData
Object (opens new window)? Expected that request contains post data in network trafficopts.timeout
number (opens new window)? Timeout to wait for request in seconds. Default is 10 seconds.
Returns void automatically synchronized promise through #recorder
# selectOption
Selects an option in a drop-down select. Field is searched by label | name | CSS | XPath. Option is selected by visible text or by value.
I.selectOption('Choose Plan', 'Monthly'); // select by label
I.selectOption('subscription', 'Monthly'); // match option by text
I.selectOption('subscription', '0'); // or by value
I.selectOption('//form/select[@name=account]','Premium');
I.selectOption('form select[name=account]', 'Premium');
I.selectOption({css: 'form select[name=account]'}, 'Premium');
Provide an array for the second argument to select multiple options.
I.selectOption('Which OS do you use?', ['Android', 'iOS']);
# Parameters
select
(string (opens new window) | object (opens new window)) field located by label|name|CSS|XPath|strict locator.option
(string (opens new window) | Array (opens new window)) visible text or value of option.
Returns void automatically synchronized promise through #recorder
# setCookie
Sets cookie(s).
Can be a single cookie object or an array of cookies:
I.setCookie({name: 'auth', value: true});
// as array
I.setCookie([
{name: 'auth', value: true},
{name: 'agree', value: true}
]);
# Parameters
cookie
(Cookie | Array (opens new window)) a cookie object or array of cookie objects.
Returns void automatically synchronized promise through #recorder
# setPlaywrightRequestHeaders
Set headers for all next requests
I.setPlaywrightRequestHeaders({
'X-Sent-By': 'CodeceptJS',
});
# Parameters
customHeaders
object (opens new window) headers to set
# startRecordingTraffic
Starts recording the network traffics. This also resets recorded network requests.
I.startRecordingTraffic();
Returns void automatically synchronized promise through #recorder
# startRecordingWebSocketMessages
Starts recording of websocket messages. This also resets recorded websocket messages.
await I.startRecordingWebSocketMessages();
Returns void automatically synchronized promise through #recorder
# stopMockingRoute
Stops network mocking created by mockRoute
.
I.stopMockingRoute(/(.png$)|(.jpg$)/);
I.stopMockingRoute(/(.png$)|(.jpg$)/, previouslySetHandler);
If no handler is passed, all mock requests for the rote are disabled.
# Parameters
url
(string (opens new window) | RegExp (opens new window))? URL, regex or pattern for to match URLhandler
function (opens new window)? a function to process request
# stopRecordingTraffic
Stops recording of network traffic. Recorded traffic is not flashed.
I.stopRecordingTraffic();
# stopRecordingWebSocketMessages
Stops recording WS messages. Recorded WS messages is not flashed.
await I.stopRecordingWebSocketMessages();
Returns void automatically synchronized promise through #recorder
# switchTo
Switches frame or in case of null locator reverts to parent.
I.switchTo('iframe'); // switch to first iframe
I.switchTo(); // switch back to main page
# Parameters
locator
(string (opens new window)? | object (opens new window)) (optional,null
by default) element located by CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# switchToNextTab
Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
I.switchToNextTab();
I.switchToNextTab(2);
# Parameters
# switchToPreviousTab
Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
I.switchToPreviousTab();
I.switchToPreviousTab(2);
# Parameters
# type
Types out the given text into an active field.
To slow down typing use a second parameter, to set interval between key presses.
Note: Should be used when fillField
is not an option.
// passing in a string
I.type('Type this out.');
// typing values with a 100ms interval
I.type('4141555311111111', 100);
// passing in an array
I.type(['T', 'E', 'X', 'T']);
// passing a secret
I.type(secret('123456'));
# Parameters
keys
delay
number (opens new window)? (optional) delay in ms between key presseskey
(string (opens new window) | Array (opens new window)<string (opens new window)>) or array of keys to type.
Returns void automatically synchronized promise through #recorder
# uncheckOption
Additional options (opens new window) for uncheck available as 3rd argument.
Examples:
// click on element at position
I.uncheckOption('Agree', '.signup', { position: { x: 5, y: 5 } })
β οΈ To avoid flakiness, option
force: true
is set by default
Unselects a checkbox or radio button. Element is located by label or name or CSS or XPath.
The second parameter is a context (CSS or XPath locator) to narrow the search.
I.uncheckOption('#agree');
I.uncheckOption('I Agree to Terms and Conditions');
I.uncheckOption('agree', '//form');
# Parameters
field
(string (opens new window) | object (opens new window)) checkbox located by label | name | CSS | XPath | strict locator.context
(string (opens new window)? | object (opens new window)) (optional,null
by default) element located by CSS | XPath | strict locator.options
Returns void automatically synchronized promise through #recorder
# usePlaywrightTo
Use Playwright API inside a test.
First argument is a description of an action. Second argument is async function that gets this helper as parameter.
{ page
(opens new window), browserContext
(opens new window) browser
(opens new window) } objects from Playwright API are available.
I.usePlaywrightTo('emulate offline mode', async ({ browserContext }) => {
await browserContext.setOffline(true);
});
# Parameters
description
string (opens new window) used to show in logs.fn
function (opens new window) async function that executed with Playwright helper as arguments
# wait
Pauses execution for a number of seconds.
I.wait(2); // wait 2 secs
# Parameters
sec
number (opens new window) number of second to wait.
Returns void automatically synchronized promise through #recorder
# waitForClickable
Waits for element to be clickable (by default waits for 1sec). Element can be located by CSS or XPath.
I.waitForClickable('.btn.continue');
I.waitForClickable('.btn.continue', 5); // wait for 5 secs
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.waitTimeout
sec
number (opens new window)? (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitForCookie
Waits for the specified cookie in the cookies.
I.waitForCookie("token");
# Parameters
name
string (opens new window) expected cookie name.sec
number (opens new window) (optional,3
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitForDetached
Waits for an element to become not attached to the DOM on a page (by default waits for 1sec). Element can be located by CSS or XPath.
I.waitForDetached('#popup');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitForDisabled
Waits for element to become disabled (by default waits for 1sec). Element can be located by CSS or XPath.
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.sec
number (opens new window) (optional) time in seconds to wait, 1 by default.
Returns void automatically synchronized promise through #recorder
# waitForElement
Waits for element to be present on page (by default waits for 1sec). Element can be located by CSS or XPath.
I.waitForElement('.btn.continue');
I.waitForElement('.btn.continue', 5); // wait for 5 secs
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.sec
number (opens new window)? (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitForEnabled
Waits for element to become enabled (by default waits for 1sec). Element can be located by CSS or XPath.
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.sec
number (opens new window) (optional) time in seconds to wait, 1 by default.
Returns void automatically synchronized promise through #recorder
# waitForFunction
Waits for a function to return true (waits for 1 sec by default). Running in browser context.
I.waitForFunction(fn[, [args[, timeout]])
I.waitForFunction(() => window.requests == 0);
I.waitForFunction(() => window.requests == 0, 5); // waits for 5 sec
I.waitForFunction((count) => window.requests == count, [3], 5) // pass args and wait for 5 sec
# Parameters
fn
(string (opens new window) | function (opens new window)) to be executed in browser context.argsOrSec
(Array (opens new window)| number (opens new window))? (optional,1
by default) arguments for function or seconds.sec
number (opens new window)? (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitForInvisible
Waits for an element to be removed or become invisible on a page (by default waits for 1sec). Element can be located by CSS or XPath.
I.waitForInvisible('#popup');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitForNavigation
Waits for navigation to finish. By default, it takes configured waitForNavigation
option.
See Playwright's reference (opens new window)
# Parameters
options
any
# waitForNumberOfTabs
Waits for number of tabs.
I.waitForNumberOfTabs(2);
# Parameters
expectedTabs
number (opens new window) expecting the number of tabs.sec
number (opens new window) number of secs to wait.
Returns void automatically synchronized promise through #recorder
# waitForRequest
Waits for a network request.
I.waitForRequest('http://example.com/resource');
I.waitForRequest(request => request.url() === 'http://example.com' && request.method() === 'GET');
# Parameters
urlOrPredicate
(string (opens new window) | function (opens new window))sec
number (opens new window)? seconds to wait
# waitForResponse
Waits for a network response.
I.waitForResponse('http://example.com/resource');
I.waitForResponse(response => response.url() === 'https://example.com' && response.status() === 200);
# Parameters
urlOrPredicate
(string (opens new window) | function (opens new window))sec
number (opens new window)? number of seconds to wait
# waitForText
Waits for a text to appear (by default waits for 1sec). Element can be located by CSS or XPath. Narrow down search results by providing context.
I.waitForText('Thank you, form has been submitted');
I.waitForText('Thank you, form has been submitted', 5, '#modal');
# Parameters
text
string (opens new window) to wait for.sec
number (opens new window) (optional,1
by default) time in seconds to waitcontext
(string (opens new window) | object (opens new window))? (optional) element located by CSS|XPath|strict locator.
Returns void automatically synchronized promise through #recorder
# waitForURL
Waits for page navigates to a new URL or reloads. By default, it takes configured waitForNavigation
option.
See Playwright's reference (opens new window)
# Parameters
url
(string (opens new window) | RegExp (opens new window)) A glob pattern, regex pattern or predicate receiving URL to match while waiting for the navigation. Note that if the parameter is a string without wildcard characters, the method will wait for navigation to URL that is exactly equal to the string.options
any
# waitForValue
Waits for the specified value to be in value attribute.
I.waitForValue('//input', "GoodValue");
# Parameters
field
(string (opens new window) | object (opens new window)) input field.value
string (opens new window) expected value.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitForVisible
This method accepts React selectors (opens new window).
Waits for an element to become visible on a page (by default waits for 1sec). Element can be located by CSS or XPath.
I.waitForVisible('#popup');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitInUrl
Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
I.waitInUrl('/info', 2);
# Parameters
urlPart
string (opens new window) value to check.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitNumberOfVisibleElements
Waits for a specified number of elements on the page.
I.waitNumberOfVisibleElements('a', 3);
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.num
number (opens new window) number of elements.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitToHide
Waits for an element to hide (by default waits for 1sec). Element can be located by CSS or XPath.
I.waitToHide('#popup');
# Parameters
locator
(string (opens new window) | object (opens new window)) element located by CSS|XPath|strict locator.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder
# waitUrlEquals
Waits for the entire URL to match the expected
I.waitUrlEquals('/info', 2);
I.waitUrlEquals('http://127.0.0.1:8000/info');
# Parameters
urlPart
string (opens new window) value to check.sec
number (opens new window) (optional,1
by default) time in seconds to wait
Returns void automatically synchronized promise through #recorder