node-browserstack

A node.js JavaScript client for working with BrowserStack through its REST API (aka Javascript Testing API), Automate API, App Automate API, and Screenshots API.

# Installation

npm install browserstack

# Usage

var BrowserStack = require("browserstack");
var browserStackCredentials = {
username: "foo",
password: "p455w0rd!!1"
};
// REST API
var client = BrowserStack.createClient(browserStackCredentials);
client.getBrowsers(function(error, browsers) {
console.log("The following browsers are available for testing");
console.log(browsers);
});
// Automate API
var automateClient = BrowserStack.createAutomateClient(browserStackCredentials);
automateClient.getBrowsers(function(error, browsers) {
console.log("The following browsers are available for automated testing");
console.log(browsers);
});
// App Automate API
// Show the upload builds for mobile app automation
var appAutomateClient = BrowserStack.createAppAutomateClient(browserStackCredentials);
appAutomateClient.getBuilds(function(error, builds) {
console.log("The following builds are available for app automated testing");
console.log(builds);
});
// Screenshots API
var screenshotClient = BrowserStack.createScreenshotClient(browserStackCredentials);
screenshotClient.getBrowsers(function(error, browsers) {
console.log("The following browsers are available for screenshots");
console.log(browsers);
});

# API

## Objects

### browser objects

A common pattern in the APIs is a "browser object" which is just a plain object with the following properties:

- `os`: The operating system.
- `os_version`: The operating system version.
- `browser`: The browser name.
- `browser_version`: The browser version.
- `device`: The device name.

A browser object may only have one of `browser` or `device` set; which property is set will depend on `os`.

### worker objects

Worker objects are extended browser objects which contain the following additional properties:

- `id`: The worker id.
- `status`: A string representing the current status of the worker.
  - Possible statuses: `"running"`, `"queue"`.

### project objects

Project objects are plain objects which contain the following properties:

- `id`: The id of the project.
- `name`: The name of the project.
- `created_at`: When the project was created.
- `updated_at`: When the project was most recently updated.
- `user_id`
- `group_id`

### build objects

Build objects are plain objects which contain the following properties:

- `hashed_id`: The hashed if of the build.
- `name`: The name of the build.
- `status`: The status of the build.
- `duration`

### extended build objects

Extended build objects are build objects with the following additional properties:

- `id`: The id of the build.
- `automation_project_id`: The id of the project this build belongs to.
- `updated_at`: When the build was created.
- `created_at`: When the build was most recently updated.
- `delta`
- `tags`
- `user_id`
- `group_id`

### session objects

Session objects are extended browser objects which contain the following additional properties:

- `hashed_id`: The hashed ID of the session.
- `name`: The name of the session.
- `build_name`: The name of the build this session belongs to.
- `project_name`: The name of the project this session belongs to.
- `status`: The status of the session.
- `browser_url`: The most recenly loaded URL the worker.
- `duration`: The duration in seconds that the session has been active.
- `logs`: The URL for the session logs.
- `video_url`: The URL for the session video.
- `reason`: The reason the session was terminated.

### screenshot job objects

Screenshot job objects are plain objects which contain the following properties:

- `job_id`: The id of the job.
- `state`: The state of the job.
- `win_res`: The screen resolution for browsers running on Windows. May be one of: `"1024x768"`, `"1280x1024"`.
- `mac_res`: The screen resolution for browsers running on Mac OS X. May be one of: `"1024x768"`, `"1280x960"`, `"1280x1024"`, `"1600x1200"`, `"1920x1080"`.
- `orientation`: The screen orientation for devices. May be one of: `"portrait"`, `"landscape"`.
- `quality`: The quality of the screenshot. May be one of: `"original"`, `"compressed"`.
- `wait_time`: The number of seconds to wait before taking the screenshot. May be one of: `2`, `5`, `10`, `15`, `20`, `60`.
- `local`: Boolean indicating whether a local testing connection should be used.
- `browsers`: A collection of browser objects indicating which browsers and devices to take screenshots with.

## screenshot state objects

Screenshot state objects are extended browser objects which contain the following additional properties:

