Configuration File

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 an initial configuration file is by using the karma init command. This page lists all of the available configuration options.

The Karma configuration file can be written in JavaScript or CoffeeScript and is loaded as a regular Node.js module. Within the configuration file, the configuration code is put together by setting module.exports to point to a function which accepts one argument: the configuration object.

// karma.conf.js
module.exports = function(config) {
  config.set({
    basePath: '../..',
    frameworks: ['jasmine'],
    //...
  });
};

# karma.conf.coffee
module.exports = (config) ->
  config.set
    basePath: '../..'
    frameworks: ['jasmine']
    # ...

File Patterns #

All of the configuration options, which specify file paths, use the 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 about each configuration option in the section below. The following options utilize minimatch expressions:

• exclude
• files
• preprocessors

Examples:

• **/*.js: All files with a "js" extension in all subdirectories
• **/!(jquery).js: Same as previous, but excludes "jquery.js"
• **/(foo|bar).js: In all subdirectories, all "foo.js" or "bar.js" files

Configuration Options #

These are all of the available configuration options.

autoWatch #

Type: Boolean

Default: true

CLI: --auto-watch, --no-auto-watch

Description: Enable or disable watching files and executing the tests whenever one of these files changes.

autoWatchBatchDelay #

Type: Number

Default: 250

Description: When Karma is watching the files for changes, it tries to batch multiple changes into a single run so that the test runner doesn't try to start and restart running tests more than it should. The configuration setting tells Karma how long to wait (in milliseconds) after any changes have occurred before starting the test process again.

basePath #

Type: String

Default: ''

Description: The root path location that will be used to resolve all relative paths defined in files and exclude. If the basePath configuration is a relative path then it will be resolved to the __dirname of the configuration file.

browserDisconnectTimeout #

Type: Number

Default: 2000

Description: How long does Karma wait for a browser to reconnect (in ms).

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 #

Type: Number

Default: 0

Description: The number of disconnections tolerated.

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 #

Type: Number

Default: 10000

Description: How long will Karma wait for a message from a browser before disconnecting from it (in ms).

If, during test execution, Karma does not receive any message from a browser within browserNoActivityTimeout (ms), it will disconnect from the browser.

browsers #

Type: Array

Default: []

CLI: --browsers Chrome,Firefox

Possible Values:

• 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 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 information. Additional launchers can be defined through plugins.

captureTimeout #

Type: Number

Default: 60000

Description: Timeout for capturing a browser (in ms).

The captureTimeout value represents the maximum boot-up time allowed for a browser to start and connect to Karma. If any browser does not get captured within the timeout, Karma will kill it and try to launch it again and, after three attempts to capture it, Karma will give up.

client.args #

Type: Array

Default: undefined

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). 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 documentation to see how (and if) it uses this value.

colors #

Type: Boolean

Default: true

CLI: --colors, --no-colors

Description: Enable or disable colors in the output (reporters and logs).

exclude #

Type: Array

Default: []

Description: List of files/patterns to exclude from loaded files.

files #

Type: Array

Default: []

Description: List of files/patterns to load in the browser.

See config/files for more information.

frameworks #

Type: Array

Default: []

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).

Additional information can be found in plugins.

hostname #

Type: String

Default: 'localhost'

Description: Hostname to be used when capturing browsers.

logLevel #

Type: Constant

Default: config.LOG_INFO

CLI: --log-level debug

Possible values:

• config.LOG_DISABLE
• config.LOG_ERROR
• config.LOG_WARN
• config.LOG_INFO
• config.LOG_DEBUG

Description: Level of logging.

loggers #

Type: Array

Default: [{type: 'console'}]

Description: A list of log appenders to be used. See the documentation for log4js for more information.

plugins #

Type: Array

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 sibling NPM modules which have a name starting with karma-*.

See plugins for more information.

port #

Type: Number

Default: 9876

CLI: --port 9876

Description: The port where the web server will be listening.

preprocessors #

Type: Object

Default: {'**/*.coffee': 'coffee'}

Description: A map of preprocessors to use.

Preprocessors can be loaded through plugins.

Be aware that preprocessors may be transforming the files and file types that are available at run time. For instance, if you are using the "coverage" preprocessor on your source files, if you then attempt to interactively debug your tests, you'll discover that your expected source code is completely changed from what you expected. Because of that, you'll want to engineer this so that your automated builds use the coverage entry in the "reporters" list, but your interactive debugging does not.

Click here for more information.

proxies #

Type: Object

Default: {}

Description: A map of path-proxy pairs.

Example:

proxies: {
'/static': 'http://gstatic.com',
'/web': 'http://localhost:9000'
},

proxyValidateSSL #

Type: Boolean

Default: true

Description: Whether or not Karma or any browsers should raise an error when an inavlid SSL certificate is found.

reportSlowerThan #

Type: Number

Default: 0

Description: Karma will report all the tests that are slower than given time limit (in ms). This is disabled by default (since the default value is 0).

reporters #

Type: Array

Default: ['progress']

CLI: --reporters progress,growl

Possible Values:

• dots
• progress

Description: A list of reporters to use.

Additional reporters, such as growl, junit, teamcity or coverage can be loaded through plugins.

singleRun #

Type: Boolean

Default: false

CLI: --single-run, no-single-run

Description: Continuous Integration mode.

If true, Karma will start and capture all configured browsers, run tests and then exit with an exit code of 0 or 1 depending on whether all tests passed or any tests failed.

transports #

Type: Array

Default: ['websocket', 'flashsocket', 'xhr-polling', 'jsonp-polling']

Description: An array of allowed transport methods between the browser and testing server. This configuration setting is handed off to socket.io (which manages the communication between browsers and the testing server).

client.useIframe #

Type: Boolean

Default: true

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.

client.captureConsole #

Type: Boolean

Default: true

Description: Capture all console output and pipe it to the terminal.

urlRoot #

Type: String

Default: '/'

Description: The base url, where Karma runs.

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.