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"
};
var client = BrowserStack.createClient(browserStackCredentials);
client.getBrowsers(function(error, browsers) {
console.log("The following browsers are available for testing");
console.log(browsers);
});
var automateClient = BrowserStack.createAutomateClient(browserStackCredentials);
automateClient.getBrowsers(function(error, browsers) {
console.log("The following browsers are available for automated testing");
console.log(browsers);
});
var appAutomateClient = BrowserStack.createAppAutomateClient(browserStackCredentials);
appAutomateClient.getBuilds(function(error, builds) {
console.log("The following builds are available for app automated testing");
console.log(builds);
});
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.
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.
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.
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.
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.
automateClient.getProjects(callback)
Gets the list of projects.
callback
(function(error, projects)
): A callback to invoke when the API call is complete.
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.
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.
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.
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.
automateClient.updateSession(id, options, callback)
Updates the status of a session.
id
: The hashed ID of the session.options
: An object containing the parameters.
callback
(function(error, session)
): A callback to invoke when the API call is complete.
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.
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.
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.
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.
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.
automateClient.updateSession(id, options, callback)
Updates the status of a session.
id
: The hashed ID of the session.options
: An object containing the parameters.
callback
(function(error, session)
): A callback to invoke when the API call is complete.
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.
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
(optional): Defaults to "portrait"
.quality
(optional): Defaults to "compressed"
.wait_time
(optional): Defaults to 5
.local
(optional): Defaults to false
.
callback
(function(error, job)
): A callback to invoke when the API call is complete.
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.
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.