- `id`: The id of the screenshot object.
- `state`: The state of the screenshot.
- `url`: The URL of the page the screenshot was generated from.
- `thumb_url`: The URL for the screenshot thumbnail.
- `image_url`: The URL for the full-size screenshot.
- `created_at`: The timestamp indicating when the screenshot was generated.

## REST API v4

Note: For earlier versions of the API, please see the wiki.

### BrowserStack.createClient(settings)

Creates a new client instance.

- `settings`: A hash of settings that apply to all requests for the new client.
  - `username`: The username for the BrowserStack account.
  - `password`: The password for the BrowserStack account.
  - `version` (optional; default: `4`): Which version of the BrowserStack API to use.
  - `server` (optional; default: `{ host: "api.browserstack.com", port: 80 }`): An object containing `host` and `port` to connect to a different BrowserStack API compatible service.
  - `proxy` (optional; default: `null`): Proxy server supporting HTTPS to be used for connecting to BrowserStack (or `settings.server`). e.g. `"http://proxy.example.com:1234"`

### client.getBrowsers(callback)

Gets the list of available browsers.

- `callback` (`function(error, browsers)`): A callback to invoke when the API call is complete.
  - `browsers`: An array of browser objects.

### client.createWorker(settings, callback)

Creates a worker.

- `settings`: A hash of settings for the worker (an extended browser object).
  - `os`: See browser object for details.
  - `os_version`: See browser object for details.
  - `browser`: See browser object for details.
  - `browser_version`: See browser object for details.
  - `device`: See browser object for details.
  - `url` (optional): Which URL to navigate to upon creation.
  - `timeout` (optional): Maximum life of the worker (in seconds). Maximum value of `1800`. Specifying `0` will use the default of `300`.
  - `name` (optional): Provide a name for the worker.
  - `build` (optional): Group workers into a build.
  - `project` (optional): Provide the project the worker belongs to.
  - `browserstack.video` (optional): Set to `false` to disable video recording.
- `callback` (`function(error, worker)`): A callback to invoke when the API call is complete.
  - `worker` A worker object.

Note: A special value of `"latest"` is supported for `browser_version`, which will use the latest stable version.

### client.getWorker(id, callback)

Gets the status of a worker.

- `id`: The id of the worker.
- `callback` (`function(error, worker)`): A callback to invoke when the API call is complete.
  - `worker`: A worker object.

### client.changeUrl(id, options, callback)

Change the URL of a worker.

- `id`: The id of the worker.
- `options`: Configuration for the URL change.
  - `url`: The new URL to set.
  - `timeout` (optional): Set a new timeout for this worker, see createWorker for details.
- `callback` (`function(error, data)`): A callback to invoke when the API call is complete.
  - `data`: An object with a `message`, confirming the URL change.

### client.terminateWorker(id, callback)

Terminates an active worker.

- `id`: The id of the worker to terminate.
- `callback` (`function(error, data)`): A callback to invoke when the API call is complete.
  - `data`: An object with a `time` property indicating how long the worker was alive.

### client.getWorkers(callback)

Gets the status of all workers.

- `callback` (`function(error, workers)`): A callback to invoke when the API call is complete.
  - `workers`: An array of worker objects.

### client.takeScreenshot(id, callback)

Take a screenshot at current state of worker.

- `callback` (`function(error, data)`): A callback to invoke when the API call is complete.
  - `data`: An object with a `url` property having the public url for the screenshot.

### client.getLatest(browser, callback)

Gets the latest version of a browser.

- `browser`: Which browser to get the latest version for. See browser object for details.
- `callback` (`function(error, version)`): A callback to invoke when the version is determined.
  - `version`: The latest version of the browser.

Note: Since mobile devices do not have version numbers, there is no latest version.

### client.getLatest(callback)

Gets the latest version of all browsers.

- `callback` (`function(error, versions)`): A callback to invoke when the versions are determined.
  - `versions`: A hash of browser names and versions.

### client.getApiStatus(callback)

