From e19feaa5540b7336858bcb653f2b6c03ae537f14 Mon Sep 17 00:00:00 2001 From: dignifiedquire Date: Thu, 11 Jun 2015 11:20:33 +0200 Subject: [PATCH] docs: Cleanup documentation and add running coffee example --- .gitignore | 1 + .npmignore | 2 +- .travis.yml | 2 + README.md | 256 ++---------------------------- docs/configuration.md | 222 ++++++++++++++++++++++++++ examples/coffee/karma.conf.coffee | 45 ++++++ examples/coffee/package.json | 20 +++ examples/coffee/plus.coffee | 7 + examples/coffee/test.coffee | 7 + gruntfile.js | 7 +- package.json | 8 +- 11 files changed, 327 insertions(+), 250 deletions(-) create mode 100644 docs/configuration.md create mode 100644 examples/coffee/karma.conf.coffee create mode 100644 examples/coffee/package.json create mode 100644 examples/coffee/plus.coffee create mode 100644 examples/coffee/test.coffee diff --git a/.gitignore b/.gitignore index 3c3629e..d1a9230 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ node_modules +examples/coffee/coverage diff --git a/.npmignore b/.npmignore index 49f3ec8..cc011f0 100644 --- a/.npmignore +++ b/.npmignore @@ -1,5 +1,5 @@ .* test - +examples/coffee/coverage Gruntfile.coffee CONTRIBUTING.md diff --git a/.travis.yml b/.travis.yml index 3566402..24222e3 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,6 +7,8 @@ node_js: # Make sure we have new NPM. before_install: + - export DISPLAY=:99.0 + - sh -e /etc/init.d/xvfb start - npm install -g npm - npm config set loglevel warn diff --git a/README.md b/README.md index 34cbb15..00431ad 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,11 @@ npm install karma karma-coverage --save-dev ## Configuration -The following code shows a simple usage: +For configuration details see [docs/configuration](docs/configuration.md). + +## Examples + +### Basic ```javascript // karma.conf.js @@ -47,45 +51,12 @@ module.exports = function(config) { }); }; ``` +### CoffeeScript -Example use with a CoffeeScript project: - -```javascript -// karma.conf.js -module.exports = function(config) { - config.set({ - files: [ - 'src/**/*.coffee', - 'test/**/*.coffee' - ], +For an example on how to use with [CoffeeScript](http://coffeescript.org/) +see [examples/coffee](examples/coffee). - // coverage reporter generates the coverage - reporters: ['progress', 'coverage'], - - preprocessors: { - // source files, that you wanna generate coverage for - // do not include tests or libraries - // (these files will be instrumented by Istanbul via Ibrik unless - // specified otherwise in coverageReporter.instrumenter) - 'src/**/*.coffee': ['coverage'], - - // note: project files will already be converted to - // JavaScript via coverage preprocessor. - // Thus, you'll have to limit the CoffeeScript preprocessor - // to uncovered files. - 'test/**/*.coffee': ['coffee'] - }, - - // optionally, configure the reporter - coverageReporter: { - type : 'html', - dir : 'coverage/' - } - }); -}; -``` - -Here is an advanced usage of karma-coverage, using severals reporters: +### Advanced, multiple reporters ```javascript // karma.conf.js @@ -119,215 +90,6 @@ module.exports = function(config) { }); ``` -### Options -#### type -**Type:** String - -**Description:** Specify a reporter type. - -**Possible Values:** - * `html` (default) - * `lcov` (lcov and html) - * `lcovonly` - * `text` - * `text-summary` - * `cobertura` (xml format supported by Jenkins) - * `teamcity` (code coverage System Messages for TeamCity) - * `json` (json format supported by [`grunt-istanbul-coverage`](https://github.com/daniellmb/grunt-istanbul-coverage)) - -#### dir -**Type:** String - -**Description:** This will be used to output coverage reports. When - you set a relative path, the directory is resolved against the `basePath`. - -#### subdir -**Type:** String - -**Description**: This will be used in complement of the `coverageReporter.dir` -option to generate the full output directory path. By default, the output -directory is set to `./config.dir/BROWSER_NAME/`, this option allows you to -custom the second part. You can either pass a `string` or a `function` which will be -called with the browser name passed as the only argument. - -```javascript -coverageReporter: { - dir: 'coverage', - subdir: '.' - // Would output the results into: .'/coverage/' -} -``` - -```javascript -coverageReporter: { - dir: 'coverage', - subdir: 'report' - // Would output the results into: .'/coverage/report/' -} -``` - -```javascript -coverageReporter: { - dir: 'coverage', - subdir: function(browser) { - // normalization process to keep a consistent browser name accross different - // OS - return browser.toLowerCase().split(/[ /-]/)[0]; - } - // Would output the results into: './coverage/firefox/' -} -``` - -#### file - -If you choose the `cobertura`, `lcovonly`, `teamcity`, `text` or `text-summary` reporters, you may set the `file` option to specify an output file. - -```javascript -coverageReporter: { - type : 'text', - dir : 'coverage/', - file : 'coverage.txt' -} -``` - -#### check -**Type:** Object - -**Description:** This will be used to configure minimum threshold enforcement for coverage results. If the thresholds are not met, karma will return failure. Thresholds, when specified as a positive number are taken to be the minimum percentage required. When a threshold is specified as a negative number it represents the maximum number of uncovered entities allowed. - -For example, `statements: 90` implies minimum statement coverage is 90%. `statements: -10` implies that no more than 10 uncovered statements are allowed. - -`global` applies to all files together and `each` on a per-file basis. A list of files or patterns can be excluded from enforcement via the `exclude` property. On a per-file or pattern basis, per-file thresholds can be overridden via the `overrides` property. - -```javascript -coverageReporter: { - check: { - global: { - statements: 50, - branches: 50, - functions: 50, - lines: 50, - excludes: [ - 'foo/bar/**/*.js' - ] - }, - each: { - statements: 50, - branches: 50, - functions: 50, - lines: 50, - excludes: [ - 'other/directory/**/*.js' - ], - overrides: { - 'baz/component/**/*.js': { - statements: 98 - } - } - } - } -} -``` - -#### watermarks -**Type:** Object - -**Description:** This will be used to set the coverage threshold colors. The first number is the threshold between Red and Yellow. The second number is the threshold between Yellow and Green. - -```javascript -coverageReporter: { - watermarks: { - statements: [ 50, 75 ], - functions: [ 50, 75 ], - branches: [ 50, 75 ], - lines: [ 50, 75 ] - } -} -``` - -#### includeAllSources -**Type:** Boolean - -You can opt to include all sources files, as indicated by the coverage preprocessor, in your code coverage data, even if there are no tests covering them. (Default `false`) - -```javascript -coverageReporter: { - type : 'text', - dir : 'coverage/', - file : 'coverage.txt', - includeAllSources: true -} -``` - -#### sourceStore -**Type:** istanbul.Store - -You can opt to specify a source store allowing for external coverage collectors access to the instrumented code. - -```javascript -coverageReporter: { - type : 'text', - dir : 'coverage/', - file : 'coverage.txt', - sourceStore : require('istanbul').Store.create('fslookup') -} -``` - -#### multiple reporters -You can use multiple reporters, by providing array of options. - -```javascript -coverageReporter: { - reporters:[ - {type: 'html', dir:'coverage/'}, - {type: 'teamcity'}, - {type: 'text-summary'} - ], -} -``` - -#### instrumenter -Karma-coverage can infers the instrumenter regarding of the file extension. - It is possible to override this behavior and point out an - instrumenter for the files matching a specific pattern. - To do so, you need to declare an object under with the keys represents the - pattern to match, and the instrumenter to apply. The matching will be done - using [minimatch](https://github.com/isaacs/minimatch). - If two patterns match, the last one will take the precedence. - -For example you can use [Ibrik](https://github.com/Constellation/ibrik) (an - [Istanbul](https://github.com/gotwarlost/istanbul) analog for - CoffeeScript files) with: - -```javascript -coverageReporter: { - instrumenters: { ibrik : require('ibrik') } - instrumenter: { - '**/*.coffee': 'ibrik' - }, - // ... -} -``` - -You can pass options additional options to specific instrumenter with: - -```javascript -var to5Options = { experimental: true }; - -// [...] - -coverageReporter: { - instrumenters: { isparta : require('isparta') }, - instrumenter: { - '**/*.js': 'isparta' - }, - instrumenterOptions: { - isparta: { to5 : to5Options } - } -} -``` - - ---- For more information on Karma see the [homepage]. diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..ca1d61a --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,222 @@ +# Configuration + +### `type` + +**Type:** String + +**Description:** Specify a reporter type. + +**Possible Values:** + * `html` (default) + * `lcov` (lcov and html) + * `lcovonly` + * `text` + * `text-summary` + * `cobertura` (xml format supported by Jenkins) + * `teamcity` (code coverage System Messages for TeamCity) + * `json` (json format supported by [`grunt-istanbul-coverage`](https://github.com/daniellmb/grunt-istanbul-coverage)) + +### `dir` + +**Type:** String + +**Description:** This will be used to output coverage reports. When + you set a relative path, the directory is resolved against the `basePath`. + +### `subdir` + +**Type:** String + +**Description**: This will be used in complement of the `coverageReporter.dir` +option to generate the full output directory path. By default, the output +directory is set to `./config.dir/BROWSER_NAME/`, this option allows you to +custom the second part. You can either pass a `string` or a `function` which will be +called with the browser name passed as the only argument. + +```javascript +coverageReporter: { + dir: 'coverage', + subdir: '.' + // Would output the results into: .'/coverage/' +} +``` + +```javascript +coverageReporter: { + dir: 'coverage', + subdir: 'report' + // Would output the results into: .'/coverage/report/' +} +``` + +```javascript +coverageReporter: { + dir: 'coverage', + subdir: function(browser) { + // normalization process to keep a consistent browser name accross different + // OS + return browser.toLowerCase().split(/[ /-]/)[0]; + } + // Would output the results into: './coverage/firefox/' +} +``` + +### `file` + +**Type:** String + +**Description:** If you use one of these reporters, `cobertura`, `lcovonly`, `teamcity`, `text` or `text-summary`,you may set the `file` option to specify the output file. + +```javascript +coverageReporter: { + type : 'text', + dir : 'coverage/', + file : 'coverage.txt' +} +``` + +### `check` + +**Type:** Object + +**Description:** This will be used to configure minimum threshold enforcement for coverage results. If the thresholds are not met, karma will return failure. Thresholds, when specified as a positive number are taken to be the minimum percentage required. When a threshold is specified as a negative number it represents the maximum number of uncovered entities allowed. + +For example, `statements: 90` implies minimum statement coverage is 90%. `statements: -10` implies that no more than 10 uncovered statements are allowed. + +`global` applies to all files together and `each` on a per-file basis. A list of files or patterns can be excluded from enforcement via the `exclude` property. On a per-file or pattern basis, per-file thresholds can be overridden via the `overrides` property. + +```javascript +coverageReporter: { + check: { + global: { + statements: 50, + branches: 50, + functions: 50, + lines: 50, + excludes: [ + 'foo/bar/**/*.js' + ] + }, + each: { + statements: 50, + branches: 50, + functions: 50, + lines: 50, + excludes: [ + 'other/directory/**/*.js' + ], + overrides: { + 'baz/component/**/*.js': { + statements: 98 + } + } + } + } +} +``` + +### `watermarks` + +**Type:** Object + +**Description:** This will be used to set the coverage threshold colors. The first number is the threshold between Red and Yellow. The second number is the threshold between Yellow and Green. + +```javascript +coverageReporter: { + watermarks: { + statements: [ 50, 75 ], + functions: [ 50, 75 ], + branches: [ 50, 75 ], + lines: [ 50, 75 ] + } +} +``` + +### `includeAllSources` + +**Type:** Boolean + +**Description:** You can opt to include all sources files, as indicated by the coverage preprocessor, in your code coverage data, even if there are no tests covering them. (Default `false`) + +```javascript +coverageReporter: { + type : 'text', + dir : 'coverage/', + file : 'coverage.txt', + includeAllSources: true +} +``` + +### `sourceStore` + +**Type:** istanbul.Store + +**Description:** You can opt to specify a source store allowing for external coverage collectors access to the instrumented code. + +```javascript +coverageReporter: { + type : 'text', + dir : 'coverage/', + file : 'coverage.txt', + sourceStore : require('istanbul').Store.create('fslookup') +} +``` + +### `reporters` + +**Type:** Array of Objects + +**Description:** You can use multiple reporters, by providing array of options. + +```javascript +coverageReporter: { + reporters:[ + {type: 'html', dir:'coverage/'}, + {type: 'teamcity'}, + {type: 'text-summary'} + ], +} +``` + +### `instrumenter` + +**Type:** Object + +**Description:** Karma-coverage can infers the instrumenter regarding of the file extension. It is possible to override this behavior and point out an +instrumenter for the files matching a specific pattern. +To do so, you need to declare an object under with the keys represents the +pattern to match, and the instrumenter to apply. The matching will be done +using [minimatch](https://github.com/isaacs/minimatch). +If two patterns match, the last one will take the precedence. + +For example you can use [Ibrik](https://github.com/Constellation/ibrik) (an +[Istanbul](https://github.com/gotwarlost/istanbul) analog for +CoffeeScript files) with: + +```javascript +coverageReporter: { + instrumenters: { ibrik : require('ibrik') } + instrumenter: { + '**/*.coffee': 'ibrik' + }, + // ... +} +``` + +You can pass options additional options to specific instrumenter with: + +```javascript +var to5Options = { experimental: true }; + +// [...] + +coverageReporter: { + instrumenters: { isparta : require('isparta') }, + instrumenter: { + '**/*.js': 'isparta' + }, + instrumenterOptions: { + isparta: { to5 : to5Options } + } +} +``` diff --git a/examples/coffee/karma.conf.coffee b/examples/coffee/karma.conf.coffee new file mode 100644 index 0000000..9a74f15 --- /dev/null +++ b/examples/coffee/karma.conf.coffee @@ -0,0 +1,45 @@ +module.exports = (config) -> + config.set + frameworks: ['mocha'] + + files: [ + '*.coffee' + ] + + browsers: ['Firefox'] + + coffeePreprocessor: + options: + sourceMap: true + + preprocessors: + # source files, that you wanna generate coverage for + # do not include tests or libraries + # (these files will be instrumented by Istanbul via Ibrik unless + # specified otherwise in coverageReporter.instrumenter) + 'plus.coffee': 'coverage' + + # note: project files will already be converted to + # JavaScript via coverage preprocessor. + # Thus, you'll have to limit the CoffeeScript preprocessor + # to uncovered files. + 'test.coffee': 'coffee' + + coverageReporter: + type: 'text-summary' + instrumenters: + ibrik : require('ibrik') + instrumenter: + '**/*.coffee': 'ibrik' + + # coverage reporter generates the coverage + reporters: ['dots', 'coverage'] + + plugins: [ + require('../../lib/index') + 'karma-mocha' + 'karma-coffee-preprocessor' + 'karma-firefox-launcher' + ] + + singleRun: true diff --git a/examples/coffee/package.json b/examples/coffee/package.json new file mode 100644 index 0000000..385a90c --- /dev/null +++ b/examples/coffee/package.json @@ -0,0 +1,20 @@ +{ + "name": "karma-coverage-coffee-example", + "version": "1.0.0", + "description": "Demonstrate the usage of karma-coverage with CoffeeScript", + "main": "", + "scripts": { + "test": "./node_modules/karma/bin/karma start" + }, + "author": "Friedel Ziegelmayer ", + "license": "MIT", + "dependencies": {}, + "devDependencies": { + "karma": "latest", + "karma-mocha": "latest", + "karma-coffee-preprocessor": "latest", + "karma-firefox-launcher": "latest", + "coffee-script": "latest", + "ibrik": "^2.0.0" + } +} diff --git a/examples/coffee/plus.coffee b/examples/coffee/plus.coffee new file mode 100644 index 0000000..81816e0 --- /dev/null +++ b/examples/coffee/plus.coffee @@ -0,0 +1,7 @@ +# Some code under test +window.plus = (a, b) -> + a + b + +# this one is not coveraged +window.minus = (a, b) -> + a - b diff --git a/examples/coffee/test.coffee b/examples/coffee/test.coffee new file mode 100644 index 0000000..c218739 --- /dev/null +++ b/examples/coffee/test.coffee @@ -0,0 +1,7 @@ +describe 'plus', -> + + it 'should pass', -> + true is true + + it 'should work', -> + plus(1, 2) is 3 diff --git a/gruntfile.js b/gruntfile.js index 9ecc48b..04cbce5 100644 --- a/gruntfile.js +++ b/gruntfile.js @@ -28,6 +28,11 @@ module.exports = function (grunt) { ] } }, + karma: { + coffee: { + configFile: 'examples/coffee/karma.conf.coffee' + } + }, eslint: { target: [ 'lib/*.js', @@ -39,7 +44,7 @@ module.exports = function (grunt) { require('load-grunt-tasks')(grunt) - grunt.registerTask('test', ['simplemocha']) + grunt.registerTask('test', ['simplemocha', 'karma']) grunt.registerTask('default', ['eslint', 'test']) grunt.registerTask('release', 'Bump the version and publish to NPM.', function (type) { diff --git a/package.json b/package.json index 0ccef83..aa42ea7 100644 --- a/package.json +++ b/package.json @@ -34,11 +34,17 @@ "grunt-bump": "^0.3.1", "grunt-conventional-changelog": "^1.2.2", "grunt-eslint": "^14.0.0", + "grunt-karma": "^0.11.0", "grunt-npm": "^0.0.2", "grunt-simple-mocha": "^0.4.0", - "karma": "^0.12.0", + "ibrik": "^2.0.0", + "karma": "^0.12.36", + "karma-coffee-preprocessor": "^0.2.1", + "karma-firefox-launcher": "^0.1.6", + "karma-mocha": "^0.1.10", "load-grunt-tasks": "^3.2.0", "lodash": "^3.9.3", + "mocha": "^2.2.5", "mocks": "0.0.11", "sinon": "^1.14.1", "sinon-chai": "^2.8.0"