# Neutrino Karma Preset [![NPM version][npm-image]][npm-url] [![NPM downloads][npm-downloads]][npm-url] [![Join Slack][slack-image]][slack-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 v5, 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](https://neutrino.js.org/project-layout) 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 --use neutrino-preset-react neutrino-preset-karma" } } ``` Or if you have set up Neutrino with `neutrino.use` in your package.json: ```json { "neutrino": { "use": [ "neutrino-preset-react", "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](https://neutrino.js.org/cli#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](https://neutrino.js.org/customization). `neutrino-preset-karma` creates some conventions to make overriding the configuration easier once you are ready to make changes. ### Simple customization By following the [customization guide](https://neutrino.js.org/customization/simple) you can override and augment the test configuration directly from package.json. `neutrino-preset-karma` will import Karma configuration from your package.json's `neutrino.options.karma` object if defined. The format is defined on the [Karma documentation site](http://karma-runner.github.io/1.0/config/configuration-file.html). _Example: Change the duration Karma waits for a browser to reconnect (in ms)._ ```js { "neutrino": { "options": { "karma": { "browserDisconnectTimeout": 5000 } } } } ``` ### Advanced configuration By following the [customization guide](https://neutrino.js.org/customization/advanced) 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.options.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.options.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](https://neutrino.js.org/contributing) for details. [npm-image]: https://img.shields.io/npm/v/neutrino-preset-karma.svg [npm-downloads]: https://img.shields.io/npm/dt/neutrino-preset-karma.svg [npm-url]: https://npmjs.org/package/neutrino-preset-karma [slack-image]: https://neutrino-slack.herokuapp.com/badge.svg [slack-url]: https://neutrino-slack.herokuapp.com/