- `callback` (`function(error, status)`): A callback to invoke when the status is determined.
  - `used_time`: Time used so far this month, in seconds.
  - `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.
  - `running_sessions`: Number of running sessions.
  - `sessions_limit`: Number of allowable concurrent sessions.

## Automate API

### BrowserStack.createAutomateClient(settings)

Creates a new client instance.

- `settings`: A hash of settings that apply to all requests for the new client.
  - `username`: The username for the BrowserStack account.
  - `password`: The password for the BrowserStack account.
  - `proxy` (optional; default: `null`): Proxy server supporting HTTPS to be used for connecting to BrowserStack. e.g. `"http://proxy.example.com:1234"`

### automateClient.getPlan(callback)

Gets information about your group's Automate plan, including the maximum number of parallel sessions allowed and the number of parallel sessions currently running.

- `callback` (`function(error, plan)`): A callback to invoke when the API call is complete.
  - `plan`: An object with `parallel_sessions_max_allowed`, `parallel_sessions_running`, and `automate_plan` showing the current state of your plan.

### automateClient.getBrowsers(callback)

Gets the list of available browsers.

- `callback` (`function(error, browsers)`): A callback to invoke when the API call is complete.
  - `browsers`: An array of browser objects.

### automateClient.getProjects(callback)

Gets the list of projects.

- `callback` (`function(error, projects)`): A callback to invoke when the API call is complete.
  - `projects`: An array of project objects.

### automateClient.getProject(id, callback)

Gets information about a project.

- `id`: The ID of the project.
- `callback` (`function(error, project)`): A callback to invoke when the API call is complete.
  - `project`: A project object including an array of extended build objects.

### automateClient.getBuilds([options,] callback)

Gets the list of builds.

- `options` (optional): An object containing search parameters.
  - `limit`: The number of builds to return. Defaults to `10`.
  - `status`: Filter builds based on status. May be one of `"running"`, `"done"`, `"failed"`, `"timeout"`.
- `callback` (`function(error, builds)`): A callback to invoke when the API call is complete.
  - `builds`: An array of build objects.

### automateClient.getSessions(buildId, [options,] callback)

Gets the list of sessions in a build.

- `buildId`: The hashed ID of the build.
- `options` (optional): An object containing search parameters.
  - `limit`: The number of sessions to return. Defaults to `10`.
  - `status`: Filter sessions based on status. May be one of `"running"`, `"done"`, `"failed"`.
- `callback` (`function(error, sessions)`): A callback to invoke when the API call is complete.
  - `sessions`: An array of session objects.

### automateClient.getSession(id, callback)

Gets the details for a session.

- `id`: The hashed ID of the session.
- `callback` (`function(error, session)`): A callback to invoke when the API call is complete.
  - `session`: A session object.

### automateClient.updateSession(id, options, callback)

Updates the status of a session.

- `id`: The hashed ID of the session.
- `options`: An object containing the parameters.
  - `status`: New status value. May be one of `"completed"` or `"error"`.
- `callback` (`function(error, session)`): A callback to invoke when the API call is complete.
  - `session`: The updated session object.

### automateClient.deleteSession(id, callback)

Deletes a session.

- `id`: The hashed ID of the session.
- `callback` (`function(error, data)`): A callback to invoke when the API call is complete.
  - `data`: An object with a `message`, confirming the deletion.

## App Automate API

### BrowserStack.createAppAutomateClient(settings)

Creates a new client instance.

- `settings`: A hash of settings that apply to all requests for the new client.
  - `username`: The username for the BrowserStack account.
  - `password`: The password for the BrowserStack account.
  - `proxy` (optional; default: `null`): Proxy server supporting HTTPS to be used for connecting to BrowserStack. e.g. `"http://proxy.example.com:1234"`

### automateClient.getPlan(callback)

Gets information about your group's App Automate plan, including the maximum number of parallel sessions allowed and the number of parallel sessions currently running.

- `callback` (`function(error, plan)`): A callback to invoke when the API call is complete.
  - `plan`: An object with `parallel_sessions_max_allowed`, `parallel_sessions_running`, and `automate_plan` showing the current state of your plan.

### automateClient.getProjects(callback)

Gets the list of projects.

- `callback` (`function(error, projects)`): A callback to invoke when the API call is complete.
  - `projects`: An array of project objects.

### automateClient.getProject(id, callback)

Gets information about a project.

- `id`: The ID of the project.
- `callback` (`function(error, project)`): A callback to invoke when the API call is complete.
  - `project`: A project object including an array of extended build objects.

### automateClient.getBuilds([options,] callback)

Gets the list of builds.

- `options` (optional): An object containing search parameters.
  - `limit`: The number of builds to return. Defaults to `10`.
  - `status`: Filter builds based on status. May be one of `"running"`, `"done"`, `"failed"`, `"timeout"`.
- `callback` (`function(error, builds)`): A callback to invoke when the API call is complete.
  - `builds`: An array of build objects.

### automateClient.getSessions(buildId, [options,] callback)

Gets the list of sessions in a build.

- `buildId`: The hashed ID of the build.
- `options` (optional): An object containing search parameters.
  - `limit`: The number of sessions to return. Defaults to `10`.
  - `status`: Filter sessions based on status. May be one of `"running"`, `"done"`, `"failed"`.
- `callback` (`function(error, sessions)`): A callback to invoke when the API call is complete.
  - `sessions`: An array of session objects.

### automateClient.getSession(id, callback)

Gets the details for a session.

- `id`: The hashed ID of the session.
- `callback` (`function(error, session)`): A callback to invoke when the API call is complete.
  - `session`: A session object.

### automateClient.updateSession(id, options, callback)

Updates the status of a session.

- `id`: The hashed ID of the session.
- `options`: An object containing the parameters.
  - `status`: New status value. May be one of `"completed"` or `"error"`.
- `callback` (`function(error, session)`): A callback to invoke when the API call is complete.
  - `session`: The updated session object.

### automateClient.deleteSession(id, callback)

Deletes a session.

- `id`: The hashed ID of the session.
- `callback` (`function(error, data)`): A callback to invoke when the API call is complete.
  - `data`: An object with a `message`, confirming the deletion.

## Screenshots API

### BrowserStack.createScreenshotClient(settings)

Creates a new client instance.

- `settings`: A hash of settings that apply to all requests for the new client.
  - `username`: The username for the BrowserStack account.
  - `password`: The password for the BrowserStack account.
  - `proxy` (optional; default: `null`): Proxy server supporting HTTPS to be used for connecting to BrowserStack. e.g. `"http://proxy.example.com:1234"`

### screenshotClient.getBrowsers(callback)

Gets the list of available browsers.

- `callback` (`function(error, browsers)`): A callback to invoke when the API call is complete.
  - `browsers`: An array of browser objects.

### screenshotClient.generateScreenshots(options, callback)

Creates a job to take screenshots.

- `options`: A hash of settings for the screenshots. See screenshot job objects for details.
  - `url`: The URL of the desired page.
  - `browsers`: A collection of browser objects indicating which browsers and devices to take screenshots with.
  - `win_res` (optional): Only required if taking a screenshot on Windows. Defaults to `"1024x768"`.
  - `mac_res` (optional): Only required if taking a screenshot on Mac OS X. Defaults to "1024x768"`. *`orientation<tt>(optional): Defaults to"portrait"`. *`quality<tt>(optional): Defaults to"compressed"`. *`wait_time<tt>(optional): Defaults to5`. *`local<tt>(optional): Defaults tofalse`. *`callback`(`function(error, job)`): A callback to invoke when the API call is complete. *`job`: A screenshot job object containing screenshot state objects in place of browser objects.

### screenshotClient.getJob(id, callback)

Gets details about the current status of a screenshot job.

- `id`: The id of the job.
- `callback` (`function(error, job)`): A callback to invoke when the API call is complete.
  - `job`: A screenshot job object containing screenshot state objects in place of browser objects.

# Tests

To run the full test suite, you must have a BrowserStack account. Run `npm test` with the `BROWSERSTACK_USERNAME` and `BROWSERSTACK_KEY` environment variables set.

To run just the lint checks, run `npm lint`.

# License

Copyright node-browserstack contributors. Released under the terms of the MIT license.