Skip to main content
Transform your testing process with: Real Device Features, Company-wide Licences, & Test Observability

Puppeteer testing on BrowserStack

A quickstart guide to running your Puppeteer tests across 100+ desktop browsers on BrowserStack.

Quickstart

Running your first Puppeteer test suite on BrowserStack is super easy. Here’s a quick start guide to help you get started with Puppeteer testing on BrowserStack in under 2 minutes.

Step 1: Clone our sample repository and install dependencies

All our sample tests are available on this GitHub repository. The first step is to download this repository on your system and install the dependencies as shown below:

Command Line
# The following command will clone the repository on your system

git clone https://github.com/browserstack/puppeteer-browserstack.git
cd puppeteer-browserstack
npm install

Step 2: Configuring BrowserStack credentials

Note: Testing on BrowserStack requires username and access key that can be found in account settings.
If you have not created an account yet, you can sign up for a Free Trial or purchase a plan.

All our sample scripts need your BrowserStack credentials to run. Please set the environment variables BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY with your credentials as shown below:

Command Line
export BROWSERSTACK_USERNAME="YOUR_USERNAME"
export BROWSERSTACK_ACCESS_KEY="YOUR_ACCESS_KEY"

Alternatively, your can put your credentials in the browserstack.username and browserstack.accessKey capabilities in the duckduckgo_search.js file (and all other files) in the sample repository.

Step 3: Run your first test

After you have configured the credentials and installed the npm dependencies, you can invoke your first Puppeteer test on BrowserStack using the following:

Command Line
node duckduckgo_search.js

Step 4: View your test results on the Automate Dashboard

After the test has run, you can access the test results on the BrowserStack Automate dashboard. You can learn more about viewing test results on Automate Dashboard.

Details of your first test

In this section, we will walk you through the details of the first test that you just ran and also explain the changes that you need to make in your existing Puppeteer scripts to make them run on BrowserStack.

The sample script that has run, is shown below (see in GitHub):

duckduckgo_search.js
'use strict';
const { strict } = require('once');
const puppeteer = require('puppeteer');
const expect = require('chai').expect;
(async () => {
  const caps = {
    '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
    'os': 'os x',
    'os_version': 'big sur',
    '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
    'browserstack.username': process.env.BROWSERSTACK_USERNAME || 'YOUR_USERNAME',
    'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY'
  };
  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');
  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.
})();
Note: Puppeteer tests run on BrowserStack using a client-server architecture. So, test assertions run on the client side and hence BrowserStack won’t know whether your tests have passed or failed. Learn more how to mark tests as passed or failed on BrowserStack.

You can learn more about how to make your existing Puppeteer scripts run on BrowserStack and you can also learn about how to test against your privately hosted websites.

Next Steps

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
Download Copy