26c3acbb07
This PR greatly improves the types within Puppeteer: - **Almost everything** is auto-deduced. - Parameters don't need to be specified in the function. They are deduced from the spread. - Return types don't need to be specified. They are deduced from the function. (More on this below) - Selections based on tag names correctly deduce element type, similar to TypeScript's mechanism for `getElementByTagName`. - [**BREAKING CHANGE**] We've removed the ability to declare return types in type arguments for the following reasons: 1. Setting them will indubitably break auto-deduction. 2. You can just use `as ...` in TypeScript to coerce the correct type (given it makes sense). - [**BREAKING CHANGE**] `waitFor` is officially gone. To migrate to these changes, there are only four things you may need to change: - If you set a return type using the `ReturnType` type parameter, remove it and use `as ...` and `HandleFor` (if necessary). ⛔ `evaluate<ReturnType>(a: number, b: number) => {...}, a, b)` ✅ `(await evaluate(a, b) => {...}, a, b)) as ReturnType` ⛔ `evaluateHandle<ReturnType>(a: number, b: number) => {...}, a, b)` ✅ `(await evaluateHandle(a, b) => {...}, a, b)) as HandleFor<ReturnType>` - If you set any type parameters in the *parameters* of an evaluation function, remove them. ⛔ `evaluate(a: number, b: number) => {...}, a, b)` ✅ `evaluate(a, b) => {...}, a, b)` - If you set any type parameters in the method's declaration, remove them. ⛔ `evaluate<(a: number, b: number) => void>((a, b) => {...}, a, b)` ✅ `evaluate(a, b) => {...}, a, b)` |
||
|---|---|---|
| .. | ||
| assets | ||
| fixtures | ||
| golden-chromium | ||
| golden-firefox | ||
| src | ||
| .eslintrc.js | ||
| README.md | ||
| tsconfig.json | ||
Puppeteer unit tests
Unit tests in Puppeteer are written using Mocha as the test runner and Expect as the assertions library.
Test state
We have some common setup that runs before each test and is defined in mocha-utils.js.
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 ranrequire('puppeteer').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 (seeutils/testserverfor more).httpsServer: a dummy test server HTTPS instance (seeutils/testserverfor more).isFirefox: true if running in Firefox.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 in specific conditions
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.
There 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.
There are also tests that assume a normal install flow, with browser binaries ending up in .local-<browser>, for example. Such tests are skipped with
itOnlyRegularInstall which checks BINARY and PUPPETEER_ALT_INSTALL environment variables.
Running tests
Despite being named 'unit', these are integration tests, making sure public API methods and events work as expected.
- To run all tests:
npm run test:unit
- Important: don't forget to first run TypeScript if you're testing local changes:
npm run build:tsc && npm run test:unit
- To run a specific test, substitute the
itwithit.only:
...
it.only('should work', async function() {
const {server, page} = getTestState();
const response = await page.goto(server.EMPTY_PAGE);
expect(response.ok).toBe(true);
});
- To disable a specific test, substitute the
itwithxit(mnemonic rule: 'cross it'):
...
// Using "xit" to skip specific test
xit('should work', async function({server, page}) {
const {server, page} = getTestState();
const response = await page.goto(server.EMPTY_PAGE);
expect(response.ok).toBe(true);
});
- To run tests in non-headless mode:
HEADLESS=false npm run test:unit
- To run tests with custom browser executable:
BINARY=<path-to-executable> npm run test:unit