1 | # node-browserstack
|
2 |
|
3 | A node.js JavaScript client for working with [BrowserStack](http://browserstack.com) through its [API](https://github.com/browserstack/api).
|
4 |
|
5 | Support this project by [donating on Gittip](https://www.gittip.com/scottgonzalez/).
|
6 |
|
7 | ## Installation
|
8 |
|
9 | ```
|
10 | npm install browserstack
|
11 | ```
|
12 |
|
13 | ## Usage
|
14 |
|
15 | ```javascript
|
16 | var BrowserStack = require( "browserstack" );
|
17 | var client = BrowserStack.createClient({
|
18 | username: "foo",
|
19 | password: "p455w0rd!!1"
|
20 | });
|
21 |
|
22 | client.getBrowsers(function( error, browsers ) {
|
23 | console.log( "The following browsers are available for testing" );
|
24 | console.log( browsers );
|
25 | });
|
26 | ```
|
27 |
|
28 | ## API
|
29 |
|
30 | *Note: The API documented here is for the latest supported version (v3). For earlier versions, please see [the wiki](https://github.com/scottgonzalez/node-browserstack/wiki/API).*
|
31 |
|
32 | ### browser objects
|
33 |
|
34 | A common pattern in the API is a "browser object" which is just a plain object with the following properties:
|
35 |
|
36 | * `os`: The operating system.
|
37 | * `os_version`: The operating system version.
|
38 | * `browser`: The browser name.
|
39 | * `browser_version`: The browser version.
|
40 | * `device`: The device name.
|
41 |
|
42 | A browser object may only have one of `browser` or `device` set; which property is set will depend on `os`.
|
43 |
|
44 | ### worker objects
|
45 |
|
46 | Worker objects are extended [browser objects](#browser-objects) which contain the following additional properties:
|
47 |
|
48 | * `id`: The worker id.
|
49 | * `status`: A string representing the current status of the worker.
|
50 | * Possible statuses: `"running"`, `"queue"`.
|
51 |
|
52 | ### BrowserStack.createClient( settings )
|
53 |
|
54 | Creates a new client instance.
|
55 |
|
56 | * `settings`: A hash of settings that apply to all requests for the new client.
|
57 | * `username`: The username for the BrowserStack account.
|
58 | * `password`: The password for the BrowserStack account.
|
59 | * `version` (optional; default: `3`): Which version of the BrowserStack API to use.
|
60 | * `server` (optional; default: `{ host: "api.browserstack.com", port: 80 }`): An object containing `host` and `port` to connect to a different BrowserStack API compatible service.
|
61 |
|
62 | ### client.getBrowsers( callback )
|
63 |
|
64 | Gets the list of available browsers.
|
65 |
|
66 | * `callback` (`function( error, browsers )`): A callback to invoke when the API call is complete.
|
67 | * `browsers`: An array of [browser objects](#browser-objects).
|
68 |
|
69 | ### client.createWorker( settings, callback )
|
70 |
|
71 | Creates a worker.
|
72 |
|
73 | * `settings`: A hash of settings for the worker (an extended [browser object](#browser-objects)).
|
74 | * `os`: See [browser object](#browser-objects) for details.
|
75 | * `os_version`: See [browser object](#browser-objects) for details.
|
76 | * `browser`: See [browser object](#browser-objects) for details.
|
77 | * `browser_version`: See [browser object](#browser-objects) for details.
|
78 | * `device`: See [browser object](#browser-objects) for details.
|
79 | * `url` (optional): Which URL to navigate to upon creation.
|
80 | * `timeout` (optional): Maximum life of the worker (in seconds). Use 0 for "forever" (BrowserStack will kill the worker after 1,800 seconds).
|
81 | * `callback` (`function( error, worker )`): A callback to invoke when the API call is complete.
|
82 | * `worker` A [worker object](#worker-objects).
|
83 |
|
84 | *Note: A special value of `"latest"` is supported for `browser_version`, which will use the latest stable version.*
|
85 |
|
86 | ### client.getWorker( id, callback )
|
87 |
|
88 | Gets the status of a worker.
|
89 |
|
90 | * `id`: The id of the worker.
|
91 | * `callback` (`function( error, worker )`): A callback to invoke when the API call is complete.
|
92 | * `worker`: A [worker object](#worker-objects).
|
93 |
|
94 | ### client.terminateWorker( id, callback )
|
95 |
|
96 | Terminates an active worker.
|
97 |
|
98 | * `id`: The id of the worker to terminate.
|
99 | * `callback` (`function( error, data )`): A callback to invoke when the API call is complete.
|
100 | * `data`: An object with a `time` property indicating how long the worker was alive.
|
101 |
|
102 | ### client.getWorkers( callback )
|
103 |
|
104 | Gets the status of all workers.
|
105 |
|
106 | * `callback` (`function( error, workers )`): A callback to invoke when the API call is complete.
|
107 | * `workers`: An array of [worker objects](#worker-objects).
|
108 |
|
109 | ### client.takeScreenshot( id, callback )
|
110 |
|
111 | Take a screenshot at current state of worker.
|
112 |
|
113 | * `callback` (`function( error, data )`): A callback to invoke when the API call is complete.
|
114 | * `data`: An object with a `url` property having the public url for the screenshot.
|
115 |
|
116 | ### client.getLatest( browser, callback )
|
117 |
|
118 | Gets the latest version of a browser.
|
119 |
|
120 | * `browser`: Which browser to get the latest version for. See [browser object](#browser-objects) for details.
|
121 | * `callback` (`function( error, version )`): A callback to invoke when the version is determined.
|
122 | * `version`: The latest version of the browser.
|
123 |
|
124 | *Note: Since mobile devices do not have version numbers, there is no latest version.*
|
125 |
|
126 | ### client.getLatest( callback )
|
127 |
|
128 | Gets the latest version of all browsers.
|
129 |
|
130 | * `callback` (`function( error, versions )`): A callback to invoke when the versions are determined.
|
131 | * `versions`: A hash of browser names and versions.
|
132 |
|
133 | ### client.getApiStatus( callback )
|
134 |
|
135 | * `callback` (`function( error, status )`): A callback to invoke when the status is determined.
|
136 | * `used_time`: Time used so far this month, in seconds.
|
137 | * `total_available_time`: Total available time, in seconds. Paid plans have unlimited API time and will receive the string `"Unlimited Testing Time"` instead of a number.
|
138 | * `running_sessions`: Number of running sessions.
|
139 | * `sessions_limit`: Number of allowable concurrent sessions.
|
140 |
|
141 | ## License
|
142 |
|
143 | Copyright 2013 Scott González. Released under the terms of the MIT license.
|
144 |
|
145 | ---
|
146 |
|
147 | Support this project by [donating on Gittip](https://www.gittip.com/scottgonzalez/).
|