Automated Testing with Puppeteer and WonderProxy

Puppeteer is a free and Open Source test automation tool for web browsers like Chrome and Firefox. Developed by Google, Puppeteer is a NodeJS library that can combine with WonderProxy to deliver localized test automation — with geoIP and redirection — all from a single laptop, Continuous Integration server, or elsewhere in the cloud.

For the code samples and setup instructions below, we'll use a working demo, available on Github, that runs a few tests against the WonderNetwork GeoTest page.

Step 1: Set up your local Puppeteer environment

1. You'll need NodeJS v10 or higher.

   
   $ node -v
   
   

   If you don't have it installed, you can download it for your platform at the official site.
2. If you're setting up a new project, create a new directory and initialize npm. When you're asked for a test command, use jest.

   
   $ mkdir puppeteer-project
   $ cd puppeteer-project
   $ npm init
   
   

3. Set up Puppeteer in your project:

   
   $ npx gitignore node                      # create a .gitignore file with sensible defaults
   $ npm install --save-dev puppeteer jest   # install Puppeteer and our test framework
   $ mkdir test                              # create the directory for your tests
   
   

Step 2: Configure Puppeteer to use WonderProxy

Writing Puppeteer tests is extensively covered in the official documentation, so we won't go in depth on the topic here. Instead, we'll focus on integrating WonderProxy using Puppeteer's launch options and page authentication functionality.

The Puppeteer tests read your WonderProxy credentials from the local environment, so set that up first:

$ export WONDERPROXY_USER=yourusername
$ export WONDERPROXY_TOKEN=yourproxytoken

In the code sample below, we pass a proxy server (denver.wonderproxy.com:11000) into the command-line argument for the browser, then use page.authenticate() to pass our proxy credentials to the page.

const server = 'denver.wonderproxy.com:11000';

const browser = await puppeteer.launch({
    args: [`--proxy-server=http://${server}`]
});
const page = await browser.newPage();
await page.authenticate({
    username: process.env.WONDERPROXY_USER
    password: process.env.WONDERPROXY_TOKEN
});

Puppeteer uses page.authenticate() to fill out any credential pop-up on a page. (Websites that require HTTP Basic authentication use the same pop-up, so if that's what you're testing, you'll need an intermediary proxy to handle WonderProxy authentication.)

Step 3: Write tests

Now that we know how to configure Puppeteer to shunt connections through WonderProxy, we can write some tests using the proxied driver.

First, define an array with all the locations you want to use for your tests:

const puppeteer = require('puppeteer');

const locations = [
    { title: 'Albuquerque', server: 'albuquerque.wonderproxy.com:11000' },
    { title: 'Toronto', server: 'toronto.wonderproxy.com:11000' },
    { title: 'Vancouver', server: 'vancouver.wonderproxy.com:11000' },
];

Make sure you've added all the locations you want to use to your WonderProxy account!

Use Jest's describe.each() method to create a test suite for each location, setting up the proxied browser in the process:

describe.each(locations)('The WonderNetwork Geotest page from $server', ({ title, server }) => {
    let browser, page;

    beforeAll(async () => {
        browser = await puppeteer.launch({
            args: [`--proxy-server=http://${server}`]
        });

        page = await browser.newPage();
        await page.authenticate({
            username: process.env.WONDERPROXY_USER
            password: process.env.WONDERPROXY_TOKEN
        });
    });

    // todo: write some tests
});

Now that each location has its own test suite, we can write the actual tests. From each location, we want to

1. load https://wondernetwork.com/geotest,
2. check that the title is correct, and
3. check that the displayed city matches the location for the group.

You've already seen the beforeAll() method we're using to set up the browser. Jest runs beforeAll() before any of the tests in the suite, so it's a good place to navigate to our target website.

beforeAll(async () => {
    // ...set up the browser as above...

    await page.goto('https://wondernetwork.com/geotest');
});

After the browser navigates to our target website, we can write our tests for the page.

describe.each(locations)('The WonderNetwork Geotest page from $server', ({ title, server }) => {
    let browser, page;

    // ...set up the suite in beforeAll()...

    it('has the right title', async () => {
        const title = await page.title();
        expect(title).toBe('Geotest - WonderNetwork');
    });

    it(`displays ${title} as the city`, async () => {
        const element = await page.$('#user-city');
        expect(await element.evaluate(node => node.innerText)).toBe(title);
    });
});

After each test suite runs, we need to close the browser so it doesn't hang around for the next one. Jest's afterAll() method is perfect:

describe.each(locations)('The WonderNetwork Geotest page from $server', ({ title, server }) => {
    let browser, page;

    // ...set up the suite in beforeAll()...

    // ...run tests...

    afterAll(async () => {
        await browser.close();
    });
});

Step 4: Get testing!

We configured npm's default test command to run jest, and we already added our proxy credentials to the environment, so we can run the tests normally:

$ npm test

Puppeteer runs each test from each location, and displays output that knits all our test descriptions together:

> puppeteer-wp@1.0.0 test
> jest --verbose

 PASS  test/WonderProxy.spec.js (12.48 s)
  The WonderNetwork Geotest page from albuquerque.wonderproxy.com:11000
    ✓ has the right title (8 ms)
    ✓ displays Albuquerque as the city (4 ms)
  The WonderNetwork Geotest page from toronto.wonderproxy.com:11000
    ✓ has the right title (16 ms)
    ✓ displays Toronto as the city (6 ms)
  The WonderNetwork Geotest page from vancouver.wonderproxy.com:11000
    ✓ has the right title (19 ms)
    ✓ displays Vancouver as the city (10 ms)

Test Suites: 1 passed, 1 total
Tests:       6 passed, 6 total
Snapshots:   0 total
Time:        12.513 s, estimated 14 s
Ran all test suites.

These code samples are part of a working demo, which is available on Github.