feat: connect to an already existing instance of Chrome (#100)

README.md

@@ -99,7 +99,7 @@ Other options are documented in [jest-dev-server](https://github.com/smooth-code
 
 ### Configure Puppeteer
 
-Jest Puppeteer automatically detect the best config to start Puppeteer but sometimes you may need to specify custom options. [All Puppeteer launch options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions) can be specified in `jest-puppeteer.config.js` at the root of the project. Since it is JavaScript, you can use all stuff you need, including environment.
+Jest Puppeteer automatically detect 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 stuff you need, including environment.
 
 ```js
 // jest-puppeteer.config.js
@@ -257,8 +257,11 @@ it('should put test in debug mode', async () => {
 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/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions) 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/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerconnectoptions) 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)
 
+#### Example 1
+
 ```js
 // jest-puppeteer.config.js
 module.exports = {
@@ -273,6 +276,25 @@ module.exports = {
 }
 ```
 
+#### Example 2
+
+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')
+
+module.exports = {
+  connect: {
+    browserWSEndpoint: wsEndpoint,
+  },
+  server: {
+    command: 'node server.js',
+    port: 4444,
+  },
+}
+```
+
 ## Inspiration
 
 Thanks to Fumihiro Xue for his great [Jest example](https://github.com/xfumihiro/jest-puppeteer-example).

packages/expect-puppeteer/src/options.js

@@ -7,8 +7,10 @@ export const setDefaultOptions = options => {
 export const getDefaultOptions = () => {
   if (
     global.puppeteerConfig &&
-    global.puppeteerConfig.launch &&
-    global.puppeteerConfig.launch.slowMo &&
+    (
+      (global.puppeteerConfig.launch && global.puppeteerConfig.launch.slowMo) || 
+      (global.puppeteerConfig.connect && global.puppeteerConfig.connect.slowMo)
+    ) &&
     defaultOptionsValue &&
     defaultOptionsValue.timeout
   ) {

packages/jest-environment-puppeteer/README.md

@@ -78,9 +78,12 @@ it('should put test in debug mode', async () => {
 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/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions) 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/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerconnectoptions) can be specified in config. This is an alternative to `launch` config, allowing you to connect to an already running instance of Chrome.
 - `exitOnPageError` <[boolean]> Exits page on any global error message thrown. Defaults to `true`.
 - `server` <[Object]> Server options allowed by [jest-dev-server](https://github.com/smooth-code/jest-puppeteer/tree/master/packages/jest-dev-server)
 
+#### Example 1
+
 ```js
 // jest-puppeteer.config.js
 module.exports = {
@@ -97,6 +100,27 @@ module.exports = {
 }
 ```
 
+#### Example 2
+
+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')
+
+module.exports = {
+  connect: {
+    browserWSEndpoint: wsEndpoint,
+  },
+  server: {
+    command: 'node server.js',
+    port: 4444,
+    launchTimeout: 10000,
+    debug: true,
+  },
+}
+```
+
 ## Inspiration
 
 Thanks to Fumihiro Xue for his great [Jest example](https://github.com/xfumihiro/jest-puppeteer-example).

packages/jest-environment-puppeteer/src/PuppeteerEnvironment.js

@@ -37,8 +37,9 @@ class PuppeteerEnvironment extends NodeEnvironment {
       throw new Error('wsEndpoint not found')
     }
     this.global.browser = await puppeteer.connect({
+      ...config.connect,
       ...config.launch,
-      browserWSEndpoint: wsEndpoint,
+      browserWSEndpoint: wsEndpoint
     })
     this.global.page = await this.global.browser.newPage()
     if (config && config.exitOnPageError) {

packages/jest-environment-puppeteer/src/global.js

@@ -17,7 +17,11 @@ let browser
 
 export async function setup() {
   const config = await readConfig()
-  browser = await puppeteer.launch(config.launch)
+  if (config.connect) {
+    browser = await puppeteer.connect(config.connect)
+  } else {
+    browser = await puppeteer.launch(config.launch)
+  }
   mkdirp.sync(DIR)
   fs.writeFileSync(WS_ENDPOINT_PATH, browser.wsEndpoint())