Skip to content

Commit

Permalink
feat(server): improve public api
Browse files Browse the repository at this point in the history
This adds a slew of new api possibilities to the server. All main
events
from the `globalEmitter` are now emitted on the `server` instances and
publicly available.
For a list of available events see the docs file.

BREAKING CHANGE:

The public api interface has changed to a constructor form. To upgrade
change

```javascript
var server = require(‘karma’).server
server.start(config, done)
```

to

```javascript
var Server = require(‘karma’).Server
var server = new Server(config, done)
server.start()
```

Closes #1037, #1482, #1467
  • Loading branch information
dignifiedquire committed Jul 8, 2015
1 parent 48e3000 commit 82cbbad
Show file tree
Hide file tree
Showing 5 changed files with 291 additions and 134 deletions.
97 changes: 85 additions & 12 deletions docs/dev/04-public-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,107 @@ 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.


## karma.server
## karma.Server(options, [callback=process.exit])

### **server.start(options, [callback=process.exit])**
### Constructor

```javascript
var Server = require('karma').Server
var server = new Server({port: 9876}, function(exitCode) {
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
```

### **server.start()**

Equivalent of `karma start`.

```javascript
var server = require('karma').server;
server.start({port: 9876}, function(exitCode) {
console.log('Karma has exited with ' + exitCode);
process.exit(exitCode);
});
server.start()
```

### Events

The `server` object is an [`EventEmitter`](https://nodejs.org/docs/latest/api/events.html#events_class_events_eventemitter). You can simply listen to events like this:

```javascript
server.on('browser_register', function (browser) {
console.log('A new browser was registered')
})
```

### `browser_register`
**Arguments:**

* `browser`: The browser instance

A new browser was opened, but is not ready yet.

### `browser_error`
**Arguments:**

* `browser`: The browser instance
* `error`: The error that occured

There was an error on this browser instance.

### `browser_start`
**Arguments:**

* `browser`: The browser instance
* `info`: Details about the run

A test run is beginning in this browser.

### `browser_complete`
**Arguments:**

* `browser`: The browser instance
* `result`: Test results

A test run has completed in this browser.

### `browsers_change`
**Arguments:**

* `browsers`: A collection of browser instances

The list of browers has changed.

#### `browsers_ready`

All browsers are ready for execution

### `run_start`
**Arguments:**

* `browsers`: A collection of browser instances on which tests are excuted

A test run starts.

### `run_complete`
**Arguments:**

* `browsers`: A collection of browser instances
* `results`: A list of results

A test run was completed.

## karma.runner

### **runner.run(options, [callback=process.exit])**

Equivalent of `karma run`.

```javascript
var runner = require('karma').runner;
var runner = require('karma').runner
runner.run({port: 9876}, function(exitCode) {
console.log('Karma has exited with ' + exitCode);
process.exit(exitCode);
});
console.log('Karma has exited with ' + exitCode)
process.exit(exitCode)
})
```

## Callback function notes

- If there is an error, the error code will be provided as the second parameter to the error callback.
- If there is an error, the error code will be provided as the second parameter to the error callback.
6 changes: 4 additions & 2 deletions lib/cli.js
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
var path = require('path')
var optimist = require('optimist')
var fs = require('fs')

var Server = require('./server')
var helper = require('./helper')
var constant = require('./constants')
var fs = require('fs')

var processArgs = function (argv, options, fs, path) {
if (argv.help) {
Expand Down Expand Up @@ -217,7 +219,7 @@ exports.run = function () {

switch (config.cmd) {
case 'start':
require('./server').start(config)
new Server(config).start()
break
case 'run':
require('./runner').run(config)
Expand Down
29 changes: 25 additions & 4 deletions lib/index.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,26 @@
// index module
exports.VERSION = require('./constants').VERSION
exports.server = require('./server')
exports.runner = require('./runner')
exports.launcher = require('./launcher')

var constants = require('./constants')
var Server = require('./server')
var runner = require('./runner')
var launcher = require('./launcher')

// TODO: remove in 1.0
var oldServer = {
start: function () {
throw new Error(
'The api interface has changed. Please use \n' +
' server = new Server(config, [done])\n' +
' server.start()\n' +
'instead.'
)
}
}

module.exports = {
VERSION: constants.VERSION,
Server: Server,
runner: runner,
launcher: launcher,
server: oldServer
}
Loading

0 comments on commit 82cbbad

Please sign in to comment.