Docs: Karma, neutrino.js.org, dev commands

README.md

@@ -1,4 +1,4 @@
-<h1><p align="center"><a href="http://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1>
+<h1><p align="center"><a href="https://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1>
 
 ### Create and build modern JavaScript applications with zero initial configuration
 #### Think: Webpack, but with presets. That's Neutrino.

docs/README.md

@@ -1,4 +1,4 @@
-<h1><p align="center"><a href="http://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1>
+<h1><p align="center"><a href="https://neutrino.js.org"><img src="https://raw.githubusercontent.com/mozilla-neutrino/neutrino-dev/master/docs/assets/logo.png" height="150"></a></p></h1>
 
 ### Create and build modern JavaScript applications with zero initial configuration
 #### Think Webpack, but with presets. That's Neutrino.

docs/contributing/development.md

@@ -7,6 +7,14 @@ packages and documentation.
 _Note: In this guide, commands executable from the command line are prepended with `❯`. Lines not starting
 with this symbol show sample console output from running the previous command._
 
+## Requirements
+
+Developing for neutrino-dev requires:
+
+- Node.js v6.9+
+- Yarn client, installation instructions at https://yarnpkg.com/en/docs/install
+- git, GitHub account
+
 ## Getting started
 
 The first step to start developing neutrino-dev is forking the repository to your own GitHub account.
@@ -21,6 +29,108 @@ of the account you forked the repository to:
 ❯ cd neutrino-dev
 ```
 
+Upon cloning, you should install dependencies and bootstrap the project:
+
+```bash
+❯ yarn
+❯ yarn bootstrap
+```
+
+This will create symlinks between the various packages, making local development much easier. It also creates yarn links
+for testing out these packages elsewhere on your system.
+
+## Development commands
+
+The package.json for neutrino-dev defines several commands to assist in the development and deployment process.
+
+---
+
+`bootstrap`
+
+Installs all sub-package dependencies using yarn. External dependencies are installed normally, whereas those belonging
+to the neutrino-dev monorepo itself are `yarn link`ed.
+
+```bash
+❯ yarn bootstrap
+```
+
+---
+
+`deps:add [--dev] <package> <...dependencies>`
+
+Adds one or more new dependencies or development dependencies to a sub-package. Any flags used, such as `--dev` are
+passed on to `yarn add`. For example, if you wanted to add "lodash.clonedeep" to the neutrino package:
+
+```bash
+❯ yarn deps:add neutrino lodash.clonedeep
+```
+
+---
+
+`deps:remove <package> <...dependencies>`
+
+Removes one or more dependencies from a sub-package. Any flags used are
+passed on to `yarn remove`. For example, if you wanted to remove "lodash.clonedeep" from the neutrino package:
+
+```bash
+❯ yarn deps:remove neutrino lodash.clonedeep
+```
+
+---
+
+`deps:upgrade <package> <...dependencies>`
+
+Upgrades one or more dependencies in a sub-package. Any flags used are
+passed on to `yarn upgrade`. For example, if you wanted to upgrade "lodash.clonedeep" in the neutrino package:
+
+```bash
+❯ yarn deps:upgrade neutrino lodash.clonedeep
+```
+
+---
+
+`deps:clean`
+
+Removes the `node_modules` directory from all sub-packages. After running this you will need to re-bootstrap
+neutrino-dev in order to continue development. Useful if you have somehow put your local development environment in an
+unworkable state with regards to local inter-dependencies.
+
+```bash
+❯ yarn deps:clean
+```
+
+---
+
+`docs:serve`
+
+Starts a local development server which builds the documentation in `docs` to a gitbook running on port 4000.
+
+```bash
+❯ yarn docs:serve
+```
+
+---
+
+`docs:build`
+
+Generates a static site by building the documentation in `docs` to a gitbook to the `_book` directory.
+
+```bash
+❯ yarn docs:build
+```
+
+---
+
+`docs:deploy`
+
+Generates a static site by building the documentation in `docs` to a gitbook to the `_book` directory, then pushing the
+contents of `_book` to a `gh-pages` branch on GitHub. In order to run this command, you must have an `upstream` remote
+configured pointing to the root neutrino-dev repo, and have sufficient rights to push to the repository.
+
+```bash
+❯ yarn docs:deploy
+```
+
 ## Making changes
 
 When you make changes to neutrino-dev, you should make them in a branch separate from `master`. Start from the
@@ -51,6 +161,10 @@ Now if you open the GitHub page for your repository, GitHub should display a but
 the branch and commit you just pushed. When filling out the details of the pull request, try to be as descriptive
 as possible, following our detailed [contribution guidelines](/contributing/README.md).
 
+### Congrats!
+
+You just made a contribution to Neutrino! We are so happy to have your help! :tada:
+
 ## Receiving updates
 
 If you need to update your local copy of neutrino-dev to be in sync with the main neutrino-dev repository, you
@@ -62,7 +176,3 @@ the latest changes from the master branch.
 ❯ git remote add upstream https://github.com/mozilla-neutrino/neutrino-dev.git
 ❯ git pull upstream master
 ```
-
-## Congrats!
-
-You just made a contribution to Neutrino! We are so happy to have your help! :tada:

docs/presets/neutrino-preset-jest/README.md

@@ -82,9 +82,9 @@ Run the tests, and view the results in your console:
 Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
-Time:        1.973s
+Time:        0.936s
 Ran all test suites.
