Skip to content
This repository has been archived by the owner on Feb 19, 2021. It is now read-only.

docs(readme): Document automatic setup #15

Merged
merged 4 commits into from
Dec 30, 2016
Merged

docs(readme): Document automatic setup #15

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3dd02bd
chore(package.json): Add npm start script
nicojs Dec 30, 2016
82269a5
docs(readme): Document automatic setup
nicojs Dec 30, 2016
8e8dd97
docs(readme): Minor typo's and fixes
nicojs Dec 30, 2016
971ba83
fix(README): Improve wording and grammar
simondel Dec 30, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 20 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,18 @@

A plugin to use the karma test runner in [Stryker](https://stryker-mutator.github.io), the JavaScript mutation testing framework

## Warning

The stryker-karma-runner is available from stryker v0.4.0 onward.

## Install

Install stryker-karma-runner from your project folder:
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 pluggin for `stryker` to enable `karma` as a test runner. As such you should install the correct versions of the dependencies:
The `stryker-karma-runner` is a pluggin for `stryker` to enable `karma` as a test runner.
Copy link
Contributor

@philippw philippw Dec 30, 2016 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

plugging -> plugin

As such, you should make sure you have the correct versions of it's dependencies installed:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

its


* `karma`
* `stryker-api`
Expand All @@ -33,24 +30,25 @@ These are marked as `peerDependencies` of `stryker-karma-runner` so you get a wa

## Configuring

You can either configure the karma test runner from the `stryker.conf.js` file or from the command line. This readme describes how to do it via the config file.
You can either configure the karma test runner from the `stryker.conf.js` file or from the command line.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can either configure the karma test runner using the command line or by providing a the stryker.conf.js file.

This README describes how to do use the `stryker.conf.js` config file.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This README describes how to use the stryker.conf.js config file.


### Load the plugin
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Loading the plugin


In order to use the `stryker-karma-runner` it must me loaded in the stryker mutation testing framework via the stryker configuration.
Easiest is to *leave out* the `plugins` section from your config entirely. That way, all node_modules starting with `stryker-` will be loaded.
Easiest is to *not have a `plugins` section* from your config file. That way, all node_modules starting with `stryker-` will be loaded.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Specify the use of the karma testRunner: `testRunner: 'karma'`.
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* `karma.conf.js` file.
You can configure stryker to use *your very own* `karma.conf.js` file.

```javascript
// Stryker.conf.js
Expand All @@ -66,18 +64,19 @@ module.exports = function (config) {
}
```

This will configure 3 things for you:
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`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Karma's files option will be used to configure the files in Stryker. This relives you from the burden to keep the list of files in sync in stryker.conf.js and karma.conf.js.

* Karma's `exclude` option will be used to ignore files in Stryker (using `!` to ignore them)
* Other karma config will be copied to the `karmaConfig` option in stryker config. These will be used by the `stryker-karma-runner` during mutation testing.
* Other karma config will be copied to the `karmaConfig` option in Stryker config. They will be picked up by the `stryker-karma-runner` during mutation testing.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • All remaining karma configs will be ...

* **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 karma config* (see next section)
**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:

When the Stryker uses the karma test runner, it uses these default karma config settings:

```javascript
{
Expand Down Expand Up @@ -118,10 +117,11 @@ karmaConfig: {
*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.
Karma config that *cannot* be overriden:

* `files`: The karma-runner will fill this based on the `files` and `filesToMutate` configuration in the `stryker-conf.js` file.
* `coverageReporter`: This will be enabled for the initial test run, disabled for testing the mutants.
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`: Stryker-karma-runner will use its own coverage reporter for the initial test run and disabled it for testing the mutants.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Expand Down Expand Up @@ -152,8 +152,9 @@ See [http://stryker-mutator.github.io](http://stryker-mutator.github.io) for mor

### Debugging

By default, karma logging will be swallowed.
Set log level to `trace` in `stryker.conf.js` to see all the karma output.
As Stryker runs karma in it's own process, it's logging output will be consumed Stryker.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[...] 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
Expand Down