From a0615bbe5412ad45d98b23694c8b346957c7f307 Mon Sep 17 00:00:00 2001 From: Grzegorz Ziolkowski Date: Fri, 30 Nov 2018 09:45:49 +0100 Subject: [PATCH] Docs: Add docs for test-e2e script added to scripts packages --- packages/scripts/CHANGELOG.md | 6 ++ packages/scripts/README.md | 59 ++++++++++++++----- .../scripts/test-e2e-jest-puppeteer.js | 44 -------------- packages/scripts/scripts/test-e2e.js | 45 +++++++++++++- 4 files changed, 95 insertions(+), 59 deletions(-) delete mode 100644 packages/scripts/scripts/test-e2e-jest-puppeteer.js diff --git a/packages/scripts/CHANGELOG.md b/packages/scripts/CHANGELOG.md index c07fe9a2e6d566..277dbe2f3c2481 100644 --- a/packages/scripts/CHANGELOG.md +++ b/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) diff --git a/packages/scripts/README.md b/packages/scripts/README.md index 4126cdd34cc9b2..32b0fe5c8b82c2 100644 --- a/packages/scripts/README.md +++ b/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).

Code is Poetry.

diff --git a/packages/scripts/scripts/test-e2e-jest-puppeteer.js b/packages/scripts/scripts/test-e2e-jest-puppeteer.js deleted file mode 100644 index 70cb7507f05d99..00000000000000 --- a/packages/scripts/scripts/test-e2e-jest-puppeteer.js +++ /dev/null @@ -1,44 +0,0 @@ -// 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 ) -); diff --git a/packages/scripts/scripts/test-e2e.js b/packages/scripts/scripts/test-e2e.js index 8d7cae99c2ccac..70cb7507f05d99 100644 --- a/packages/scripts/scripts/test-e2e.js +++ b/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 ) +);