playwright-extra

Extra utility functions for interacting with Playwright.

Installation • Usage • Contributors • License

Installation

1yarn add @devoxa/playwright-extra

Usage

Assertions

1await expectToExist(locator)

Expect the locator to exist exactly once.

1await expectNotToExist(locator)

Expect the locator not to exist.

Clipboard

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

1await getClipboardValue(page)

Get the value of the clipboard.

1await setClipboardValue(page, value)

Set the value of the clipboard.

Accessability

1await 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.

1await jsonLinesAppend(filePath, line)

Append a line to a file in JSON Lines format.

1await jsonLinesParse(filePath)

Parse a file in JSON Lines format.

Local Storage

1await getLocalStorageItem(page, key)

Get the value of a local storage item.

1await setLocalStorageItem(page, key, value)

Set the value of a local storage item.

1await removeLocalStorageItem(page, key)

Remove a local storage item.

Console Messages

1const getConsoleMessages = captureConsoleMessages(page)
2// ... do things here ...
3expect(getConsoleMessages()).toEqual([])
4expect(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.

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

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

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

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

1await expect(page).toHaveURL($endsWith(value))
2
3const dynamicSegments = { id: '[0-9]+' }
4await 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

1const options = { filePath: 'performance-metrics.jsonl' }
2
3await 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

1const options = { timeout: 5000, waitTime: 100 }
2
3await 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

1const options = { timeout: 10000, minIdleTime: 200, debug: false }
2
3const waitForNetworkIdlePromise = waitForNetworkIdle(page, options?)
4// ... do things here ...
5await waitForNetworkIdlePromise

Wait for all network requests to be settled before resolving.

1await gotoAndWaitForNetworkIdle(page, url, options?)

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

1await reloadAndWaitForNetworkIdle(page, url, options?)

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

1WaitForNetworkIdleDefaultOptions.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