diff --git a/docs/about/01-versioning.md b/docs/about/01-versioning.md index 7cec438df..7fb3eb06d 100644 --- a/docs/about/01-versioning.md +++ b/docs/about/01-versioning.md @@ -1,8 +1,8 @@ Karma uses [Semantic Versioning] with a little exception: -- even versions (eg. `0.6.x`, `0.8.x`) are considered stable - no breaking changes or new features, only bug fixes will pushed into this branch, +- even versions (eg. `0.6.x`, `0.8.x`) are considered stable - no breaking changes or new features, only bug fixes will be pushed into this branch - odd versions (eg. `0.7.x`, `0.9.x`) are unstable - anything can happen ;-) -Therefore it is recommended to rely on the latest stable version, which gives you automatic bug fixes, but does not break you: +Therefore, it is recommended that you rely on the latest stable (even) version, which will give you automatic bug fixes, but will not break your test setup: ```javascript { "devDependencies": { diff --git a/docs/about/03-migration.md b/docs/about/03-migration.md index de726018f..cd74cfff4 100644 --- a/docs/about/03-migration.md +++ b/docs/about/03-migration.md @@ -3,7 +3,7 @@ pageTitle: Migration from v0.10 The good thing is that you don't have to migrate everything at once. You can leave all the existing projects using an older version of Karma and only use the latest -version for the new projects. Or you can migrate the existing projects one at the time... +version for the new projects. Alternatively, you can migrate the existing projects one at a time... Anyway, this migration should be easy ;-) so let's get started... @@ -16,8 +16,9 @@ This will install the latest version of Karma and also update `package.json` of ## Install missing plugins -Karma does not ship with any "default" plugin anymore. -For existing projects, this should not cause any problems as NPM (when installing Karma 0.10) probably added these "default" plugins into `package.json` as regular dependencies. +Karma does not ship with any "default" plugins anymore. +For existing projects, this should not cause any problems as NPM (when updating Karma to 0.10 using +`npm install karma --save-dev`) added these "default" plugins into `package.json` as regular dependencies. For new projects, just remember you have to install all the plugins you need. These are the "default" plugins that were removed: - karma-jasmine - karma-requirejs @@ -33,7 +34,7 @@ For new projects, just remember you have to install all the plugins you need. Th Karma does not put the `karma` command in your system PATH anymore. If you want to use the `karma` command, please install the command line interface (`karma-cli`). -You probably have `karma` package installed globally, in which case you should remove it first: +You probably have the `karma` package installed globally, in which case you should remove it first: ```bash npm remove -g karma ``` @@ -45,11 +46,14 @@ npm install -g karma-cli ## Default configuration -`autoWatch` is true by default, so if you don't wanna use it make sure you set it to `false`. But hey, give it a shot first, it's really awesome to run your tests on every save! +`autoWatch` is true by default, so if you don't wanna use it make sure you set it to `false`. +But hey, give it a shot first, it's really awesome to run your tests on every save! ## NPM complaining -NPM is sometimes finicky so if you encounter errors such as "unsatisfied peer dependency", just try to remove all the packages (`rm -rf ./node_modules`) and install again. +In some cases NPM can run into dependency tree issues during the migration process. If you are faced +with an "unsatisfied peer dependency" error, removing all of the packages (`rm -rf ./node_modules`) and installing +them again should clear up the issue. If you have any other issuses, please ask on the [mailing list]. diff --git a/docs/config/01-configuration-file.md b/docs/config/01-configuration-file.md index 27d4fecc7..645f57b21 100644 --- a/docs/config/01-configuration-file.md +++ b/docs/config/01-configuration-file.md @@ -1,7 +1,7 @@ ## Overview In order to serve you well, Karma needs to know about your project in order to test it -and this is done via a configuration file. The easiest way to generate initial configuration file -is using `karma init` command. This page lists all the available configuration options. +and this is done via a configuration file. The easiest way to generate an initial configuration file +is by using the `karma init` command. This page lists all of the available configuration options. Note: Most of the framework adapters, reporters, preprocessors and launchers needs to be loaded as [plugins]. @@ -31,9 +31,10 @@ module.exports = (config) -> ``` ## File Patterns -All of the configuration options which specify file paths use the [minimatch][minimatch] library to facilitate flexible but concise file expressions, so you can easily list all the files you want to include, along with excluding the files that need to be skipped. +All of the configuration options, which specify file paths, use the [minimatch][minimatch] library to facilitate flexible +but concise file expressions so you can easily list all of the files you want to include and exclude. -You can find details of each option in the following section, but this is the list of options that utilize minimatch expressions: +You can find details about each configuration option in the section below. The following options utilize minimatch expressions: * `exclude` * `files` @@ -46,7 +47,7 @@ Examples: * `**/(foo|bar).js`: In all subdirectories, all "foo.js" or "bar.js" files ## Configuration Options -These are all the available configuration options. +These are all of the available configuration options. ## autoWatch **Type:** Boolean @@ -55,8 +56,7 @@ These are all the available configuration options. **CLI:** `--auto-watch`, `--no-auto-watch` -**Description:** Enable or disable watching files and executing the tests - whenever one of these files changes. +**Description:** Enable or disable watching files and executing the tests whenever one of these files changes. ## autoWatchBatchDelay @@ -87,7 +87,9 @@ relative path then it will be resolved to the `__dirname` of the configuration f **Description:** How long does Karma wait for a browser to reconnect (in ms). -With a flaky connection it is pretty common that browser disconnects but the actual execution is running without any problems. Karma does not treat a disconnection as immediate failure and rather wait `browserDisconnectTimeout` ms. If the browser reconnect during that time, everything is fine. +With a flaky connection it is pretty common that the browser disconnects, but the actual test execution is still running +without any problems. Karma does not treat a disconnection as immediate failure and will wait `browserDisconnectTimeout` (ms). +If the browser reconnects during that time, everything is fine. ## browserDisconnectTolerance @@ -97,9 +99,9 @@ With a flaky connection it is pretty common that browser disconnects but the act **Description:** The number of disconnections tolerated. -The `disconnectTolerance` value represents the maximum number of tries a browser will attempt in case of disconnection. -Usually any disconnection is considered as a failure, but this option allows to define a tolerance level when there is -a flaky network link between the karma server and the browsers. +The `disconnectTolerance` value represents the maximum number of tries a browser will attempt in the case of a disconnection. +Usually any disconnection is considered a failure, but this option allows you to define a tolerance level when there is +a flaky network link between the Karma server and the browsers. ## browserNoActivityTimeout @@ -107,9 +109,10 @@ a flaky network link between the karma server and the browsers. **Default:** `10000` -**Description:** How long does Karma wait for a message from a browser before disconnecting it (in ms). +**Description:** How long will Karma wait for a message from a browser before disconnecting from it (in ms). -If, during the execution, Karma does not receive any message from a browser within `browserNoActivityTimeout` ms, it will disconnect the browser. +If, during test execution, Karma does not receive any message from a browser within `browserNoActivityTimeout` +(ms), it will disconnect from the browser. ## browsers @@ -121,20 +124,20 @@ If, during the execution, Karma does not receive any message from a browser with **Possible Values:** - * `Chrome` (comes installed with Karma) - * `ChromeCanary` (comes installed with Karma) - * `PhantomJS` (comes installed with Karma) - * `Firefox` (requires karma-firefox-launcher plugin) - * `Opera` (requires karma-opera-launcher plugin) - * `Internet Explorer` (requires karma-ie-launcher plugin) - * `Safari` (requires karma-safari-launcher plugin) + * `Chrome` (launcher comes installed with Karma) + * `ChromeCanary` (launcher comes installed with Karma) + * `PhantomJS` (launcher comes installed with Karma) + * `Firefox` (launcher requires karma-firefox-launcher plugin) + * `Opera` (launcher requires karma-opera-launcher plugin) + * `Internet Explorer` (launcher requires karma-ie-launcher plugin) + * `Safari` (launcher requires karma-safari-launcher plugin) **Description:** A list of browsers to launch and capture. When Karma starts up, it will also start up each browser -which is placed within this setting. Once Karma is shut down, it will shut down these -browsers as well. You can capture any browser manually just by opening the browser and visiting the URL where +which is placed within this setting. Once Karma is shut down, it will shut down these +browsers as well. You can capture any browser manually by opening the browser and visiting the URL where the Karma web server is listening (by default it is `http://localhost:9876/`). -See [config/browsers] for more. Additional launchers can be defined through [plugins]. +See [config/browsers] for more information. Additional launchers can be defined through [plugins]. ## captureTimeout @@ -156,7 +159,7 @@ it again and, after three attempts to capture it, Karma will give up. **CLI:** All arguments after `--` (only when using `karma run`) **Description:** When `karma run` is passed additional arguments on the command-line, they -are passed through to the test adapter as ``karma.config.args` (an array of strings). +are passed through to the test adapter as `karma.config.args` (an array of strings). The `client.args` option allows you to set this value for actions other than `run`. How this value is used is up to your test adapter - you should check your adapter's @@ -169,7 +172,7 @@ documentation to see how (and if) it uses this value. **CLI:** `--colors`, `--no-colors` -**Description:** Enable or disable colors in the output (reporters and logs). +**Description:** Enable or disable colors in the output (reporters and logs). ## exclude @@ -195,7 +198,7 @@ See [config/files] for more information. **Default:** `[]` -**Description:** List of frameworks you want to use. Typically, you will set this to `['jasmine']`, `['mocha']` or `['qunit']`... +**Description:** List of test frameworks you want to use. Typically, you will set this to `['jasmine']`, `['mocha']` or `['qunit']`... Please note just about all frameworks in Karma require an additional plugin/framework library to be installed (via NPM). @@ -233,8 +236,7 @@ Additional information can be found in [plugins]. **Default:** `[{type: 'console'}]` -**Description:** A list of log appenders to be used. See the - documentation for [log4js] for more information. +**Description:** A list of log appenders to be used. See the documentation for [log4js] for more information. ## plugins @@ -243,9 +245,9 @@ Additional information can be found in [plugins]. **Default:** `['karma-*']` **Description:** List of plugins to load. A plugin can be a string (in which case it will be required by Karma) or an inlined plugin - Object. -By default, Karma loads all siblink modules, that match `karma-*`. +By default, Karma loads all sibling NPM modules which have a name starting with `karma-*`. -Please note just about all plugins in Karma require an additional library to be installed (via NPM). +Note: Just about all plugins in Karma require an additional library to be installed (via NPM). See [plugins] for more information. @@ -257,7 +259,7 @@ See [plugins] for more information. **CLI:** `--port 9876` -**Description:** The port where the webserver will be listening. +**Description:** The port where the web server will be listening. ## preprocessors @@ -269,7 +271,7 @@ See [plugins] for more information. Preprocessors can be loaded through [plugins]. -Please note just about all preprocessors in Karma (other than CoffeeScript and some other defaults) +Note: Just about all preprocessors in Karma (other than CoffeeScript and some other defaults) require an additional library to be installed (via NPM). Be aware that preprocessors may be transforming the files and file types that are available at run time. For instance, @@ -284,24 +286,26 @@ Click here for more information. ## proxies **Type:** Object -**Default:** `{}` +**Default:** `{}` **Description:** A map of path-proxy pairs. **Example:** - ```javascript - proxies: { - '/static': 'http://gstatic.com', - '/web': 'http://localhost:9000' - }, - ``` +```javascript +proxies: { +'/static': 'http://gstatic.com', +'/web': 'http://localhost:9000' +}, +``` + ## proxyValidateSSL **Type:** Boolean -**Default:** `true` +**Default:** `true` + +**Description:** Whether or not Karma or any browsers should raise an error when an inavlid SSL certificate is found. -**Description:** Whether or not karma or any browsers should raise an error when an inavlid SSL certificate is found. ## reportSlowerThan **Type:** Number @@ -328,7 +332,7 @@ This is disabled by default (since the default value is 0). Additional reporters, such as `growl`, `junit`, `teamcity` or `coverage` can be loaded through [plugins]. -Please note just about all additional reporters in Karma (other than progress) require an additional library to be installed (via NPM). +Note: Just about all additional reporters in Karma (other than progress) require an additional library to be installed (via NPM). ## singleRun @@ -358,9 +362,10 @@ between browsers and the testing server). **Default:** `true` -**Description:** Run the tests inside an iframe or a new window +**Description:** Run the tests inside an iFrame or a new window -If true, Karma runs the tests inside an iframe. If false, Karma runs the tests in a new window. Some tests may not run in an iFrame and may need a new window to run. +If true, Karma runs the tests inside an iFrame. If false, Karma runs the tests in a new window. Some tests may not run in an +iFrame and may need a new window to run. ## client.captureConsole **Type:** Boolean @@ -376,7 +381,7 @@ If true, Karma runs the tests inside an iframe. If false, Karma runs the tests i **Description:** The base url, where Karma runs. -All the Karma's urls get prefixed with the `urlRoot`. This is helpful when using proxies, as +All of Karma's urls get prefixed with the `urlRoot`. This is helpful when using proxies, as sometimes you might want to proxy a url that is already taken by Karma. diff --git a/docs/config/02-files.md b/docs/config/02-files.md index 17c258950..797121c2d 100644 --- a/docs/config/02-files.md +++ b/docs/config/02-files.md @@ -2,30 +2,32 @@ ## Pattern matching and `basePath` -- All of the relative patterns will get resolved to `basePath` first. +- All of the relative patterns will get resolved using the `basePath` first. - If the `basePath` is a relative path, it gets resolved to the - directory where the configuration file is. + directory where the configuration file is located. - Eventually, all the patterns will get resolved into files using [glob], so you can use [minimatch] expressions like `test/unit/**/*.spec.js`. + ## Ordering -- The order of patterns determines the order of files in which they - are included in the browser. +- The order of patterns determines the order in which files are included in the browser. - Multiple files matching a single pattern are sorted alphabetically. - Each file is included exactly once. If multiple patterns match the same file, it's included as if it only matched the first pattern. + ## Included, served, watched Each pattern is either a simple string or an object with four properties: ### `pattern` +* **Type.** String +* **No Default.** * **Description.** The pattern to use for matching. This property is mandatory. ### `watched` * **Type.** Boolean * **Default.** `true` -* **Description.** If `autoWatch` is `true` all files that have set `watched` to true will be - watched for changes. +* **Description.** If `autoWatch` is `true` all files that have set `watched` to true will be watched for changes. ### `included` * **Type.** Boolean @@ -39,11 +41,13 @@ Each pattern is either a simple string or an object with four properties: * **Default.** `true` * **Description.** Should the files be served by Karma's webserver? + ## Preprocessor transformations Depending on preprocessor configuration, be aware that files loaded may be transformed and no longer available in their native format. For instance, if html2js preprocessor is enabled, the actual .html files are no longer served - but rather available as `window.__html__['my.html']`. Read more about [preprocessors]. + ## Complete example Here is a complete example showing the different options possible: ```javascript diff --git a/docs/config/03-browsers.md b/docs/config/03-browsers.md index c8ce8c645..552df8207 100644 --- a/docs/config/03-browsers.md +++ b/docs/config/03-browsers.md @@ -1,13 +1,14 @@ -Capturing browsers on your own is kinda tedious and time consuming, -so Karma can do that for you. Just simply add into the configuration file: +Capturing browsers on your own can be a tedious and time consuming task, +so Karma can automate this for you. Simply add the browsers you would like to +capture into the configuration file: ```javascript browsers: ['Chrome'] ``` -Then, Karma will take care of autocapturing these browsers, as well as killing them. +Then, Karma will take care of auto-capturing these browsers, as well as killing them. -Note: Most of the browser launchers needs to be loaded as [plugins]. +Note: Most of the browser launchers need to be loaded as [plugins]. ## Available browser launchers - [Chrome and Chrome Canary] (install karma-chrome-launcher) @@ -23,7 +24,7 @@ Note: Most of the browser launchers needs to be loaded as [plugins]. Here's an example of how to add Firefox to your testing suite: ```bash -# Install it first with NPM: +# Install the launcher first with NPM: $ npm install karma-firefox-launcher --save-dev ``` @@ -43,9 +44,12 @@ Of course, you can write [custom plugins] too! ## Capturing any browser manually -You can also capture browsers by simply opening `http://:/`, where `` is the IP address or hostname of the machine where Karma server is running and `` is the port where Karma server is listening (by default it's `9876`). With the default settings in place, just point your browser to `http://localhost:9876/`. +You can also capture browsers by simply opening `http://:/`, where `` is the IP +address or hostname of the machine where the Karma server is running and `` is the port where the Karma +server is listening (by default it's `9876`). With the default settings in place, just point your browser to `http://localhost:9876/`. -This allows you to capture a browser on any device such as a tablet or a phone, that is on the same network as the machine running Karma (or using a local tunnel). +This allows you to capture a browser on any device, such as a tablet or a phone, that is on the same network +as the machine running Karma (or using a local tunnel). ## Configured launchers diff --git a/docs/config/04-preprocessors.md b/docs/config/04-preprocessors.md index 1735b4e80..e1d2a0dee 100644 --- a/docs/config/04-preprocessors.md +++ b/docs/config/04-preprocessors.md @@ -9,8 +9,9 @@ preprocessors: { '**/*.html': ['html2js'] }, ``` -Note the multiple expressions referencing the "coffee" preprocessor, as a preprocessor can be listed more than once, -as another way to specify multiple file path expressions. + +Note: There are multiple expressions referencing the "coffee" preprocessor in this example, as a preprocessor +can be listed more than once as another way to specify multiple file path expressions. Note: Most of the preprocessors need to be loaded as [plugins]. @@ -75,8 +76,7 @@ the `files` configuration. * First the file paths are expanded to an absolute path, based on the `basePath` configuration and the directory of the configuration file. See [files] for more information on that. -* Then the newly expanded path is matched using [minimatch] against the - specified key. +* Then the newly expanded path is matched using [minimatch] against the specified key. So for example the path `/my/absolute/path/to/test/unit/file.coffee` matched against the key `**/*.coffee` would return `true`, but matched against just `*.coffee` it would diff --git a/docs/config/05-plugins.md b/docs/config/05-plugins.md index 2117ddabf..3c0bd79c1 100644 --- a/docs/config/05-plugins.md +++ b/docs/config/05-plugins.md @@ -3,7 +3,7 @@ In fact, all the existing preprocessors, reporters, browser launchers and framew ## Installation -Karma plugins are NPM modules, so the recommended way is to keep all the plugins your project requires in `package.json`: +Karma plugins are NPM modules, so the recommended way to install them are as project dependencies in your `package.json`: ```javascript { @@ -16,21 +16,22 @@ Karma plugins are NPM modules, so the recommended way is to keep all the plugins } ``` -Therefore, a simple way how to install a plugin is +Therefore, a simple way to install a plugin is: + ```bash npm install karma- --save-dev ``` ## Loading Plugins -By default, Karma loads all sibling NPM modules which names start with `karma-*`. +By default, Karma loads all sibling NPM modules which have a name starting with `karma-*`. You can also explicitly list plugins you want to load via the `plugins` configuration setting. The configuration value can either be a string (module name), which will be required by Karma, or an object (inlined plugin). ```javascript plugins: [ - // these plugins will be require() by Karma + // Karma will require() these plugins 'karma-jasmine', 'karma-chrome-launcher' @@ -40,7 +41,7 @@ plugins: [ ] ``` -There are already many [existing plugins]. Of course, you write [your own plugins] too! +There are already many [existing plugins]. Of course, you can write [your own plugins] too! [existing plugins]: https://npmjs.org/browse/keyword/karma-plugin [your own plugins]: ../dev/plugins.html