UNPKG

5.61 kBMarkdownView Raw
1# node-browserstack
2
3A node.js JavaScript client for working with [BrowserStack](http://browserstack.com) through its [API](https://github.com/browserstack/api).
4
5Support this project by [donating on Gittip](https://www.gittip.com/scottgonzalez/).
6
7## Installation
8
9```
10npm install browserstack
11```
12
13## Usage
14
15```javascript
16var BrowserStack = require( "browserstack" );
17var client = BrowserStack.createClient({
18 username: "foo",
19 password: "p455w0rd!!1"
20});
21
22client.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
34A 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
42A browser object may only have one of `browser` or `device` set; which property is set will depend on `os`.
43
44### worker objects
45
46Worker 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
54Creates 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
64Gets 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
71Creates 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
88Gets 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
96Terminates 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
104Gets 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
111Take 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
118Gets 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
128Gets 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
143Copyright 2013 Scott González. Released under the terms of the MIT license.
144
145---
146
147Support this project by [donating on Gittip](https://www.gittip.com/scottgonzalez/).