playwright-extra

Extra utility functions for interacting with Playwright.

Installation • Usage • Contributors • License

Installation

yarn add @devoxa/playwright-extra

Usage

Assertions

await expectToExist(locator)

Expect the locator to exist exactly once.

await expectNotToExist(locator)

Expect the locator not to exist.

Clipboard

Note: These functions are not thread safe and a potential cause of race conditions.

await getClipboardValue(page)

Get the value of the clipboard.

await setClipboardValue(page, value)

Set the value of the clipboard.

Accessability

await expectZeroAccessibilityViolations(page, config?)

Expect that there are no accessibility violations. This is a wrapper around axe-playwright, and takes the same config as configureAxe. The assertion can be turned off globally by setting process.env.DISABLE_ACCESSIBILITY_TESTS to true.

JSON Lines

Note: You can read more about the JSON Lines format here.

await jsonLinesAppend(filePath, line)

Append a line to a file in JSON Lines format.

await jsonLinesParse(filePath)

Parse a file in JSON Lines format.

Local Storage

await getLocalStorageItem(page, key)

Get the value of a local storage item.

await setLocalStorageItem(page, key, value)

Set the value of a local storage item.

await removeLocalStorageItem(page, key)

Remove a local storage item.

Console Messages

const getConsoleMessages = captureConsoleMessages(page)
// ... do things here ...
expect(getConsoleMessages()).toEqual([])
expect(getConsoleMessages(['warning', 'error'])).toEqual([])

Capture the console messages of the page for later assertions.

Matchers

Note: These functions escape special regular expression characters, so they are safe to use for example for URLs with query strings.

await expect(page).toHaveURL($startsWith(value))

const dynamicSegments = { id: '[0-9]+' }
await expect(page).toHaveURL($startsWith('/:id/edit', dynamicSegments))

Create a RegExp that starts with the value, with optional dynamicSegments replaced with their respective regular expressions.

await expect(page).toHaveURL($contains(value))

const dynamicSegments = { id: '[0-9]+' }
await expect(page).toHaveURL($contains('/:id/edit', dynamicSegments))

Create a RegExp that contains the value, with optional dynamicSegments replaced with their respective regular expressions.

await expect(page).toHaveURL($endsWith(value))

const dynamicSegments = { id: '[0-9]+' }
await expect(page).toHaveURL($endsWith('/:id/edit', dynamicSegments))

Create a RegExp that ends with the value, with optional dynamicSegments replaced with their respective regular expressions.

Performance Metrics

const options = { filePath: 'performance-metrics.jsonl' }

await exportPerformanceMetrics(page, label, options?)

Export the performance metrics of the page to the file path. The output is in JSON Lines format, and includes the label, encodedBodySize, resourceLoadDuration and nextjsHydrationDuration.

• Make sure to call the function right after loading the page to get correct results.
• The performance-metrics.jsonl file has to be manually removed, e.g. before running the tests.
• You can test the resulting export with the yarn test-performance-metrics CLI tool. See --help for the available options.

Retry On Error

const options = { timeout: 5000, waitTime: 100 }

await retryOnError(asyncCallback, options?)

Retry until the callback is successful or the timeout is hit. This is useful for unstable parts of tests, for example when waiting for an email that is sent out by a queue processor.

Wait For Network Idle

const options = { timeout: 10000, minIdleTime: 200, debug: false }

const waitForNetworkIdlePromise = waitForNetworkIdle(page, options?)
// ... do things here ...
await waitForNetworkIdlePromise

Wait for all network requests to be settled before resolving.

await gotoAndWaitForNetworkIdle(page, url, options?)

Go to a page and wait for all network requests to be settled.

await reloadAndWaitForNetworkIdle(page, url, options?)

Reload the page and wait for all network requests to be settled.

WaitForNetworkIdleDefaultOptions.minIdleTime = 500

Set the global default options for all *waitForNetworkIdle functions.

Keep in mind that test files run independently from the setup, so you have to call this in a helper, that is imported into all test files.

Contributors

Thanks goes to these wonderful people (emoji key):

David Reeß 💻 📖 ⚠️

This project follows the all-contributors specification. Contributions of any kind welcome!

License

MIT