feat: add debug mode

.eslintrc.js

@@ -14,7 +14,7 @@ module.exports = {
  globals: {
  page: true,
  browser: true,
- expectPage: true,
+ jestPuppeteer: true,
  },
  rules: {
  'class-methods-use-this': 'off',

README.md

@@ -71,6 +71,14 @@ await expect(page).toFillForm('form[name="myForm"]', {
 })
 ```
 
+### Put in debug mode
+
+Debugging tests can be hard sometimes and it is very useful to be able to pause tests in order to inspect the browser. Jest Puppeteer exposes a method `jestPuppeteer.debug()` that suspends test execution and gives you opportunity to see what's going on in the browser.
+
+```js
+await jestPuppeteer.debug()
+```
+
 ### Start a server
 
 Jest Puppeteer integrates a functionality to start a server when running your test suite. It automatically closes the server when tests are done.
@@ -116,6 +124,7 @@ module.exports = {
  globals: {
  page: true,
  browser: true,
+ jestPuppeteer: true,
  },
 }
 ```
@@ -230,6 +239,19 @@ await expect(page).toMatch('A text in the page')
 // ...
 ```
 
+### `global.jestPuppeteer.debug()`
+
+Put test in debug mode.
+
+- Jest is suspended (no timeout)
+- A `debugger` instruction to Chromium, if Puppeteer has been launched with `{ devtools: true }` it will stop
+
+```js
+it('should put test in debug mode', async () => {
+ await jestPuppeteer.debug()
+})
+```
+
 ### `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.

package.json

@@ -6,6 +6,7 @@
  "scripts": {
  "build": "lerna run build",
  "ci": "yarn build && yarn lint && yarn test --ci",
+ "dev": "lerna run build --parallel -- --watch",
  "format": "prettier --write \"packages/**/*.{js,json,md}\" \"*.{js,json,md}\"",
  "lint": "eslint .",
  "release": "lerna publish --conventional-commits && conventional-github-releaser --preset angular",
@@ -26,5 +27,6 @@
  "lerna": "^2.11.0",
  "prettier": "^1.13.5",
  "puppeteer": "^1.5.0"
- }
+ },
+ "dependencies": {}
 }

packages/jest-environment-puppeteer/README.md

@@ -60,6 +60,19 @@ it('should fill an input', async () => {
 })
 ```
 
+### `global.jestPuppeteer.debug()`
+
+Put test in debug mode.
+
+- Jest is suspended (no timeout)
+- A `debugger` instruction to Chromium, if Puppeteer has been launched with `{ devtools: true }` it will stop
+
+```js
+it('should put test in debug mode', async () => {
+ await jestPuppeteer.debug()
+})
+```
+
 ### `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.

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

@@ -2,6 +2,7 @@ import fs from 'fs'
 // eslint-disable-next-line
 import NodeEnvironment from 'jest-environment-node'
 import puppeteer from 'puppeteer'
+import chalk from 'chalk'
 import readConfig from './readConfig'
 import { WS_ENDPOINT_PATH } from './constants'
 
@@ -10,6 +11,17 @@ const handleError = error => {
 }
 
 class PuppeteerEnvironment extends NodeEnvironment {
+ // Jest is not available here, so we have to reverse engineer
+ // the setTimeout function, see https://github.com/facebook/jest/blob/v23.1.0/packages/jest-runtime/src/index.js#L823
+ setTimeout(timeout) {
+ if (this.global.jasmine) {
+ // eslint-disable-next-line no-underscore-dangle
+ this.global.jasmine.DEFAULT_TIMEOUT_INTERVAL = timeout
+ } else {
+ this.global[Symbol.for('TEST_TIMEOUT_SYMBOL')] = timeout
+ }
+ }
+
  async setup() {
  const config = await readConfig()
  this.global.puppeteerConfig = config
@@ -33,6 +45,42 @@ class PuppeteerEnvironment extends NodeEnvironment {
  if (config && config.exitOnPageError) {
  this.global.page.addListener('pageerror', handleError)
  }
+
+ this.global.jestPuppeteer = {
+ debug: async () => {
+ // eslint-disable-next-line no-eval
+ // Set timeout to 4 days
+ this.setTimeout(345600)
+ // Run a debugger (in case Puppeteer has been launched with `{ devtools: true }`)
+ await this.global.page.evaluate(() => {
+ // eslint-disable-next-line no-debugger
+ debugger
+ })
+ console.log(
+ chalk.blue('\n\n🕵️‍ Code is paused, press enter to resume'),
+ )
+ // Run an infinite promise
+ return new Promise(resolve => {
+ const { stdin } = process
+ const onKeyPress = key => {
+ if (key === '\r') {
+ stdin.removeListener('data', onKeyPress)
+ if (!listening) {
+ stdin.pause()
+ }
+ resolve()
+ }
+ }
+ const listening = stdin.listenerCount('data') > 0
+ if (!listening) {
+ stdin.setRawMode(true)
+ stdin.resume()
+ stdin.setEncoding('utf8')
+ }
+ stdin.on('data', onKeyPress)
+ })
+ },
+ }
  }
 
  async teardown() {