Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Merge pull request #8 from Krinkle/master
issue #7: Update for TestSwarm 1.0 and some other minor fixes
  • Loading branch information
clarkbox committed Apr 28, 2012
2 parents 425e7b5 + 18d8562 commit 5673931
Show file tree
Hide file tree
Showing 3 changed files with 393 additions and 237 deletions.
95 changes: 52 additions & 43 deletions README.md
@@ -1,57 +1,44 @@
# [testswarm-browserstack](http://jquery.com/)
This is a light weight integration layer between [TestSwarm](https://github.com/jquery/testswarm) and [BrowserStack](http://www.browserstack.com/). Use it to spawn BrowserStack workers needed by TestSwarm on demand.

This script is currently compatible with:
* [TestSwarm](https://github.com/jquery/testswarm) 1.0.0-alpha or higher
* [BrowserStack API](https://github.com/browserstack/api) v1


## Howto use CLI:
<pre>
testswarm-browserstack.cli.js --swarmUrl "swarm.jquery.org" --spawnUrl "http://swarm.jquery.org/run/" --user "browserstackUserName" --pass "myPass@#$" --clientTimeout 15 --run --kill
testswarm-browserstack.cli.js --swarmUrl "http://swarm.jquery.org" --swarmRunUrl "http://swarm.jquery.org/run/exampleClientName" --user "BrowserStackUser" --pass "myBrowserStackPass@#$" --run --kill
</pre>

This above command will spawn (via --run) AND kill (via `--kill`) BrowSack workers as indicated by the TestSwarm `getneeded` endpoint. This command should be executed on a regular interval, via CRON or other scheduler - for more short term requirements, see [node-cli-repeater](https://github.com/clarkbox/node-repeater).
This above command will spawn (via `--run`) AND kill (via `--kill`) BrowserStack workers as indicated by the TestSwarm `swarmstate` API. This command should be executed on a regular interval, via cron or other scheduler - for more short term requirements, see [node-cli-repeater](https://github.com/clarkbox/node-repeater).


In most cases, the `--kill` option should always accompany the `--run` option. This will ensure workers are not running idle, and depend on `--clientTimeout` option for works to die and allow other queued workers to start.
In most cases, the `--kill` option should always accompany the `--run` option. This will ensure workers are not running idle (although eventually browserstack will still terminate idle workers after `clientTimeout`).

## This repo contains two parts:

1. [testswarm-browserstack.js](https://github.com/clarkbox/testswarm-browserstack/blob/master/testswarm-browserstack.js) - abstraction of TestSwarm "getNeeded" endpoint, and Scott Gonz�lez's BrowserStack API. Use it to spawn BrowserStack workers required by TestSwarm.
2. [testswarm-browserstack.cli.js](https://github.com/clarkbox/testswarm-browserstack/blob/master/testswarm-browserstack.cli.js) - nodejs CLI interface wrapper around it all. Allows for scripted or easier manual invokation of browsers.
1. [testswarm-browserstack.js](https://github.com/clarkbox/testswarm-browserstack/blob/master/testswarm-browserstack.js) - Abstraction of TestSwarm API, and Scott González's BrowserStack API. Use it to spawn BrowserStack workers to keep your TestSwarm populated.
2. [testswarm-browserstack.cli.js](https://github.com/clarkbox/testswarm-browserstack/blob/master/testswarm-browserstack.cli.js) - nodejs CLI interface wrapper around it all. Allows for scripted or easier manual invocation of browsers.

### Dependencies:
* [commander](https://github.com/visionmedia/commander.js)
* [async](https://github.com/caolan/async)
* [request](https://github.com/mikeal/request)
* [node-browserstack](https://github.com/scottgonzalez/node-browserstack)


## testswarm-browserstack.js
--------------------------------------
### run():
* Start the needed workers. If `--kill` option is set, will kill any running workers not needed. be sure to set options first via `testswarm-browserstack.options({...my options...})`.

### getNeeded(callback):
* Returns the TestSwarm [useragent ID's](https://github.com/jquery/testswarm/blob/master/config/useragents.sql)
* parameters:
* function callback(error, useragnets)
* error (object) - null if none
* useragnets (interger array) - JSON array of useragendIDs

### killWorker(workerId):
Kill a single worker. Calls BrowserStack.terminateWorker()
* parameters:
* workerId (integer) - BrowserStack Worker ID as returned by startWorker

### killAll()
Kill all workers running on BrowserStack.

### options([options])
Call this first! get/set the options required to run. Passing in an object literal will set the options. calling without arguments will return the current options.
#### Example options:
<pre>
{
user: 'myUserId',
pass: 'myPassWurd',
swarmUrl: 'swarm.jquery.org',
spawnUrl: 'http://swarm.jquery.org/run/_SWARM_USERNAME_',
swarmUrl: 'http://ci.example.org/testswarm',
swarmRunUrl: 'http://c.example.org/testswarm/run/_SWARM_USERNAME_',
verbose: false,
kill: true,
clientTimeout: 6000
Expand All @@ -60,11 +47,32 @@ Call this first! get/set the options required to run. Passing in an object liter
#### Option Definition:
* user - BrowserStack username
* pass - BrowserStack password
* swarmUrl - the URL of the TestSwarm instance (where the getneeded endpoint lives)
* spawnUrl - the URL to open when a BrowserStack worker starts
* verbose - output more debug messages (all output via console.log())
* kill - kill workers that are no longer in getNeeded output
* clientTimeout - number of seconds to run a worker
* swarmHost - Hostname of TestSwarm server (without protocol or slash)
* swarmPath - Path on the server to TestSwarm (without trailing slash)
* swarmRunUrl - URL to the TestSwarm run page (including client name), for BrowserStack workers to open
* verbose - Output more debug messages (all output via console.log)
* kill - Kill BrowserStack workers if they are no longer needed
* clientTimeout - Number of minutes to run each client


### getSwarmState(callback):
* Get statistics about the TestSwarm, keyed by [browser ID](https://github.com/jquery/testswarm/blob/master/config/useragents.ini)
* parameters:
* function callback(error, swarmState)
* error (object|null) - Object with 'code' and 'info' property (TestSwarm API error codes)
* swarmState (object|undefined) - Swarm state object with all browsers and their pending runs, and active clients.

### run():
* Start the needed workers. If `--kill` option is set, will also kill any running workers that are no longer needed. Be sure to set options first via `testswarm-browserstack.options({...my options...})`.

### killWorker(workerId):
Kill a single worker. Calls BrowserStack.terminateWorker()
* parameters:
* workerId (integer) - BrowserStack Worker ID as returned by startWorker.

### killAll()
Kill all workers running on BrowserStack.



## testswarm-browserstack.cli.js
Expand All @@ -76,17 +84,18 @@ this is a nodejs CLI interface wrapper around testswarm-browserstack.js. Use --h

Options:

-h, --help output usage information
-V, --version output the version number
--killAll kill all workers now
--killWorker [workerid] kill worker
--getNeeded return the workers required by TestSwarm
-k, --kill if --run specified, kill workers if they are no longer needed.
-r, --run start up workers required by BrowserStack
-u, --user [username] BrowserStack username
-p, --pass [password] BrowserStack password
-s, --swarmUrl [url] TestSwarm URL of getneeded call
-w, --spawnUrl [url] URL that BrowserStack workers will open
-v, --verbose print more info
-t, --clientTimeout [min] number of minuets to run each client (BrowserStack timeout) DEFAULTS 10min.
-h, --help output usage information
-V, --version output the version number
--killAll Kill all BrowserStack workers
--killWorker [workerid] Kill a BrowserStack worker by its worker ID
--getNeeded Shows a list of browser IDs that have pending jobs in TestSwarm
--kill Kill BrowserStack workers if they are no longer needed (Only if --run is also specified)
--run Start new workers in BrowserStack based on the swarm state
-u, --user [username] BrowserStack username
-p, --pass [password] BrowserStack password
-v, --verbose Output more debug messages (all output via console.log)
--swarmUrl [url] URL of TestSwarm root (without trailing slash)
--swarmRunUrl [url] URL to the TestSwarm run page (including client name), for BrowserStack workers to open
--clientTimeout [min] Number of minutes to run each client (BrowserStack timeout, defaults to 10 minutes)

</pre>
64 changes: 38 additions & 26 deletions testswarm-browserstack.cli.js
Expand Up @@ -4,60 +4,72 @@ var program = require('commander'),

program
.version('0.0.1')
.option('--killAll', 'kill all workers now')
.option('--killWorker [workerid]', 'kill worker', parseInt)
.option('--getNeeded', 'return the workers required by testswarm')
.option('-k, --kill', 'if --run specified, kill workers if they are no longer needed.')
.option('-r, --run', 'start up workers required by browserstack')
.option('-u, --user [username]', 'browserstack username', '')
.option('-p, --pass [password]', 'browserstack password', '')
.option('-s, --swarmUrl [url]', 'testswarm URL of getneeded call', '')
.option('-w, --spawnUrl [url]', 'URL for browserstack workers to run', '')
.option('-v, --verbose', 'print more info')
.option('-t, --clientTimeout [min]', 'number of minuets to run each client (browserstack timeout)', parseInt)
.option('--killAll', 'Kill all BrowserStack workers')
.option('--killWorker [workerid]', 'Kill a BrowserStack worker by its worker ID', parseInt)
.option('--getNeeded', 'Shows a list of browser IDs that have pending jobs in TestSwarm')
.option('--kill', 'Kill BrowserStack workers if they are no longer needed (Only if --run is also specified)')
.option('--run', 'Start new workers in BrowserStack based on the swarm state')
.option('-u, --user [username]', 'BrowserStack username', '')
.option('-p, --pass [password]', 'BrowserStack password', '')
.option('-v, --verbose', 'Output more debug messages (all output via console.log)')
.option('--swarmUrl [url]', 'URL of TestSwarm root (without trailing slash)', '')
.option('--swarmRunUrl [url]', 'URL to the TestSwarm run page (including client name), for BrowserStack workers to open', '')
.option('--clientTimeout [min]', 'Number of minutes to run each client (BrowserStack timeout defaults to 10 minutes)', parseInt)
.parse(process.argv);

if(!process.argv[2]){
if (!process.argv[2]) {
console.log(program.helpInformation());
return;
}

tsbs.options(program);

if(program.getNeeded){
if(!program.swarmUrl){
if (program.getNeeded) {
if (!program.swarmUrl) {
console.log('please set --swarmUrl. stopping.');
return;
}
tsbs.getNeeded(function(needed){
tsbs.getSwarmState(function (error, swarmState) {
var browserID, stats,
needed = [];
if (error) {
console.log('getting swarm state failed:\n', error);
return;
}
for (browserID in swarmState.userAgents) {
stats = swarmState.userAgents[browserID].stats;
if (stats.onlineClients === 0 && stats.pendingRuns > 0) {
needed.push(browserID);
}
}
console.log(needed);
});
}

if(program.run || program.killWorker || program.killAll){
if(!program.pass || !program.user){
console.log('please set --user and --pass. stopping.');
if (program.run || program.killWorker || program.killAll) {
if (!program.pass || !program.user) {
console.log('please set --user and --pass for browserstack. stopping.');
return;
}
}

if(program.killAll){
if (program.killAll) {
tsbs.killAll(program.killWorker);
}

if(program.killWorker){
if (program.killWorker) {
tsbs.killWorker(program.killWorker);
}

if(program.run){
if(!program.swarmUrl || !program.spawnUrl){
console.log('please set --swarmUrl and --spawnUrl. stopping.');
if (program.run) {
if (!program.swarmUrl || !program.swarmRunUrl) {
console.log('please set --swarmUrl and --swarmRunUrl. stopping.');
return;
}

//set default timeout if not set
// Set default timeout if not set
program.clientTimeout = program.clientTimeout || 10;
//convert timeout to min
// Convert timeout to min
program.clientTimeout = program.clientTimeout * 60;
tsbs.run();
}
}

0 comments on commit 5673931

Please sign in to comment.