Docs: Mocha, Jest intro

8 years ago · 0ef8679251
5 changed files with 547 additions and 3 deletions
--- a/docs/presets/neutrino-preset-jest/README.md
+++ b/docs/presets/neutrino-preset-jest/README.md
@ -1 +1,164 @@
-# heading
+# Neutrino Jest Preset [![NPM version][npm-image]][npm-url]
+
+`neutrino-preset-jest` is a Neutrino preset that supports testing JavaScript projects with the Jest test runner.
+
+## Features
+
+- Zero upfront configuration necessary to start testing
+- Babel compilation that compiles your tests using the same Babel options used by your source code
+- Easily extensible to customize your testing as needed
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v4, Neutrino build preset
+
+## Installation
+
+`neutrino-preset-jest` can be installed via the Yarn or npm clients. Inside your project, make sure
+`neutrino` and `neutrino-preset-jest` are development dependencies. You will also be using
+another Neutrino preset for building your application source code.
+
+#### Yarn
+
+```bash
+❯ yarn add --dev neutrino-preset-jest
+```
+
+#### npm
+
+```bash
+❯ npm install --save-dev neutrino-preset-mocha
+```
+
+## Project Layout
+
+`neutrino-preset-jest` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+means that by default all project test code should live in a directory named `test` in the root of the
+project. Test files end in either `_test.js` or `.test.js`.
+
+## Quickstart
+
+After adding the Jest preset to your Neutrino-built project, add a new directory named `test` in the root of the
+project, with a single JS file named `simple_test.js` in it.
+
+```bash
+❯ mkdir test && touch test/simple_test.js
+```
+
+Edit your `test/simple_test.js` file with the following:
+
+```js
+describe('simple', () => {
+  it('should be sane', () => {
+    expect(!false).toBe(true);
+  });
+});
+```
+
+Now edit your project's package.json to add commands for testing your application. In this example,
+let's pretend this is a Node.js project:
+
+```json
+{
+  "scripts": {
+    "test": "neutrino test --presets neutrino-preset-node neutrino-preset-mocha"
+  }
+}
+```
+
+Run the tests, and view the results in your console:
+
+#### Yarn
+
+```bash
+❯ yarn test
+
+  simple
+    ✓ should be sane
+
+
+  1 passing (426ms)
+
+✨  Done in 4.17s.
+```
+
+#### npm
+
+```bash
+❯ npm test
+
+  simple
+    ✓ should be sane
+
+
+  1 passing (409ms)
+```
+
+To run tests against files from your source code, simply import them:
+
+```js
+import thingToTest from '../src/thing';
+```
+
+## Executing single tests
+
+By default this preset will execute every test file located in your test directory ending in `_test.js`.
+Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests.
+
+## Customizing
+
+To override the test configuration, start with the documentation on [customization](/customization/README.md).
+`neutrino-preset-mocha` creates some conventions to make overriding the configuration easier once you are ready to make
+changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `compile`: Compiles JS files from the `test` directory using Babel. Contains a single loader named `babel`.
+
+### Simple customization
+
+By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above,
+you can override and augment the build directly from package.json.
+
+### Advanced configuration
+
+By following the [customization guide](/customization/advanced.md) and knowing the rule, and loader IDs above,
+you can override and augment testing by creating a JS module which overrides the config.
+
+You can modify Mocha settings by overriding the preset with any options Mocha accepts. This is stored in the
+`neutrino.custom.mocha` object.
+
+_Example: Switch the test reporter from the default `spec` to `nyan`:_
+
+```js
+module.exports = neutrino => {
+  neutrino.custom.mocha.reporter = 'nyan';
+};
+```
+
+```bash
+❯ yarn test
+yarn test v0.19.1
+$ node_modules/neutrino/bin/neutrino test
+ 1   -__,------,
+ 0   -__|  /\_/\
+ 0   -_~|_( ^ .^)
+     -_ ""  ""
+
+  1 passing (362ms)
+
+✨  Done in 3.28s.
+```
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](/contributing/README.md) for details.
+
+[npm-image]: https://badge.fury.io/js/neutrino-preset-jest.svg
+[npm-url]: https://npmjs.org/package/neutrino-preset-jest
--- a/docs/presets/neutrino-preset-mocha/README.md
+++ b/docs/presets/neutrino-preset-mocha/README.md
@ -1 +1,166 @@
-# heading
+# Neutrino Mocha Preset [![NPM version][npm-image]][npm-url]
+
+`neutrino-preset-mocha` is a Neutrino preset that supports testing JavaScript projects with the Mocha test runner.
+
+## Features
+
+- Zero upfront configuration necessary to start testing
+- Babel compilation that compiles your tests using the same Babel options used by your source code
+- Easily extensible to customize your testing as needed
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v4, Neutrino build preset
+
+## Installation
+
+`neutrino-preset-mocha` can be installed via the Yarn or npm clients. Inside your project, make sure
+`neutrino` and `neutrino-preset-mocha` are development dependencies. You will also be using
+another Neutrino preset for building your application source code.
+
+#### Yarn
+
+```bash
+❯ yarn add --dev neutrino-preset-mocha
+```
+
+#### npm
+
+```bash
+❯ npm install --save-dev neutrino-preset-mocha
+```
+
+## Project Layout
+
+`neutrino-preset-mocha` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+means that by default all project test code should live in a directory named `test` in the root of the
+project. Test files end in `_test.js` by default.
+
+## Quickstart
+
+After adding the Mocha preset to your Neutrino-built project, add a new directory named `test` in the root of the
+project, with a single JS file named `simple_test.js` in it.
+
+```bash
+❯ mkdir test && touch test/simple_test.js
+```
+
+Edit your `test/simple_test.js` file with the following:
+
+```js
+import assert from 'assert';
+
+describe('simple', () => {
+  it('should be sane', () => {
+    assert.equal(true, !false);
+  });
+});
+```
+
+Now edit your project's package.json to add commands for testing your application. In this example,
+let's pretend this is a Node.js project:
+
+```json
+{
+  "scripts": {
+    "test": "neutrino test --presets neutrino-preset-node neutrino-preset-mocha"
+  }
+}
+```
+
+Run the tests, and view the results in your console:
+
+#### Yarn
+
+```bash
+❯ yarn test
+
+  simple
+    ✓ should be sane
+
+
+  1 passing (426ms)
+
+✨  Done in 4.17s.
+```
+
+#### npm
+
+```bash
+❯ npm test
+
+  simple
+    ✓ should be sane
+
+
+  1 passing (409ms)
+```
+
+To run tests against files from your source code, simply import them:
+
+```js
+import thingToTest from '../src/thing';
+```
+
+## Executing single tests
+
+By default this preset will execute every test file located in your test directory ending in `_test.js`.
+Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests.
+
+## Customizing
+
+To override the test configuration, start with the documentation on [customization](/customization/README.md).
+`neutrino-preset-mocha` creates some conventions to make overriding the configuration easier once you are ready to make
+changes.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `compile`: Compiles JS files from the `test` directory using Babel. Contains a single loader named `babel`.
+
+### Simple customization
+
+By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above,
+you can override and augment the build directly from package.json.
+
+### Advanced configuration
+
+By following the [customization guide](/customization/advanced.md) and knowing the rule, and loader IDs above,
+you can override and augment testing by creating a JS module which overrides the config.
+
+You can modify Mocha settings by overriding the preset with any options Mocha accepts. This is stored in the
+`neutrino.custom.mocha` object.
+
+_Example: Switch the test reporter from the default `spec` to `nyan`:_
+
+```js
+module.exports = neutrino => {
+  neutrino.custom.mocha.reporter = 'nyan';
+};
+```
+
+```bash
+❯ yarn test
+yarn test v0.19.1
+$ node_modules/neutrino/bin/neutrino test
+ 1   -__,------,
+ 0   -__|  /\_/\
+ 0   -_~|_( ^ .^)
+     -_ ""  ""
+
+  1 passing (362ms)
+
+✨  Done in 3.28s.
+```
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](/contributing/README.md) for details.
+
+[npm-image]: https://badge.fury.io/js/neutrino-preset-mocha.svg
+[npm-url]: https://npmjs.org/package/neutrino-preset-mocha
--- a/docs/presets/neutrino-preset-node/README.md
+++ b/docs/presets/neutrino-preset-node/README.md
@ -1,5 +1,215 @@
-# heading
+# Neutrino Node.js Preset [![NPM version][npm-image]][npm-url]
+
+`neutrino-preset-node` is a Neutrino preset that supports building Node.js applications.
+
+## Features
+
+- Zero upfront configuration necessary to start developing and building a Node.js project
+- Modern Babel compilation supporting ES modules, Node.js 6.9+, and async functions
+- Auto-wired sourcemaps
+- Chunking of external dependencies apart from application code
+- Easily extensible to customize your project as needed
+
+## Requirements
+
+- Node.js v6.9+
+- Yarn or npm client
+- Neutrino v4
+
+## Installation
+
+`neutrino-preset-node` can be installed via the Yarn or npm clients. Inside your project, make sure
+`neutrino` and `neutrino-preset-node` are development dependencies.
+
+#### Yarn
+
+```bash
+❯ yarn add --dev neutrino neutrino-preset-node
+```
+
+#### npm
+
+```bash
+❯ npm install --save-dev neutrino neutrino-preset-node
+```
+
+## Project Layout
+
+`neutrino-preset-node` follows the standard [project layout](/project-layout.md) specified by Neutrino. This
+means that by default all project source code should live in a directory named `src` in the root of the
+project. This includes JavaScript files that would be available to your compiled project.
+
+## Quickstart
+
+After installing Neutrino and the Node.js preset, add a new directory named `src` in the root of the project, with
+a single JS file named `index.js` in it.
+
+```bash
+❯ mkdir src && touch src/index.js
+```
+
+Edit your `src/index.js` file with the following:
+
+```js
+import { createServer } from 'http';
+
+const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
+const port = process.env.PORT || 3000;
+
+createServer(async (req, res) => {
+  await delay(500);
+  console.log('Request!');
+  res.end('hi!');
+})
+.listen(port, () => console.log(`Server running on port ${port}`));
+```
+
+Now edit your project's package.json to add commands for starting and building the application.

 **Important Note:** At the time of writing, Neutrino's Node preset does not support `watch`
 compilation with `neutrino start`; it will instead fall back to running a build with the `NODE_ENV`
 environment variable set to `development`.
