Docs: Add docs for test-e2e script added to scripts packages

packages/scripts/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.5.0 (Unreleased)
+
+### New Feature
+
+- Added support for `test-e2e` script ([#12437](https://github.com/WordPress/gutenberg/pull/12437)).
+
 ## 2.4.4 (2018-11-20)
 
 ## 2.4.3 (2018-11-09)

packages/scripts/README.md

@@ -19,15 +19,18 @@ _Example:_
 ```json
 {
 	"scripts": {
+		"check-licenses": "wp-scripts check-licenses --production",
+		"lint:js": "wp-scripts lint-js .",
 		"lint:pkg-json": "wp-scripts lint-pkg-json .",
-		"test": "wp-scripts test-unit-js"
+		"test:e2e": "wp-scripts test-e2e",
+		"test:unit": "wp-scripts test-unit-js"
 	}
 }
 ```
 
 ## Available Scripts
 
-### `wp-scripts lint-js`
+### `lint-js`
 
 Helps enforce coding style guidelines for your JavaScript files. It uses [eslint](https://eslint.org/) with no rules provided (we plan to add zero config support in the near future). You can specify your own rules as described in [eslint docs](https://eslint.org/docs/rules/).
 
@@ -44,7 +47,7 @@ _Example:_
 This is how you execute the script with presented setup:
 * `npm run lint:js` - lints JavaScripts files in the whole project's.
 
-### `wp-scripts lint-pkg-json`
+### `lint-pkg-json`
 
 Helps enforce standards for your package.json files. It uses [npm-package-json-lint](https://www.npmjs.com/package/npm-package-json-lint) with the set of default rules provided. You can override them with your own rules as described in [npm-package-json-lint wiki](https://github.com/tclindner/npm-package-json-lint/wiki).
 
@@ -61,30 +64,58 @@ _Example:_
 This is how you execute those scripts using the presented setup:
 * `npm run lint:pkg-json` - lints `package.json` file in the project's root folder.
 
-### `wp-scripts test-unit-js`
+### `test-e2e`
+
+Launches the End-To-End (E2E) test runner. It uses [Jest](https://facebook.github.io/jest/) behind the scenes and you are able to utilize all of its [CLI options](https://facebook.github.io/jest/docs/en/cli.html). You can also run `./node_modules/.bin/wp-scripts test:e2e --help` or `npm run test:e2e:help` (as presented below) to view all of the available options.
+
+Writing tests can be done using Puppeteer API:
+
+> [Puppeteer](https://pptr.dev/) is a Node library which provides a high-level API to control Chrome or Chromium over the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/). Puppeteer runs [headless](https://developers.google.com/web/updates/2017/04/headless-chrome) by default, but can be configured to run full (non-headless) Chrome or Chromium.
+
+_Example:_
+
+```json
+{
+	"scripts": {
+		"test:e2e": "wp-scripts test-e2e",
+		"test:e2e:help": "wp-scripts test-e2e --help"
+	}
+}
+```
+
+This is how you execute those scripts using the presented setup:
+* `npm run test:e2e` - runs all unit tests.
+* `npm run test:e2e:help` - prints all available options to configure unit tests runner.
+
+This script automatically detects the best config to start Puppeteer but sometimes you may need to specify custom options:
+ - You can add a `jest-puppeteer.config.js` at the root of the project or define a custom path using `JEST_PUPPETEER_CONFIG` environment variable. Check [jest-puppeteer](https://github.com/smooth-code/jest-puppeteer#jest-puppeteerconfigjs) for more details.
+
+We enforce that all tests run serially in the current process using [--runInBand](https://jestjs.io/docs/en/cli#runinband) Jest CLI option to avoid conflicts between tests caused by the fact that they share the same WordPress instance.
+
+### `test-unit-js`
 
 _Alias_: `wp-scripts test-unit-jest` 
 
-Launches the test runner. It uses [Jest](https://facebook.github.io/jest/) behind the scenes and you are able to utilize all of its [CLI options](https://facebook.github.io/jest/docs/en/cli.html). You can also run `./node_modules/.bin/wp-scripts test-unit-js --help` or `npm run test:help` (as presented below) to view all of the available options.
+Launches the unit test runner. It uses [Jest](https://facebook.github.io/jest/) behind the scenes and you are able to utilize all of its [CLI options](https://facebook.github.io/jest/docs/en/cli.html). You can also run `./node_modules/.bin/wp-scripts test-unit-js --help` or `npm run test:unit:help` (as presented below) to view all of the available options.
 
 _Example:_
 
 ```json
 {
 	"scripts": {
-		"test": "wp-scripts test-unit-js",
-		"test:help": "wp-scripts test-unit-js --help",
-		"test:watch": "wp-scripts test-unit-js --watch"
+		"test:unit": "wp-scripts test-unit-js",
+		"test:unit:help": "wp-scripts test-unit-js --help",
+		"test:unit:watch": "wp-scripts test-unit-js --watch"
 	}
 }
 ```
 
 This is how you execute those scripts using the presented setup:
-* `npm run test` or `npm test` - runs all unit tests.
-* `npm run test:help` - prints all available options to configure unit tests runner.
-* `npm run test:watch` - runs all unit tests in the watch mode.
+* `npm run test:unit` - runs all unit tests.
+* `npm run test:unit:help` - prints all available options to configure unit tests runner.
+* `npm run test:unit:watch` - runs all unit tests in the watch mode.
 
-### `wp-scripts check-licenses`
+### `check-licenses`
 
 Validates that all dependencies of a project are compatible with the project's own license.
 
@@ -93,7 +124,7 @@ _Example:_
 ```json
 {
 	"scripts": {
-		"check-licenses": "wp-scripts check-licenses --prod --gpl2 --ignore=abab",
+		"check-licenses": "wp-scripts check-licenses --prod --gpl2 --ignore=abab"
 	}
 }
 ```
@@ -107,6 +138,6 @@ _Flags_:
 
 ## Inspiration
 
-This is inspired by [react-scripts](https://www.npmjs.com/package/react-scripts) and [kcd-scripts](https://www.npmjs.com/package/kcd-scripts).
+This package is inspired by [react-scripts](https://www.npmjs.com/package/react-scripts) and [kcd-scripts](https://www.npmjs.com/package/kcd-scripts).
 
 <br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/scripts/scripts/test-e2e.js

@@ -1 +1,44 @@
-require( './test-e2e-jest-puppeteer' );
+// Do this as the first thing so that any code reading it knows the right env.
+process.env.BABEL_ENV = 'test';
+process.env.NODE_ENV = 'test';
+
+// Makes the script crash on unhandled rejections instead of silently
+// ignoring them. In the future, promise rejections that are not handled will
+// terminate the Node.js process with a non-zero exit code.
+process.on( 'unhandledRejection', ( err ) => {
+	throw err;
+} );
+
+/**
+ * External dependencies
+ */
+const jest = require( 'jest' );
+
+/**
+ * Internal dependencies
+ */
+const {
+	fromConfigRoot,
+	getCliArgs,
+	hasCliArg,
+	hasProjectFile,
+	hasJestConfig,
+} = require( '../utils' );
+
+// Provides a default config path for Puppeteer when jest-puppeteer.config.js
+// wasn't found at the root of the project or a custom path wasn't defined
+// using JEST_PUPPETEER_CONFIG environment variable.
+if ( ! hasProjectFile( 'jest-puppeteer.config.js' ) && ! process.env.JEST_PUPPETEER_CONFIG ) {
+	process.env.JEST_PUPPETEER_CONFIG = fromConfigRoot( 'puppeteer.config.js' );
+}
+
+const hasRunInBand = hasCliArg( '--runInBand' ) ||
+	hasCliArg( '-i' );
+
+jest.run(
+	[].concat(
+		! hasJestConfig() && [ '--config', JSON.stringify( fromConfigRoot( 'jest-e2e.config' ) ) ],
+		! hasRunInBand && '--runInBand',
+		getCliArgs()
+	).filter( Boolean )
+);