-✨  Done in 4.43s.
+✨  Done in 2.12s.
 ```
 
 #### npm
@@ -99,7 +99,7 @@ Ran all test suites.
 Test Suites: 1 passed, 1 total
 Tests:       1 passed, 1 total
 Snapshots:   0 total
-Time:        1.075s
+Time:        0.972s
 Ran all test suites.
 ```
 

docs/presets/neutrino-preset-karma/README.md

@@ -1 +1,188 @@
-# heading
+# Neutrino Karma Preset [![NPM version][npm-image]][npm-url]
+
+`neutrino-preset-karma` is a Neutrino preset that supports testing web applications using the Karma test runner.
+
+## Features
+
+- Zero upfront configuration necessary to start testing on real browsers with Karma, Mocha, and Chrome
+- Babel compilation that compiles your tests using the same Babel options used by your source code
+- Source watching for re-running of tests on change
+- Out-of-the-box support for running in CI
+- 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-karma` can be installed via the Yarn or npm clients. Inside your project, make sure
+`neutrino` and `neutrino-preset-karma` are development dependencies. You will also be using
+another Neutrino preset for building your application source code.
+
+#### Yarn
+
+```bash
+❯ yarn add --dev neutrino-preset-karma
+```
+
+#### npm
+
+```bash
+❯ npm install --save-dev neutrino-preset-karma
+```
+
+## Project Layout
+
+`neutrino-preset-karma` 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 Karma 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 React project:
+
+```json
+{
+  "scripts": {
+    "test": "neutrino test --presets neutrino-preset-node neutrino-preset-karma"
+  }
+}
+```
+
+Run the tests, and view the results in your console:
+
+#### Yarn
+
+```bash
+❯ yarn test
+
+START:
+16 02 2017 10:36:34.713:INFO [karma]: Karma v1.4.1 server started at http://0.0.0.0:9876/
+16 02 2017 10:36:34.715:INFO [launcher]: Launching browser Chrome with unlimited concurrency
+16 02 2017 10:36:34.731:INFO [launcher]: Starting browser Chrome
+16 02 2017 10:36:35.655:INFO [Chrome 56.0.2924 (Mac OS X 10.12.3)]: Connected on socket MkTbqJLpAAa2HFaeAAAA with id 21326158
+  simple
+    ✔ should be sane
+
+Finished in 0.003 secs / 0 secs @ 10:36:35 GMT-0600 (CST)
+
+SUMMARY:
+✔ 1 test completed
+✨  Done in 7.54s.
+```
+
+#### npm
+
+```bash
+❯ npm test
+
+START:
+16 02 2017 10:38:12.865:INFO [karma]: Karma v1.4.1 server started at http://0.0.0.0:9876/
+16 02 2017 10:38:12.867:INFO [launcher]: Launching browser Chrome with unlimited concurrency
+16 02 2017 10:38:12.879:INFO [launcher]: Starting browser Chrome
+16 02 2017 10:38:13.688:INFO [Chrome 56.0.2924 (Mac OS X 10.12.3)]: Connected on socket svRGoxU0etKTKQWhAAAA with id 68456725
+  simple
+    ✔ should be sane
+
+Finished in 0.006 secs / 0 secs @ 10:38:13 GMT-0600 (CST)
+
+SUMMARY:
+✔ 1 test completed
+```
+
+To run tests against files from your source code, simply import them:
+
+```js
+import thingToTest from '../src/thing';
+```
+
+For more details on specific Karma usage, please refer to their
+[documentation](https://karma-runner.github.io/1.0/index.html).
+
+## Executing single tests
+
+By default this preset will execute every test file located in your test directory ending in the appropriate file
+extension.
+Use the command line [`files` parameters](/cli/README.md#neutrino-test) to execute individual tests.
+
+## Watching for changes
+
+`neutrino-preset-karma` can watch for changes on your source directory and subsequently re-run tests. Simply use the
+`--watch` flag with your `neutrino test` command.
+
+## Using from CI
+
+`neutrino-preset-karma` needs no additional configuration to run your tests in CI infrastructure, but you will still
+need to ensure your CI can actually run the tests. This usually means having a display emulator and access to the
+browsers you are testing against.
+
+To do this in Travis-CI, you will need to add the following to your `.travis.yml` file for Chrome tests:
+
+```yaml
+before_install:
+  - export CHROME_BIN=chromium-browser
+  - export DISPLAY=:99.0
+  - sh -e /etc/init.d/xvfb start
+```
+
+## Customizing
+
+To override the test configuration, start with the documentation on [customization](/customization/README.md).
+`neutrino-preset-karma` creates some conventions to make overriding the configuration easier once you are ready to make
+changes.
+
+### Simple customization
+
+It is not currently possible to override `neutrino-preset-karma` settings from the package.json using simple
+customization. Please use the advanced configuration for changes.
+
+### Advanced configuration
+
+By following the [customization guide](/customization/advanced.md) you can override and augment testing by creating a
+JS module which overrides the config. 
+
+You can also modify Karma settings by overriding with any options Karma accepts. In a standalone Karma project this is
+typically done in a `karma.conf.js` file, but `neutrino-preset-karma` unifies advanced configuration through a preset
+override module. When needing to make changes to Karma-specific settings, this is stored in the `neutrino.custom.karma`
+object, and takes the same configuration options as outlined in the
+[Karma documentation](https://karma-runner.github.io/1.0/config/configuration-file.html).
+
+_Example: Change the duration Karma waits for a browser to reconnect (in ms)._
+
+```js
+module.exports = neutrino => {
+  neutrino.custom.karma.browserDisconnectTimeout = 5000;
+};
+```
+
+## 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-karma.svg
+[npm-url]: https://npmjs.org/package/neutrino-preset-karma