From 488dbda86e9df9fe46e566c249bb763cec6ce44c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Greg=20Berg=C3=A9?= Date: Wed, 8 Mar 2023 13:24:59 +0100 Subject: [PATCH] docs: update config doc Closes #444 --- README.md | 118 +++++++++++++----- packages/jest-environment-puppeteer/README.md | 24 ++-- 2 files changed, 107 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index d60e632e..1b04f873 100644 --- a/README.md +++ b/README.md @@ -105,10 +105,12 @@ await jestPuppeteer.debug(); Jest Puppeteer integrates a functionality to start a server when running your test suite. It automatically closes the server when tests are done. -To use it, specify a server section in your `jest-puppeteer.config.js`. +To use it, specify a server section in your `jest-puppeteer.config.cjs`. ```js -// jest-puppeteer.config.js +// jest-puppeteer.config.cjs + +/** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */ module.exports = { server: { command: "node server.js", @@ -121,7 +123,7 @@ Other options are documented in [jest-dev-server](https://github.com/smooth-code ### Configure Puppeteer -Jest Puppeteer automatically detects the best config to start Puppeteer but sometimes you may need to specify custom options. All Puppeteer [launch](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions) or [connect](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerconnectoptions) options can be specified in `jest-puppeteer.config.js` at the root of the project. Since it is JavaScript, you can use all the stuff you need, including environment. +Jest Puppeteer automatically detects the best config to start Puppeteer but sometimes you may need to specify custom options. To run Puppeteer on Firefox, you can set the `launch.product` property to `firefox`. By default, the value is `chrome` which will use Puppeteer on Chromium. @@ -130,7 +132,9 @@ The browser context can be also specified. By default, the browser context is sh Default config values: ```js -// jest-puppeteer.config.js +// jest-puppeteer.config.cjs + +/** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */ module.exports = { launch: { dumpio: true, @@ -332,7 +336,7 @@ it("should fill an input", async () => { ### `global.context` -Give access to a [browser context](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-browsercontext) that is instantiated when the browser is launched. You can control whether each test has its own isolated browser context using the `browserContext` option in your `jest-puppeteer.config.js`. +Give access to a [browser context](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-browsercontext) that is instantiated when the browser is launched. You can control whether each test has its own isolated browser context using the `browserContext` option in your config file. ### `global.expect(page)` @@ -376,20 +380,67 @@ beforeEach(async () => { }); ``` -### `jest-puppeteer.config.js` - -You can specify a `jest-puppeteer.config.js` at the root of the project or define a custom path using `JEST_PUPPETEER_CONFIG` environment variable. - -- `launch` <[object]> [All Puppeteer launch options](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.puppeteerlaunchoptions.md) can be specified in config. Since it is JavaScript, you can use all stuff you need, including environment. -- `connect` <[object]> [All Puppeteer connect options](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.connectoptions.md) can be specified in config. This is an alternative to `launch` config, allowing you to connect to an already running instance of Chrome. -- `server` <[Object]> Server options allowed by [jest-dev-server](https://github.com/smooth-code/jest-puppeteer/tree/master/packages/jest-dev-server) -- `browserPerWorker` <[Boolean]> Allows to run tests for each [jest worker](https://jestjs.io/docs/cli#--maxworkersnumstring) in an individual browser. -- `exitOnPageError` <[boolean]> Exits page on any global error message thrown. Defaults to true. +### Config + +Jest Puppeteer uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for configuration file support. This means you can configure Jest Puppeteer via (in order of precedence): + +- A `"jest-puppeteer"` key in your `package.json` file. +- A `.jest-puppeteerrc` file written in JSON or YAML. +- A `.jest-puppeteerrc.json`, `.jest-puppeteerrc.yml`, `.jest-puppeteerrc.yaml`, or `.jest-puppeteerrc.json5` file. +- A `.jest-puppeteerrc.js`, `.jest-puppeteerrc.cjs`, `jest-puppeteer.config.js`, or `jest-puppeteer.config.cjs` file that exports an object using `module.exports`. +- A `.jest-puppeteerrc.toml` file. + +By default it looks for config at the root of the project. You can define a custom path using `JEST_PUPPETEER_CONFIG` environment variable. + +It should export a config object or a Promise that returns a config object. + +```ts +interface JestPuppeteerConfig { + /** + * Puppeteer connect options. + * @see https://pptr.dev/api/puppeteer.connectoptions + */ + connect?: ConnectOptions; + /** + * Puppeteer launch options. + * @see https://pptr.dev/api/puppeteer.launchoptions + */ + launch?: PuppeteerLaunchOptions; + /** + * Server config for `jest-dev-server`. + * @see https://www.npmjs.com/package/jest-dev-server + */ + server?: JestDevServerConfig | JestDevServerConfig[]; + /** + * Allow to run one browser per worker. + * @default false + */ + browserPerWorker?: boolean; + /** + * Browser context to use. + * @default "default" + */ + browserContext?: "default" | "incognito"; + /** + * Exit on page error. + * @default true + */ + exitOnPageError?: boolean; + /** + * Use `runBeforeUnload` in `page.close`. + * @see https://pptr.dev/api/puppeteer.page.close + * @default false + */ + runBeforeUnloadOnClose?: boolean; +} +``` -#### Example 1 +#### Sync config ```js -// jest-puppeteer.config.js +// jest-puppeteer.config.cjs + +/** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */ module.exports = { launch: { dumpio: true, @@ -398,27 +449,38 @@ module.exports = { server: { command: "node server.js", port: 4444, + launchTimeout: 10000, + debug: true, }, }; ``` -#### Example 2 +#### Async config This example uses an already running instance of Chrome by passing the active web socket endpoint to `connect`. This is useful, for example, when you want to connect to Chrome running in the cloud. ```js -// jest-puppeteer.config.js -const wsEndpoint = fs.readFileSync(endpointPath, "utf8"); +// jest-puppeteer.config.cjs +const dockerHost = "http://localhost:9222"; + +async function getConfig() { + const data = await fetch(`${dockerHost}/json/version`).json(); + const browserWSEndpoint = data.webSocketDebuggerUrl; + /** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */ + return { + connect: { + browserWSEndpoint, + }, + server: { + command: "node server.js", + port: 3000, + launchTimeout: 10000, + debug: true, + }, + }; +} -module.exports = { - connect: { - browserWSEndpoint: wsEndpoint, - }, - server: { - command: "node server.js", - port: 4444, - }, -}; +module.exports = getConfig(); ``` ## Inspiration diff --git a/packages/jest-environment-puppeteer/README.md b/packages/jest-environment-puppeteer/README.md index 2b0d1ac1..69f51d35 100644 --- a/packages/jest-environment-puppeteer/README.md +++ b/packages/jest-environment-puppeteer/README.md @@ -62,7 +62,7 @@ it("should fill an input", async () => { ### `global.context` -Give access to a [browser context](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-browsercontext) that is instantiated when the browser is launched. You can control whether each test has its own isolated browser context using the `browserContext` option in your `jest-puppeteer.config.js`. +Give access to a [browser context](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#class-browsercontext) that is instantiated when the browser is launched. You can control whether each test has its own isolated browser context using the `browserContext` option in config. ### `global.jestPuppeteer.debug()` @@ -97,9 +97,19 @@ beforeEach(async () => { }); ``` -### `jest-puppeteer.config.js` +### Config -You can specify a `jest-puppeteer.config.js` at the root of the project or define a custom path using `JEST_PUPPETEER_CONFIG` environment variable. It should export a config object or a Promise for a config object. +Jest Puppeteer uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) for configuration file support. This means you can configure Jest Puppeteer via (in order of precedence): + +- A `"jest-puppeteer"` key in your `package.json` file. +- A `.jest-puppeteerrc` file written in JSON or YAML. +- A `.jest-puppeteerrc.json`, `.jest-puppeteerrc.yml`, `.jest-puppeteerrc.yaml`, or `.jest-puppeteerrc.json5` file. +- A `.jest-puppeteerrc.js`, `.jest-puppeteerrc.cjs`, `jest-puppeteer.config.js`, or `jest-puppeteer.config.cjs` file that exports an object using `module.exports`. +- A `.jest-puppeteerrc.toml` file. + +By default it looks for config at the root of the project. You can define a custom path using `JEST_PUPPETEER_CONFIG` environment variable. + +It should export a config object or a Promise that returns a config object. ```ts interface JestPuppeteerConfig { @@ -142,10 +152,10 @@ interface JestPuppeteerConfig { } ``` -#### Example 1 +#### Sync config ```js -// jest-puppeteer.config.js +// jest-puppeteer.config.cjs /** @type {import('jest-environment-puppeteer').JestPuppeteerConfig} */ module.exports = { @@ -162,12 +172,12 @@ module.exports = { }; ``` -#### Example 2 +#### Async config This example uses an already running instance of Chrome by passing the active web socket endpoint to `connect`. This is useful, for example, when you want to connect to Chrome running in the cloud. ```js -// jest-puppeteer.config.js +// jest-puppeteer.config.cjs const dockerHost = "http://localhost:9222"; async function getConfig() {