buster.captureServer

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

Automates loading of a web pages (sessions) into multiple captured browsers (slaves). The session creator gets access to messaging so data can be transmitted to and from the browsers.

Creating the server

var server = bCaptureServer.create()

Creates a new server instance.

server.attach(httpServer)

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

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

Listening to events

The server has a global event hub, as well as one event hub per session. The global path is /messaging. The paths for the individual sessions is available as .bayeuxClientPath on the individual sessions.

Bayeux is a standardized protocol for messaging, but Faye specific features is used so you're expected to use Faye for creating messaging clients.

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.capturePath = path

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

server.header(height, resourceSet)

All slaves will have a header of height pixels with the provided resource set loaded into it.

Performing capture

To capture a browser, perform a HTTP GET request to the capturePath of the server. This will load the slave page and notify when the browser is ready to accept new sessions.

Event: /capture

Emitted when new slaves are created (a browser has been captured) and the slave is ready to accept sessions.

Sessions

Sessions are the units 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 session = server.createSession(payload)

Creates a new session.

POST /sessions

Creates a new session over HTTP. Responds with 201 Created if the session will start immediately, or 202 Accepted if it is queued.

server.destroySession(id)

Unqueues a queued session or ends the current session.

DELETE session.path

Unqueues a queued session or ends the current session.

Event: /session/create (session)

Emitted with a session object when a session is created.

Event: /session/start (session)

Emitted with a session object when a session has started (became current) in all slaves.

Session payload

The payload passed to createSession or POST /sessions.

resourceSet

A serialized resource set.

joinable

Set to true or false. Defaults to true. When false, a slave that is created while the session is in progress will not get the session loaded into it.

Session objects

The session object emitted from events and returned from createSession.

id

The id of the session. Used in the APIs to delete the session, and more.

path

The path to the session. Used in the HTTP APis to delete the session, and more.

bayeuxClientPath

The path to the bayeux messaging for the session.

resourcesPath

The path where the resource set is mounted.

Browser environment

In addition to the resource set itself, some additional internal JavaScript is loaded into the session's web page.

buster.publish(event, data)

Publishes an event on the session event scope.

buster.subscribe(event, handler)

Subscribes to an event on the session event scope.