Most of the time, you will be using Karma directly from the command line. You can, however, call Karma programmatically from your node module. Here is the public API.
- Returns:
Serverinstance.
Notice the capital 'S' on require('karma').Server.
The following still works, but the way it behaves is deprecated and will be changed in a future major version.
var Server = require('karma').Server
var karmaConfig = {port: 9876}
var server = new Server(karmaConfig, function(exitCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})const karma = require('karma')
const parseConfig = karma.config.parseConfig
const Server = karma.Server
parseConfig(
null,
{ port: 9876 },
{ promiseConfig: true, throwErrors: true }
).then(
(karmaConfig) => {
const server = new Server(karmaConfig, function doneCallback(exitCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
},
(rejectReason) => { /* respond to the rejection reason error */ }
);Equivalent of karma start.
server.start()Trigger a file list refresh. Returns a promise.
server.refreshFiles()Trigger a file refresh. Returns a promise.
server.refreshFile('src/js/module-dep.js')The server object is an EventEmitter. You can simply listen to events like this:
server.on('browser_register', function (browser) {
console.log('A new browser was registered')
})Arguments:
port: Port number
Begin accepting connections on the specified port.
Arguments:
browser: The browser instance
A new browser was opened, but is not ready yet.
Arguments:
browser: The browser instanceerror: The error that occurred
There was an error in this browser instance.
Arguments:
browser: The browser instanceinfo: Details about the run
A test run is beginning in this browser.
Arguments:
browser: The browser instanceresult: Test results
A test run has completed in this browser.
Arguments:
browsers: A collection of browser instances
The list of browsers has changed.
All browsers are ready for execution
Arguments:
browsers: A collection of browser instances on which tests are executed
A test run starts.
Arguments:
browsers: A collection of browser instancesresults: A list of results
This event gets triggered whenever all the browsers, which belong to a test run, finish. For example, on a run that has 3 browsers, one would expect 3 browser_complete events before the run_complete one.
- Returns:
EventEmitter
The equivalent of karma run.
The following still works, but the way it behaves is deprecated and will be changed in a future major version.
var runner = require('karma').runner
runner.run({port: 9876}, function(exitCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})const karma = require('karma')
karma.config.parseConfig(
null,
{ port: 9876 },
{ promiseConfig: true, throwErrors: true }
).then(
(karmaConfig) => {
karma.runner.run(karmaConfig, function doneCallback(exitCode, possibleErrorCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
},
(rejectReason) => { /* respond to the rejection reason error */ }
);The callback receives the exit code as the first argument.
If there is an error, the error code will be provided as the second parameter to the error callback.
runner.run() returns an EventEmitter which emits a progress event passing
the reporter output as a Buffer object.
You may listen for that event to print the reporter output to the console:
runner.run({port: 9876}).on('progress', function(data) {
process.stdout.write(data)
})This function will signal a running server to stop. The equivalent of
karma stop.
The following still works, but the way it behaves is deprecated and will be changed in a future major version.
var stopper = require('karma').stopper
stopper.stop({port: 9876}, function(exitCode) {
if (exitCode === 0) {
console.log('Server stop as initiated')
}
process.exit(exitCode)
})const karma = require('karma')
karma.config.parseConfig(
null,
{ port: 9876 },
{ promiseConfig: true, throwErrors: true }
).then(
(karmaConfig) => {
karma.stopper.stop(karmaConfig, function doneCallback(exitCode, possibleErrorCode) {
if (exitCode === 0) {
console.log('Server stop as initiated')
}
process.exit(exitCode)
})
},
(rejectReason) => { /* respond to the rejection reason error */ }
);The callback receives the exit code as the first argument.
If there is an error, the error code will be provided as the second parameter to the error callback.
This function will load given config file and returns a filled config object. This can be useful if you want to integrate karma into another tool and want to load the karma config while honoring the karma defaults.
The following still works, but the way it behaves is deprecated and will be changed in a future major version.
const cfg = require('karma').config;
const path = require('path');
// Read karma.conf.js, but override port with 1337
const karmaConfig = cfg.parseConfig(
path.resolve('./karma.conf.js'),
{ port: 1337 }
);The new behavior in the future will involve throwing exceptions instead of exiting the process and aynchronous config files will be supported through the use of promises.
const cfg = require('karma').config;
const path = require('path');
// Read karma.conf.js, but override port with 1337
cfg.parseConfig(
path.resolve('./karma.conf.js'),
{ port: 1337 },
{ promiseConfig: true, throwErrors: true }
).then(
(karmaConfig) => { /* use the config with the public API */ },
(rejectReason) => { /* respond to the rejection reason error */ }
);- Type: String |
null|undefined - Default Value:
undefined
A string representing a file system path pointing to the config file whose
default export is a function that will be used to set Karma configuration
options. This function will be passed an instance of the Config class as its
first argument. If this option is not provided, then only the options provided
by the cliOptions argument will be set.
- JavaScript must use CommonJS modules.
- ECMAScript modules are not currently supported by Karma when using
JavaScript.
- Other formats, such as TypeScript, may support ECMAScript modules.
- Type: Object |
null|undefined - Default Value:
undefined
An object whose values will take priority over options set in the config file. The config object passed to function exported by the config file will already have these options applied. Any changes the config file makes to these options will effectively be ignored in the final configuration.
Supports all the same options as the config file and is applied using the same
config.set() method.
The expected source of this argument is parsed command line options, but programatic users may construct this object or leave it out entirely.
- Type: Object |
null|undefined - Default Value:
undefined
parseOptions is an object whose properties are configuration options that
allow additional control over parsing and opt-in access to new behaviors or
features.
These options are only related to parsing configuration files and object and are not related to the configuration of Karma itself.
- Type: Boolean
- Default Value:
false
When parseOptions.promiseConfig === true, then parseConfig will return a
promise instead of a configuration object.
When this option is true, then the function exported by the config file may
return a promise. The resolution of that promise indicates that all asynchronous
activity has been completed. Internally, the resolved/fulfilled value is
ignored. As with synchronous usage, all changes to the config object must be
done with the config.set() method.
If the function exported by the config file does not return a promise, then parsing is completed and an immediately fulfilled promise is returned.
Whether the function exported by the config file returns a promise or not, the
promise returned by parseConfig() will resolve with a parsed configuration
object, an instance of the Config class, as the value.
In most cases, parseOptions.throwErrors = true should also be set. This
disables process exiting and allows errors to result in rejected promises.
- Type: Boolean
- Default Value:
false
In the past, parseConfig() would call process.exit(exitCode) when it
encountered a critical failure. This meant that your own code had no way of
responding to failures before the Node.js process exited.
By passing parseOptions.throwErrors = true, parseConfig() will disable
process exiting.
For synchronous usage, it will throw an exception instead of exiting the process. Your code can then catch the exception and respond how ever it needs to.
If the asynchronous API (parseOptions.promiseConfig = true) is being used,
then parseOptions.throwErrors = true allows the promise to be rejected
instead of exiting the process.
The current version of karma
The default port used for the karma server
The default hostname used for the karma server
The default address use for the karma server to listen on
The value for disabling logs
The value for the log error level
The value for the log warn level
The value for the log info level
The value for the log debug level
An array of log levels in descending order, i.e. LOG_DISABLE, LOG_ERROR, LOG_WARN, LOG_INFO, and LOG_DEBUG
The default color pattern for log output
The default pattern for log output without color
The default console appender
The exit code