Test private websites using Puppeteer

A guide to running your Puppeteer tests on your privately hosted websites.

Important: Puppeteer testing on BrowserStack (beta) is not available to all users yet. If you’d like to get access, please submit a request here.

BrowserStack enables you to run automated tests on your internal development environments, on localhost, and from behind a corporate firewall. This feature is called “Local Testing”.

Local Testing establishes a secure connection between your machine and the BrowserStack cloud. Once you set up Local Testing, all URLs work out of the box, including HTTPS URLs and those behind a proxy or firewall. Learn more about how Local Testing works.

Run your first Puppeteer test against a private website

Local Testing can be enabled through two methods and both of them have been detailed below:

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.

Local testing connection can be set up using the npm package for BrowserStack Local. Please follow the steps below to run our sample test:

  • Step 1: Clone our sample repository and install dependencies (if not already done)

    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
    

    The important dependency for Local Testing is browserstack-local and you can install it in your project using npm i --save-dev browserstack-local

  • Step 2: Configuring BrowserStack credentials (if not already done)

    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 google_search.js file (and all other files) in the sample repository.

  • Step 3: Run your first Local test

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

    Command Line
    node local_test_using_bindings.js
    

Local testing connection can be set up using the npm package for BrowserStack Local. Please follow the steps below to run our sample test:

  • Step 1: Clone our sample repository and install dependencies (if not already done)

    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 (if not already done)

    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 google_search.js file (and all other files) in the sample repository.

  • Step 3: Download the BrowserStack Local binary from the links below (depending on your local machine’s environment):
  • Step 4: Once you have downloaded and unzipped the file, you can initiate the binary by running the command:

    Command Line
    ./BrowserStackLocal --key YOUR_ACCESS_KEY
    

    You can invoke the BrowserStackLocal binary using a lot of configurable options that may suit your use case.

  • Step 5: Once you see the terminal say “[SUCCESS] You can now access your local server(s) in our remote browser”, your local testing connection is considered established.

  • Step 6: Run your sample Local test

    Command Line
    node local_test.js
    
Important: Puppeteer testing on BrowserStack (beta) is not available to all users yet. If you’d like to get access, please submit a request here.

After the test has run, you can access the test results on the BrowserStack Automate dashboard.

Details of your first test

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

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

local_test_using_bindings.js
'use strict';

const puppeteer = require('puppeteer');
const BrowserStackLocal = require('browserstack-local');  // You have to ensure that 'browserstack-local' is a devDependency in your package.json

const bsLocal = new BrowserStackLocal.Local();

// replace YOUR_ACCESS_KEY with your key. You can also set an environment variable - "BROWSERSTACK_ACCESS_KEY".
const BS_LOCAL_ARGS = {
    'key': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY'
};

/**
 * Mark test status on BrowserStack.
 *
 * @param {Page} page - Page object created by Puppeteer context.
 * @param {String} status - Status string can be either passed|failed.
 * @param {String} reason - Explanatory reason for the status marked.
 * @return {Promise<String>} Stringified response from BrowserStack regarding the
 * execution of the jsExecutor.
 */
function markTest(page, status, reason) {
    return page.evaluate(
        _ => {},
        `browserstack_executor: ${JSON.stringify({
            action: 'setSessionStatus',
            arguments: { status, reason }
        })}`);
}

/**
 * Driver Test Function.
 *
 * @async
 * @return {Promise<void>}
 */
async function testFn() {
    console.log('Started BrowserStackLocal');

    // Check if BrowserStack local instance is running
    console.log(`BrowserStackLocal running: ${bsLocal.isRunning()}`);

    const caps = {
        'browser': 'chrome',
        'browser_version': 'latest',
        'os': 'os x',
        'os_version': 'catalina',
        'build': 'puppeteer-build-1',
        'name': 'My first Puppeteer test',
        'browserstack.username': process.env.BROWSERSTACK_USERNAME || 'YOUR_USERNAME',
        'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
        'browserstack.local': 'true'  // Setting this capability to true would inform BrowserStack that publicly inaccessible URLs have to be resolved through your local network using the tunnel connection created by 'browserstack-local' node package
    };

    // Use `.connect()` to initiate an Automate session on BrowserStack
    const browser = await puppeteer.connect({
        browserWSEndpoint: `wss://cdp.browserstack.com?caps=${encodeURIComponent(JSON.stringify(caps))}`,
    });
    // BrowserStack specific code ends here

    const page = await browser.newPage();
    await page.goto('http://localhost:45691');  // You can test against any of your privately hosted websites
    try {
        await page.waitForFunction(
            `document
                .querySelector("body")
                .innerText
                .includes("This is an internal server for BrowserStack Local")`,
        );
        // 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 markTest(page, 'passed', 'Local is up and running');
    } catch {
        await markTest(page, 'failed', 'BrowserStack Local binary is not running');
    }
    await browser.close();

    // Stop the Local instance after your test run is completed
    bsLocal.stop(() => console.log('Stopped BrowserStackLocal'));
}

// Starts the Local instance with the required arguments
bsLocal.start(BS_LOCAL_ARGS, testFn);

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

local_test.js
'use strict';
const { strict } = require('once');
const puppeteer = require('puppeteer');
const expect = require('chai').expect;
(async () => {
    const caps = {
        'browser': 'chrome',
        'browser_version': 'latest',
        'os': 'os x',
        'os_version': 'big sur',
        'build': 'puppeteer-build-1',
        'name': 'My first Puppeteer test',
        'browserstack.username': process.env.BROWSERSTACK_USERNAME || 'YOUR_USERNAME',
        'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY || 'YOUR_ACCESS_KEY',
        'browserstack.local': 'true'  // Setting this capability to 'true' would mean that browsers at BrowserStack would try to resolve the URL under test through the BrowserStack Local connection. You have to ensure that you have started the BrowserStackLocal binary in your system before invoking the script
    };
    const browser = await puppeteer.connect({
    browserWSEndpoint:
    `wss://cdp.browserstack.com?caps=${encodeURIComponent(JSON.stringify(caps))}`,
    });

    /* 
    *  BrowserStack specific code ends here.
    *  You have to ensure that BrowserStackLocal binary is running on your system before invoking this script.
    */
    const page = await browser.newPage();
    await page.goto('http://localhost:45454');  // You can test any of your privately hosted websites once Local Testing binary is connected and the 'browserstack.local' capability is set to true
    const title = await page.title('');
    console.log(title);
    try {
        expect(title).to.equal("BrowserStack Local", '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: 'Local is up and running'}})}`);
    } catch {
        await page.evaluate(_ => {}, `browserstack_executor: ${JSON.stringify({action: 'setSessionStatus',arguments: {status: 'failed',reason: 'BrowserStack Local binary is not running'}})}`);
    }
    await browser.close();
})();

//  After the end of the script, ensure to stop the BrowserStackLocal binary that had been started before invoking this script.
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 run cross-browser Puppeteer tests in parallel.

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
Talk to an Expert