Writing Queen Scripts

Queen Scripts are JavaScript applications that use the Queen to execute code on browsers. This document outlines how to create one.

A Queen Script is a Node.js module, which exports out one function which takes in one parameter. When the script runs, an initialized Queen object will be passed to this function, you may interact with this object using the Queen API and use it to issue requests to captured browsers (called "worker providers" in the documentation).

Download this repo and checkout the examples folder for various example scripts.

// Example Queen Script
module.exports = function(queen){
    // We're going to use this "config" object to define
    // the workforce we want. A "workforce" is a collection of browsers
    // which run the client-side code defined in the "run" variable.
    var config = {
        run: ['http://queenjs.com/ping-client.js'],
		
        // This tells queen to run this script on any
        // browsers which are connected now and in the future
        populate: "continuous", 
		
        // By default, queen will kill a workforce (i.e. this job)
        // if there are no browsers connected, this tells queen
        // that it's ok to idle and wait for browsers to connect.
        killOnStop: false,
		
        // This function gets called right before a browser starts 
        // running the client script.
        handler: function(worker){ 
            // Worker can be thought of as the browser.
            worker.on('message', function(num){
                queen.log(worker.provider + " is at " + num + "\n");
				
                // If the browser has pinged us 10 times, kill it.
                if(num === 10){
                    worker.kill();
                } else {
                    // Echo the number back to the worker
                    worker(num);
                }
            });
		
            // Tell the worker to start at 0
            worker(0);
        }
    }

    // This will create our workforce and set things in to motion.
    // Note that the full Queen API is available to use through this object,
    // and we could call it multiple times to create multiple workforces if we wanted
    queen(config);
};

Workforce Configuration Options

In the last line of the example we pass in a config object to queen. This is the "workforce configuration" it tells Queen how to run our script and on which browsers. Here are the configuration options available for this object. More detailed information is available in the API documentation.

run

A string or an array of strings of URLs for scripts the workers (browsers) will load.

killOnStop true by default

Whether the workforce should kill itself as soon as it's worker count reaches 0. If you set this to false, the workforce will just idle when no workers are connected.

populate "once" by default

"manual": The workforce will not be automatically populated. "once": The workforce will be populated by all currently available worker providers. "continuous": The workforce will be populated by all currently available worker providers AND all future worker providers.

timeout Infinity by default

The number of milliseconds each worker has until it's .kill()'d automatically.

handler [Function]

A function which gets called with workers whenever they are added to the workforce.

stop [Function]

A function which gets called when the workforce no longer has any workers connected (when it's idling). If killOnStop is true, the workforce will die immediately afterwards.

autoStart true by default

Whether the workforce should start immediately. If not, need to manually call the .start() method.

filter [Function(WorkerProviderAttributes)]

A filter function which takes in a WorkerProvider Attributes object and returns true or false given a worker provider attributes object, determining whether the workforce should attempt to get workers from that provider.

// In this example, we start a queen server to run server-example.js continuously on
// any browser which connects to the server that has the canvas capability
module.exports = function(queen){
    queen({
        filter: function(browser){ return browser.capabilities.canvas === true; }
        run: "http://queenjs.com/server-example.js",
        populate: "continuous",
        killOnStop: false
    });
};

uniqueness [Function(WorkerProviderAttributes)]

A function which WorkerProvider Attributes object and returns a string to used to determine if two browsers should be considered the "same" and therefore, only one will end up executing the test. This means if the function returned the browser family name, only one browser connected per browser family will run this script.