+
+```json
+{
+  "scripts": {
+    "start": "neutrino start --presets neutrino-preset-node && node build/index.js",
+    "build": "neutrino build --presets neutrino-preset-node"
+  }
+}
+```
+
+Start the app, then either open a browser to http://localhost:3000 or use curl from another terminal window:
+
+#### Yarn
+
+```bash
+❯ yarn start
+Warning: This preset does not support watch compilation. Falling back to a one-time build.
+Hash: 89e4fb250fc535920ba4
+Version: webpack 2.2.1
+Time: 432ms
+       Asset     Size  Chunks             Chunk Names
+    index.js  4.29 kB       0  [emitted]  index
+index.js.map  3.73 kB       0  [emitted]  index
+Server running on port 3000
+```
+
+```bash
+❯ curl http://localhost:3000
+hi!
+```
+
+#### npm
+
+```bash
+❯ npm start
+Warning: This preset does not support watch compilation. Falling back to a one-time build.
+Hash: 89e4fb250fc535920ba4
+Version: webpack 2.2.1
+Time: 432ms
+       Asset     Size  Chunks             Chunk Names
+    index.js  4.29 kB       0  [emitted]  index
+index.js.map  3.73 kB       0  [emitted]  index
+Server running on port 3000
+```
+
+```bash
+❯ curl http://localhost:3000
+hi!
+```
+
+## Building
+
+`neutrino-preset-node` builds assets to the `build` directory by default when running `neutrino build`. Using the
+quick start example above as a reference:
+
+```bash
+❯ yarn build
+clean-webpack-plugin: /node/build has been removed.
+Build completed in 0.419s
+
+Hash: 89e4fb250fc535920ba4
+Version: webpack 2.2.1
+Time: 424ms
+       Asset     Size  Chunks             Chunk Names
+    index.js  4.29 kB       0  [emitted]  index
+index.js.map  3.73 kB       0  [emitted]  index
+✨  Done in 1.51s.
+```
+
+You can either serve or deploy the contents of this `build` directory as a Node.js module, server, or tool.
+
+## Customizing
+
+To override the build configuration, start with the documentation on [customization](/customization/README.md).
+`neutrino-preset-node` creates some conventions to make overriding the configuration easier once you are ready to make
+changes.
+
+By default the Node.js preset creates a single **main** `index` entry point to your application, and this maps to the
+`index.js` file in the `src` directory. This means that the Node.js preset is optimized toward a main entry to your app.
+Code not imported in the hierarchy of the `index` entry will not be output to the bundle. To overcome this you
+must either define more entry points, or import the code path somewhere along the `index` hierarchy.
+
+### Vendoring
+
+This preset automatically vendors all external dependencies into a separate chunk based on their inclusion in your
+package.json. No extra work is required to make this work.
+
+### Rules
+
+The following is a list of rules and their identifiers which can be overridden:
+
+- `compile`: Compiles JS files from the `src` directory using Babel. Contains a single loader named `babel`.
+
+### Plugins
+
+The following is a list of plugins and their identifiers which can be overridden:
+
+- `banner`: Injects source-map-support into the entry point of your application.
+- `copy`: Copies non-JS files from `src` to `build` when using `neutrino build`.
+- `clean`: Clears the contents of `build` prior to creating a production bundle.
+- `progress`: Displays a progress bar when using `neutrino build`.
+
+### Simple customization
+
+By following the [customization guide](/customization/simple.md) and knowing the rule, loader, and plugin IDs above,
+you can override and augment the build directly from package.json.
+
+_Example: Allow importing modules with an `.mjs` extension._
+
+```json
+{
+  "config": {
+    "neutrino": {
+      "resolve": {
+        "extensions": [
+          ".mjs"
+        ]
+      }
+    }
+  }
+}
+```
+
+### Advanced configuration
+
+By following the [customization guide](/customization/advanced.md) and knowing the rule, loader, and plugin IDs above,
+you can override and augment the build by creating a JS module which overrides the config.
+
+_Example: Allow importing modules with an `.mjs` extension._
+
+```js
+module.exports = neutrino => {
+  neutrino.config.resolve.extensions.add('.mjs');
+};
+```
+
+## Contributing
+
+This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
+containing all resources for developing Neutrino and its core presets. Follow the
+[contributing guide](/contributing/README.md) for details.
+
+[npm-image]: https://badge.fury.io/js/neutrino-preset-node.svg
+[npm-url]: https://npmjs.org/package/neutrino-preset-node
--- a/docs/presets/neutrino-preset-react/README.md
+++ b/docs/presets/neutrino-preset-react/README.md
@ -4,6 +4,7 @@

 ## Features

+- Zero upfront configuration necessary to start developing and building a React web app
 - Modern Babel compilation adding JSX and object rest spread syntax.
 - Support for React Hot Loader
 - Write JSX in .js or .jsx files
@ -214,6 +215,10 @@ module.exports = neutrino => {
 };
 ```

+## Hot Reloading
+
+
+
 ## Contributing

 This preset is part of the [neutrino-dev](https://github.com/mozilla-neutrino/neutrino-dev) repository, a monorepo
--- a/docs/presets/neutrino-preset-web/README.md
+++ b/docs/presets/neutrino-preset-web/README.md
@ -4,6 +4,7 @@

 ## Features

+- Zero upfront configuration necessary to start developing and building a web app
 - Modern Babel compilation supporting ES modules, last 2 major browser versions, and async functions
 - Webpack loaders for importing HTML, CSS, images, icons, and fonts
 - Webpack Dev Server during development