node-browserstack

by scottgonzalez

scottgonzalez / node-browserstack

node.js client for BrowserStack

211 Stars 52 Forks Last release: Not found Other 79 Commits 18 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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.

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.
    • 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.

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.
    • 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.

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.

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.