puppeteer/test
Josh Bielick 6d6ea9bf59
fix: always use ENV executable path when present (#7985)
Some recent changes to allow arm64 environments (including M1 macs) to
launch a chromium installation successfully before arm-compatible builds
were downloadable prevented the usage of PUPPETEER_EXECUTABLE_PATH in
some environments. Currently, when the platform is not darwin and the
arch is arm64, an executable cannot be specified using the environment
variable.

Generally speaking, environment variables have highest precedence for
options such as this since they depend on system configuration.

These change:

1. allow the ENV variable to always be used when defined and not
   specified in LaunchOptions (and when not puppeteer-core)
2. Retain the existing behavior of assuming /usr/bin/chromium-browser on
   platforms like Ubuntu (exact if-conditions preserved to avoid any
   breaking changes)
3. Add some tests for this particular portion of the code.
2022-02-11 13:07:31 +00:00
..
assets feat(oop iframes)!: integrate OOP iframes with the frame manager (#7556) 2021-10-28 11:25:49 +02:00
fixtures chore: add Prettier (#5825) 2020-05-07 12:54:55 +02:00
golden-chromium feat(chromium): roll to Chromium 98.0.4758.0 (r950341) (#7907) 2022-01-17 13:40:38 +00:00
golden-firefox feat: use captureBeyondViewport in Page.captureScreenshot (#6805) 2021-02-03 14:30:46 +01:00
.eslintrc.js chore: enforce file extensions on imports (#6202) 2020-07-13 10:22:26 +01:00
accessibility.spec.ts feat(chromium): roll to Chromium 98.0.4758.0 (r950341) (#7907) 2022-01-17 13:40:38 +00:00
ariaqueryhandler.spec.ts feat(chromium): roll to Chromium 99.0.4844.16 (r961656) (#7960) 2022-02-04 12:18:53 +01:00
assert-coverage-test.js chore(deps): update deps 2022-02-09 14:49:25 +00:00
browser.spec.ts chore: enforce file extensions on imports (#6202) 2020-07-13 10:22:26 +01:00
browsercontext.spec.ts chore: update test expectations per Mozilla’s sync-up with v5.5.0 (#6650) 2020-12-07 08:18:32 +01:00
CDPSession.spec.ts feat(chromium): roll to Chromium 92.0.4512.0 (r884014) (#7288) 2021-05-26 16:44:29 +00:00
chromiumonly.spec.ts chore(agnostification): split up launcher class (#6484) 2020-10-12 10:08:57 +01:00
click.spec.ts chore: re-enable tests for Firefox related to fixed Input.dispatchMouseEvent issues (#7776) 2021-11-19 08:50:31 +01:00
cookies.spec.ts chore: fix eslint warnings around type defs (#7230) 2021-05-12 17:43:05 +01:00
coverage-utils.js chore(agnostification): split up root Puppeteer class (#6504) 2020-10-13 16:19:26 +01:00
coverage.spec.ts feat(coverage): option for raw V8 script coverage (#6454) 2021-09-15 18:54:24 +00:00
defaultbrowsercontext.spec.ts chore: skip non-standard cookie asserts on Firefox (#6994) 2021-03-17 16:09:10 +00:00
dialog.spec.ts chore: enforce file extensions on imports (#6202) 2020-07-13 10:22:26 +01:00
diffstyle.css Implement FrameManager 2017-06-21 14:11:52 -07:00
drag-and-drop.spec.ts feat(api): make page.isDragInterceptionEnabled a method (#7419) 2021-07-13 11:37:39 +02:00
elementhandle.spec.ts feat: implement Element.waitForSelector (#7825) 2021-12-09 11:51:14 +00:00
emulation.spec.ts feat: add page.emulateCPUThrottling (#7343) 2021-06-22 11:43:11 +00:00
evaluation.spec.ts fix: jsonValue() type is generic (#6865) 2021-02-11 09:50:15 +00:00
EventEmitter.spec.ts chore: vendor Mitt & update project structure (#6209) 2020-07-14 16:57:29 +01:00
fixtures.spec.ts chore: enforce file extensions on imports (#6202) 2020-07-13 10:22:26 +01:00
frame.spec.ts feat: handle unhandled promise rejections in tests (#7722) 2021-10-27 13:43:57 +02:00
golden-utils.js chore: migrate tests to TypeScript (#6075) 2020-06-23 07:18:46 +02:00
headful.spec.ts chore: add hared TaskQueue for page.screenshot() again (#6714) 2021-09-23 14:37:35 +02:00
idle_override.spec.ts feat(chromium) roll Chromium to r809590 (#6458) 2020-10-01 08:24:47 +02:00
ignorehttpserrors.spec.ts chore: enforce file extensions on imports (#6202) 2020-07-13 10:22:26 +01:00
input.spec.ts fix(filechooser): cancel is sync (#6937) 2021-03-02 15:27:11 +01:00
jshandle.spec.ts feat(chromium)!: roll to Chromium 97.0.4692.0 (r938248) 2021-11-23 08:19:14 +01:00
keyboard.spec.ts chore: run unit tests for Firefox on MacOS (#6896) 2021-02-18 13:44:36 +01:00
launcher.spec.ts fix: always use ENV executable path when present (#7985) 2022-02-11 13:07:31 +00:00
mocha-ts-require.js chore: vendor Mitt & update project structure (#6209) 2020-07-14 16:57:29 +01:00
mocha-utils.ts feat(chromium)!: roll to Chromium 97.0.4692.0 (r938248) 2021-11-23 08:19:14 +01:00
mouse.spec.ts chore: re-enable tests for Firefox related to fixed Input.dispatchMouseEvent issues (#7776) 2021-11-19 08:50:31 +01:00
navigation.spec.ts chore: upgrade TypeScript to 4.1.5 (#6889) 2021-02-16 10:43:32 +00:00
network.spec.ts fix: disable a test failing on Firefox (#7846) 2021-12-15 09:17:56 +01:00
NetworkManager.spec.ts fix: handle multiple/duplicate Fetch.requestPaused events (#7802) 2021-12-03 20:13:44 +01:00
oopif.spec.ts fix: apply OOPIF offsets to bounding box and box model calls (#7906) 2022-01-17 14:19:43 +01:00
page.spec.ts fix(page): fix page.off method for request event (#7624) 2021-10-04 06:59:46 +00:00
queryselector.spec.ts chore: mark version v5.4.0 (#6542) 2020-10-23 16:28:38 +02:00
README.md chore: automate prettier in docs (#7014) 2021-03-23 10:02:34 +01:00
requestinterception-experimental.spec.ts fix!: typo in 'already-handled' constant of the request interception API (#7813) 2021-12-09 14:57:40 +00:00
requestinterception.spec.ts feat: handle unhandled promise rejections in tests (#7722) 2021-10-27 13:43:57 +02:00
run_static_server.js chore(deps): update deps 2022-02-09 14:49:25 +00:00
screenshot.spec.ts feat: add webp to screenshot options (#7565) 2021-09-21 14:26:20 +00:00
target.spec.ts test: fix Browser.pages should return all of the pages (#7064) 2021-04-07 09:11:43 +02:00
touchscreen.spec.ts chore: enforce file extensions on imports (#6202) 2020-07-13 10:22:26 +01:00
tracing.spec.ts chore: remove unused tracing category for cpu profiling (#5866) 2021-09-15 11:59:38 +02:00
tsconfig.json chore: migrate tests to TypeScript (#6075) 2020-06-23 07:18:46 +02:00
tsconfig.test.json chore(agnostic): Remove use of util.promisify (#6446) 2020-09-28 10:35:35 +01:00
utils.js chore(deps): update deps 2022-02-09 14:49:25 +00:00
waittask.spec.ts fix: predicate arguments for waitForFunction (#7845) 2021-12-15 08:40:56 +00:00
worker.spec.ts feat(chromium): roll Chromium to r843427 (#6797) 2021-02-02 08:40:56 +01:00

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 ran require('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 (see utils/testserver for more).
  • httpsServer: a dummy test server HTTPS instance (see utils/testserver for 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 unit
  • Important: don't forget to first run TypeScript if you're testing local changes:
npm run tsc && npm run unit
  • To run a specific test, substitute the it with it.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 it with xit (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 unit
  • To run tests with custom browser executable:
BINARY=<path-to-executable> npm run unit