feat(server): improve public api

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

docs/dev/04-public-api.md

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

lib/cli.js

@@ -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) {
@@ -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)

lib/index.js

@@ -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
+}