Have ideas to improve npm?Join in the discussion! »

    browserstack

    1.6.1 • Public • Published

    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.

    Install

    npm i browserstack

    DownloadsWeekly Downloads

    1,388,691

    Version

    1.6.1

    License

    MIT

    Unpacked Size

    55.7 kB

    Total Files

    18

    Last publish

    Collaborators

    • avatar
    • avatar
    • avatar