README.md
1# Puppeteer unit tests
2
3Unit tests in Puppeteer are written using [Mocha] as the test runner and [Expect] as the assertions library.
4
5## Test state
6
7We have some common setup that runs before each test and is defined in `mocha-utils.js`.
8
9You 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:
10
11- `puppeteer`: an instance of the Puppeteer library. This is exactly what you'd get if you ran `require('puppeteer')`.
12- `puppeteerPath`: the path to the root source file for Puppeteer.
13- `defaultBrowserOptions`: the default options the Puppeteer browser is launched from in test mode, so tests can use them and override if required.
14- `server`: a dummy test server instance (see `utils/testserver` for more).
15- `httpsServer`: a dummy test server HTTPS instance (see `utils/testserver` for more).
16- `isFirefox`: true if running in Firefox.
17- `isChrome`: true if running Chromium.
18- `isHeadless`: true if the test is in headless mode.
19
20If 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()`.
21
22If 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.
23
24The best place to look is an existing test to see how they use the helpers.
25
26## Skipping tests in specific conditions
27
28Tests 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`.
29
30There is also `describeChromeOnly` and `itChromeOnly` which will only execute the test if running in Chromium. Note that this is different from `describeFailsFirefox`: the goal is to get any `FailsFirefox` calls passing in Firefox, whereas `describeChromeOnly` should be used to test behaviour that will only ever apply in Chromium.
31
32There are also tests that assume a normal install flow, with browser binaries ending up in `.local-<browser>`, for example. Such tests are skipped with
33`itOnlyRegularInstall` which checks `BINARY` and `PUPPETEER_ALT_INSTALL` environment variables.
34
35[mocha]: https://mochajs.org/
36[expect]: https://www.npmjs.com/package/expect
37
38## Running tests
39
40Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.
41
42- To run all tests:
43
44```bash
45npm run unit
46```
47
48- **Important**: don't forget to first run TypeScript if you're testing local changes:
49
50```bash
51npm run tsc && npm run unit
52```
53
54- To run a specific test, substitute the `it` with `it.only`:
55
56```js
57 ...
58 it.only('should work', async function() {
59 const {server, page} = getTestState();
60 const response = await page.goto(server.EMPTY_PAGE);
61 expect(response.ok).toBe(true);
62 });
63```
64
65- To disable a specific test, substitute the `it` with `xit` (mnemonic rule: '_cross it_'):
66
67```js
68 ...
69 // Using "xit" to skip specific test
70 xit('should work', async function({server, page}) {
71 const {server, page} = getTestState();
72 const response = await page.goto(server.EMPTY_PAGE);
73 expect(response.ok).toBe(true);
74 });
75```
76
77- To run tests in non-headless mode:
78
79```bash
80HEADLESS=false npm run unit
81```
82
83- To run tests with custom browser executable:
84
85```bash
86BINARY=<path-to-executable> npm run unit
87```
88