From 0d14c1aa3ccb2f84bc5033546ecbcfdc89b11194 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Wed, 8 Apr 2020 16:25:36 +0100 Subject: [PATCH] Docs update about test helpers --- test/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/test/README.md b/test/README.md index 38e8dd253cf79..f69d4fe02abf2 100644 --- a/test/README.md +++ b/test/README.md @@ -4,18 +4,12 @@ Unit tests in Puppeteer are written using [Mocha] as the test runner and [Expect ## Test state -We have some common setup that runs before each test and is defined in `mocha-utils.js`. This code creates a Puppeteer browser that can be used by tests. It also creates a `context` and `page` that are reset between each test and can be used to save the boilerplate of creating one every single time. -If you are in an `it` and want to use the provided state, you can call `getTestState` from `mocha-utils.js` to access them: +We have some common setup that runs before each test and is defined in `mocha-utils.js`. -```js -const { page } = getTestState(); -``` - -`getTestState` exposes the following that you can use in your tests. These will be reset/tidied between tests automatically for you: +You can use the `getTestState` function to read state. It exposes the following that you can use in your tests. These will be reset/tidied between tests automatically for you: * `puppeteer`: an instance of the Puppeteer library. This is exactly what you'd get if you ran `require('puppeteer')`. -* `browser`: a launched Puppeteer browser. Note that this persists for the entire test suite, rather than re-launch this on each test. * `puppeteerPath`: the path to the root source file for Puppeteer. * `defaultBrowserOptions`: the default options the Puppeteer browser is launched from in test mode, so tests can use them and override if required. * `server`: a dummy test server instance (see `utils/testserver` for more). @@ -24,6 +18,12 @@ const { page } = getTestState(); * `isChrome`: true if running Chromium. * `isHeadless`: true if the test is in headless mode. +If your test needs a browser instance, you can use the `setupTestBrowserHooks()` function which will automatically configure a browser that will be cleaned between each test suite run. You access this via `getTestState()`. + +If your test needs a Puppeteer page and context, you can use the `setupTestPageAndContextHooks()` function which will configure these. You can access `page` and `context` from `getTestState()` once you have done this. + +The best place to look is an existing test to see how they use the helpers. + ## Skipping tests for Firefox Tests that are not expected to pass in Firefox can be skipped. You can skip an individual test by using `itFailsFirefox` rather than `it`. Similarly you can skip a describe block with `describeFailsFirefox`.