buster.captureServer

Version
0.2 (2011-10-04)
Module
require("buster-capture-server");

Loads resource sets (HTML, CSS, JavaScript, images, ...) into browsers (captured slaves) via an HTTP API and/or a JavaScript API.

Resource sets are loaded into the server as sessions. Sessions are queued, so that when the current session ends, the next session in the queue is immediately loaded into the captured slaves.

Buster.JS creates one session for each test run.

buster-capture-server is also completely reusable, and has no direct knowledge of running tests. One example is Slidebuster, where a session is a presentation, and the generic messaging in buster-capture-server is used to synchronize current slide state across the captured browsers.

Creating a server

var server = bCaptureServer.create()

Creates a new server instance.

server.attach(httpServer)

Attaches the buster-capture-server to a Node.js HTTP server.

The procedure injects itself into the request event of the http server so that the "request" handlers only run for requests that buster-server doesn't handle. Other than that, buster-server leaves the HTTP server untouched.

Capturing slaves

A captured slave is (typically) a browser that is "captured" by loading an HTML page with a communication channel (event emitter) between the buster-capture-server and the browser. When the browser receives the event for loading a session, a frame gets its src attribute set to the URL that corresponds to the root HTML page for that session.

For Buster.JS testing, the root document contains the specified testbed or the default plain testbed, and <script> tags for all the loadable scripts from the config file.

Framesets are used so that the session root HTML page spans the full viewport of the captured slave (browser).

server.oncapture = function(req, res, slave){}

This property is required.

Capturing a slave is always done via a GET request to the capturePath.

You are required to define the behaviour of the HTTP request.

server.oncapture = function (req, res, slave) {
    res.writeHead(302, {"Location": slave.url});
    res.end();
}

It's important that you end() the request. If you don't, it'll hang indefinitely and the browser will eventually time out.

You are free to do whatever you want here. You don't have to redirect to slave.url. You can for example redirect to a page that lets you configure additional options for the captured browser, and then redirect to the slave.url when you're done.

server.capturePath = "/capture"

The default value of this property is "/capture".

server.header(height, resourceSet)

Adds a header to captured browsers. It is positioned above the main session frame, and is given the height specified. The document in the frame will be the root resource in the resource set. It will stay in place when you change session, and even when there's no session in progress.

TODO: Write about the environment. We probably want messaging here, for example.

Sessions

A session is the unit of work in a buster-capture-server.

When a session is created, it is added to the bottom of the session queue. As soon as there are no other sessions above it in the queue, it is loaded into the captured slaves. When there are no other sessions in the queue, the session loads immediately upon creation.

Loading a session into a captured slave basically means setting the src attribute of the session frame in the captured slave to the path to the root HTML document of the session's resource set.

var sess = server.createSession(sessionPayload)

Creates a new session.

Session payload

The session payload is an object where the following properties are used:

resourceSet: A resource set instance. The root HTML page is the resource with the path "/". It is assumed to be a HTML document. Everything in load of the resource set is added as script tags to the root HTML page. All other resources are made available to the session. Relative paths should be used since resources are not served on root and the context path isn't available to the session.

joinable: Defaults to true. A joinable session will be loaded in slaves that are captured while the session is active. In Buster.JS it's set to false for test run sessions.

POST /sessions

Creates a new session with HTTP.

Request body

A JSON encoded sessionPayload. Instead of a resource set instance, a resource set object payload is instead used. TODO: Link to the docs for resource set object payloads.

Response body

A JSON encoded object with relevant information about the newly created session.

{
    "id": session-id,
    "contextPath": session-context-path
    "resourceSetPath": session-resource-set-path
    "bayeuxClientPath": session-bayeux-path,
}

Response status code

201
Session successfully created and will be loaded immediately due to empty session queue.
202
Session successfully created and was queued.

server.destroySession(sess.id)

Stops the session with the given ID.

DELETE /session-context-path

Stops the session with the given context path.

sess.id

The ID of the session. TODO: Write about how this ID is useful for faye messaging.

sess.contextPath

Used to reference the session by URL, such as when killing the session.

sess.resourceSetPath

The path to the root resource of the sessions resource set.

sess.bayeuxClientPath

The URL to use for creating Faye/bayeux clients. This property is also available on the server itself if you have programmatic access to it. The URL is the same for all sessions.

sess.publish(url, message)

Publishes a message on the session. Will be published to all captured slaves with the session loaded.

sess.subscribe(url, handler)

Subscribes on messages sent to the session. Will receive messages from all captured slaves with the session loaded, as well as the session object self.

Session browser runtime

These global variables are loaded before everything else in your session.

buster

The buster-core module in its entirety.

buster.publish(url, message)

Publishes messages on the session event emitter. Will be published to all captured slaves listening on the event, including the sender, as well as the session object on the server itself.

buster.subscribe(url, handler)

Subscribes to messages on the session event emitter. Will be published to all other captured slaves as well as the session object on the server itself.

Captured slave

A captured slave is the object that represents a captured slave/browser. You usually only deal with this object in server.oncapture.

slave.url

The URL to open in the browser in order to initiate the capture and load the frameset.