Skip to main content

Capabilities

Using Puppeteer with BrowserStack requires passing the custom capabilities in an object, and passing this object to the Puppeteer URL endpoint on BrowserStack. This section includes a sample script file along with a detailed reference of all the supported capabilities.

sample-test.js
'use strict';
const { strict } = require('once');
const puppeteer = require('puppeteer');
const expect = require('chai').expect;
(async () => {
  const caps = {
    'os': 'os x',
    'os_version': 'big sur',
    'browser': 'chrome',  // You can choose `chrome`, `edge` or `firefox` in this capability
    'browser_version': 'latest',  // We support v83 and above. You can choose `latest`, `latest-beta`, `latest-1`, `latest-2` and so on, in this capability
    'browserstack.username': process.env.BROWSERSTACK_USERNAME || 'YOUR_USERNAME',
    'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
    'build': 'puppeteer-build-1',
    'name': 'My first Puppeteer test',  // The name of your test and build. See browserstack.com/docs/automate/puppeteer/organize tests for more details
    'buildTag': 'reg',
    'resolution': '1280x1024',
    'browserstack.local' : 'true',
    'browserstack.localIdentifier': `local_connection_name`,
    'browserstack.debug': 'true',  // Enabling visual logs
    'browserstack.seleniumLogs': 'true',
    'browserstack.console': 'info', // Enabling console logs
    'browserstack.networkLogs': 'true',  // Enabling network logs for the test
    'browserstack.networkLogsOptions':
        {
            'captureContent': 'true',
        }
    };
    
    const browser = await puppeteer.connect({
    browserWSEndpoint:
    `wss://cdp.browserstack.com/puppeteer?caps=${encodeURIComponent(JSON.stringify(caps))}`,  // The BrowserStack CDP endpoint gives you a `browser` instance based on the `caps` that you specified
    });

    /* 
    *  The BrowserStack specific code ends here. Following this line is your test script.
    *  Here, we have a simple script that opens duckduckgo.com, searches for the word BrowserStack and asserts the result.
    */
    const page = await browser.newPage();
    await page.goto('https://www.duckduckgo.com');
    const element = await page.$('[name="q"]');
    await element.click();
    await element.type('BrowserStack\n');
    await element.press('Enter');
    await page.waitForNavigation();
    const title = await page.title('');
    console.log(title);
    try {
        expect(title).to.equal("BrowserStack at DuckDuckGo", 'Expected page title is incorrect!');
        // following line of code is responsible for marking the status of the test on BrowserStack as 'passed'. You can use this code in your after hook after each test
        await page.evaluate(_ => {}, `browserstack_executor: ${JSON.stringify({action: 'setSessionStatus',arguments: {status: 'passed',reason: 'Title matched'}})}`);
    } catch {
        await page.evaluate(_ => {}, `browserstack_executor: ${JSON.stringify({action: 'setSessionStatus',arguments: {status: 'failed',reason: 'Title did not match'}})}`);
    }
    await browser.close();  // At the end of each of your tests, you must close the browser so that BrowserStack knows when to end the session.
})();
The following table lists the supported Puppeteer capabilites and how they must be defined in the test file:
Capability Expected Values
os Set the operating system on which you want to run your test
Eg. Windows or OS X

Ref: Specify which OS is to be used to run the test
os_version Set the specific version of the OS
Eg. Windows: 10, 11 or OS X: Mojave, Catalina, Big Sur, and Monterey

Ref: Specify which OS version is to be used to run the test
browser Set the browser you want to use for your test
Eg. chrome, firefox, and edge

Ref: Specify the browser to be used
browser_version Set the browser version for your test
Eg. Chrome: 72 and above
Firefox: 86 and above
Edge: 80 and above

It is recommended that you use latest, latest-1, latest-2, latest-beta, and so on, to test on the latest n versions of the required browser.

Ref: Specify the browser version to be used
browserstack.username Your BrowserStack username which you can find in your account settings.
browserstack.accessKey Your BrowserStack access key which you can find in your account settings.
browserstack.geolocation Simulate the location of browsers

"geolocation": "<country_code>"
project A string that you want to group your builds into.
Eg. New dashboard

Ref: Specify a name for your project
build A string that you want to identify your build with.
Eg. build 1

Ref: Specify a name for your build or CI run
name A string that you want to identify your session with.
Eg. My Test

Ref: Specify a name for your build or CI run
buildTag A string that you want to tag your build with.
Eg. sanity

Ref: Specify a tag for your test build
resolution Set the resolution of your desktop OS before beginning your test

Default resolution is 1920x1080

Ref: Specify desktop screen resolution
browserstack.local Test your locally hosted website on BrowserStack.
Defaults to false. Set value as true to enable.
browserstack.localIdentifier Specify the unique Local Testing connection name.
Eg. local_connection_name
debug Helps debug issues detected through your tests.

Disabled by default. Set True to enable.
video Provides a video recording of the actions performed during the test.

Available by default. Set false to disable.

Ref: Records every test as it is executed on BrowserStack
browserstack.console Captures the browser’s console output at various steps of the test.
Available by default. Set value as disable to disable the console logs.
browserstack.networkLogs Provides a comprehensive log of all network activity during your Puppeteer tests.

Defaults to false. Set true to enable.
browserstack.networkLogsOptions Captures the request and response payload of your test session

Defaults to false. Set true to enable.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback

Is this page helping you?

Yes
No

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked






Thank you for your valuable feedback!

Talk to an Expert
Talk to an Expert