This repository has been archived by the owner on Feb 19, 2021. It is now read-only.
docs(readme): Document automatic setup #15
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,137 +1,168 @@ | ||
| [](https://travis-ci.org/stryker-mutator/stryker-karma-runner) | ||
| [](https://www.npmjs.com/package/stryker-karma-runner) | ||
| [](https://img.shields.io/node/v/stryker-karma-runner.svg) | ||
| [](https://gitter.im/stryker-mutator/stryker?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) | ||
|
|
||
| #Stryker Karma Runner | ||
|
|
||
| A plugin to use the karma test runner in [Stryker](https://stryker-mutator.github.io), the JavaScript mutation testing framework | ||
|
|
||
| ## Install | ||
|
|
||
| Install stryker-karma-runner locally within your project folder, like so: | ||
|
|
||
| ```bash | ||
| npm i --save-dev stryker-karma-runner | ||
| ``` | ||
|
|
||
| ## Peer dependencies | ||
|
|
||
| The `stryker-karma-runner` is a plugin for `stryker` to enable `karma` as a test runner. | ||
| As such, you should make sure you have the correct versions of its dependencies installed: | ||
|
|
||
| * `karma` | ||
| * `stryker-api` | ||
|
|
||
| For the current versions, see the `peerDependencies` section in the [package.json](https://github.com/stryker-mutator/stryker-karma-runner/blob/master/package.json). | ||
|
|
||
| These are marked as `peerDependencies` of `stryker-karma-runner` so you get a warning during installation when the correct versions are not installed. | ||
| *Note*: Karma itself also requires some plugins to work. | ||
|
|
||
| ## Configuring | ||
|
|
||
| You can either configure the karma test runner using the command line or by providing it in the `stryker.conf.js` file. | ||
| This README describes how to use the `stryker.conf.js` config file. | ||
|
|
||
| ### Load the plugin | ||
|
|
||
| In order to use the `stryker-karma-runner` it must me loaded in the stryker mutation testing framework via the stryker configuration. | ||
| The easiest way to achieve this, is *not have a `plugins` section* in your config file. That way, all `node_modules` starting with `stryker-` will be loaded. | ||
|
|
||
| If you do decide to choose specific modules, don't forget to add `'stryker-karma-runner'` to the list of plugins to load. | ||
|
|
||
| ### Use the test runner | ||
|
|
||
| In order to use karma as the test runner, you simply specify it in your config file: `testRunner: 'karma'` | ||
|
|
||
| ### Karma config | ||
|
|
||
| #### Automatic setup | ||
|
|
||
| You can configure stryker to use *your very own* `karma.conf.js` file. | ||
|
|
||
| ```javascript | ||
| // Stryker.conf.js | ||
| module.exports = function (config) { | ||
| config.set({ | ||
| testRunner: 'karma', | ||
| testFramework: 'jasmine', // <-- add your testFramework here | ||
| karmaConfigFile: 'karma.conf.js' // <-- add your karma.conf.js file here | ||
| mutate: [ | ||
| 'src/**/*.js' // <-- mark files for mutation here | ||
|
There was a problem hiding this comment. select the files to mutate here There was a problem hiding this comment. No, its not selecting. File selection is done via the |
||
| ] | ||
| }); | ||
| } | ||
| ``` | ||
|
|
||
| This will configure three things for you: | ||
|
|
||
| * Karma's `files` option will be used to configure the files in Stryker, you don't need to keep a list of files in sync in both `stryker.conf.js` and `karma.conf.js`. | ||
|
There was a problem hiding this comment.
|
||
| * Karma's `exclude` option will be used to ignore files in Stryker (using `!` to ignore them) | ||
| * All remaining karma config options will be copied to the `karmaConfig` option in Stryker config. They will be picked up by the `stryker-karma-runner` during mutation testing. | ||
| * **Note**: Any manual setup you configure in the `karmaConfig` options will *not* be overwritten. | ||
|
|
||
| #### Manual setup | ||
|
|
||
| **Note**: Using the manual setup will not read your `karma.conf.js` options. You'll probably need to *Override the karma config* (see next section) | ||
|
|
||
| When Stryker uses the karma test runner, it uses these default karma config settings: | ||
|
|
||
|
|
||
| ```javascript | ||
| { | ||
| browsers: ['PhantomJS'], // * | ||
| frameworks: ['jasmine'], // * | ||
| autoWatch: false, | ||
| singleRun: false, | ||
| } | ||
| // * these settings can be overriden, see next paragraph | ||
| ``` | ||
|
|
||
| For the first test run, stryker enables code coverage. If so, these additional settings are used: | ||
|
|
||
| ```javascript | ||
| coverageReporter: { | ||
| type: 'in-memory' | ||
| }, | ||
| preprocessors: { | ||
| 'src/file1.js': 'coverage', // for each file to be mutated | ||
| 'src/file2.js': 'coverage' | ||
| }, | ||
| plugins: ['karma-coverage'] // or left blank (by default, karma loads all plugins starting with karma-* | ||
| ``` | ||
|
|
||
| #### Override karma config | ||
|
|
||
| You can override karma config by adding a `karmaConfig` property to your `stryker.conf.js` file. | ||
|
|
||
| For example: | ||
|
|
||
| ```javascript | ||
| karmaConfig: { | ||
| browsers: ['Chrome'], | ||
| frameworks: ['mocha'] | ||
| } | ||
| ``` | ||
|
|
||
| *Note*: Whichever testFramework you use should also be reflected in the `testFramework` property of stryker itself. For example: `testFramework: 'mocha'` | ||
|
|
||
| Not all karma config can be overriden, as Stryker requires specific functionality from the testRunner to do its magic. | ||
|
|
||
| The following Karma config options cannot be overridden: | ||
|
|
||
| * `files`: The karma-runner will fill this based on the `files` and `mutate` configuration in the `stryker-conf.js` file (or your `karma.conf.js` file when using the *automatic setup*). | ||
| * `coverageReporter`: For the initial test run, the `stryker-karma-runner` will use its own coverage reporter. For testing the mutants, however, it will be disabled. | ||
| * `autoWatch`, `singleRun`: Stryker needs full control on when to run the karma tests | ||
|
|
||
| ### Full config example | ||
|
|
||
| ```javascript | ||
| // stryker.conf.js | ||
| exports = function(config){ | ||
| config.set({ | ||
| // ... | ||
| testRunner: 'karma', | ||
| testFramework: 'jasmine', | ||
| karmaConfig: { // these are the defaults | ||
| browsers: ['PhantomJS'], | ||
| frameworks: ['jasmine'], | ||
| autoWatch: false, | ||
| singleRun: false | ||
| }, | ||
| plugins: ['stryker-karma-runner'] // Or leave out the plugin list entirely to load all stryker-* plugins directly | ||
| // ... | ||
| }); | ||
| } | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| Use Stryker as you normally would. | ||
| See [http://stryker-mutator.github.io](http://stryker-mutator.github.io) for more info. | ||
|
|
||
| ### Debugging | ||
|
|
||
| As Stryker runs karma in its own process, its logging output will be consumed by Stryker. | ||
|
|
||
| To see all logging from karma, set the log level to `trace` in `stryker.conf.js`. | ||
|
|
||
| ```javascript | ||
| // stryker.conf.js | ||
| exports = function(config){ | ||
| config.set({ | ||
| // ... | ||
| logLevel: 'trace' | ||
| // ... | ||
| }); | ||
| } | ||
| ``` | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Loading the plugin