Creating Tests with Puppeteer: Part 2

In our last post about implementing tests with Puppeteer, we did a high-level overview of some of the decisions we made to switch from Casper to Puppeteer. In this post, we are going to go over the code that makes our tests work.

Goals

At the end of this tutorial, we will have a fully working test that implements Puppeteer, Mocha, and Chai for Outside Online.

Initialization

1. Let’s first start with creating a new folder in the directory of your choosing.

2. Inside this folder, run npm init – feel free to name it however you like and fill in any values you prefer, there is nothing special in this step

3. Next, we need to install 4 modules. Two of them are devDependencies and two are regular dependencies

npm install --save lodash puppeteer

npm install --save-dev mocha chai

I did not mention lodash in the previous post, but it is a utility library that we will use minimally.

4. After installation completes, create an empty bootstrap.js file to bootstrap our tests in the base directory.

5. Lastly for initialization, we need to modify package.json to run mocha correctly:

...
"scripts": {
	"test": "mocha bootstrap.js";
}
...

6. In your terminal, if you run npm test you should get an output saying 0 passing. This is exactly what we want – it signals everything is correctly installed and mocha is running.

Bootstrapping the Tests

The next thing we need to do is bootstrap all of our tests with puppeteer.

1. Head back to your text editor and open up the bootstrap.js file.

2. We now need to import the libraries we installed:

const puppeteer = require('puppeteer');
const { expect } = require('chai');
const _ = require('lodash');

3. One of the benefits of using mocha is that we can define before and after functions that will run before our test suite and then after. This is ideal for setup and cleanup after our tests run.

4. We are going to create a before function to setup puppeteer

before (async function () {
	global.expect = expect;
	global.browser = await puppeteer.launch({headless: true});
});

The before function does 2 things – it setups expect as a global variable to use in all of our tests and it also creates a puppeteer browser instance that we can reuse. We do this so we are not creating a new browser for each test, just using a single one.

5. Inside of launch() for puppeteer we are passing in the option of headless: true. This flag is what determines how Chrome will launch – a physical browser or not. For now, we are setting it to be headless but, if you wanted to see an actual Chrome browser open up and run you would set it to false.

6. Now for our after function, we are just going to do a little cleanup:

after (function () {
	browser.close();
});

All that is doing is closing down the puppeteer browser instance we created.

Creating Your First Test

1. With all the setup work now complete, we can create our first test! For this test, we are going to keep it really simple and make sure that Outside's homepage has the correct title.

2. Before we get started, check out the Mocha Documentation for some examples and documentation of how to write tests.

3. Next, go ahead and create a directory within your project called test

4. Inside the test directory, create a new file called homepage.spec.js – this will be the file where we write our homepage tests.

5. To start our test inside homepage.spec.js we have to describe it –

describe('Homepage Test', function() {
});

7. In the previous section we set up the base bootstrap for all tests. Now, we need to set up a before function that handles what should happen before the tests are run. In this scenario it needs to:

   • Open a new tab

   • Go to a specific URL

8. Within the describe function, let's create the before initialization:

before (async () => {
	page = await browser.newPage();
	await page.goto('https://www.outsideonline.com', { waitUntil: 'networkidle2' });
});

9. With the before successfully created, we can now write our test right below the before function!

it("should have the title", async () => {
	expect(await page.title()).to.eql("Outside Online")
});

The above test should read almost like a sentence – we “expect” the page title to equal Outside Online. Pretty simple, right?

Finalizing Our Test

1. With our test complete, we just need to do one more thing – update our package.json script.

...
"scripts": {
	"test": "mocha bootstrap.js --recursive test/ --timeout 30000"
}
...

2. We added two more parameters to the test script:

   • The --recursive test/ parameter tells mocha to look into the test/ folder and recursively run all tests that it finds. For us it is only 1, but you can imagine a folder full or subfolder and subtests that all need to be run.

   • The --timeout 30000 is setting the mocha timeout to be 30 seconds instead of 2000ms. This is important as it takes some time for puppeteer to launch and, if we didn't have that, the tests would fail to launch!

3. With that now complete, we can run our tests with a simple npm test

4. We should now see that the test has run correctly and the Outside homepage has the title “Outside Online”.

5. If you want to double check to make sure it is working, go back to homepage.spec.jsand change the title to expect something else like “Welcome to Outside!”

it("should have the title", async () => {
	expect(await page.title()).to.eql("Welcome to Outside")
});

6. If we do that, and rerun the tests, we should see that it has failed. Congratulations you are up and running!

If you’ve run into any errors or problems, visit the gist Testing with Puppeteer to compare your code. Be sure to check out Part 3 of this series of how to pass custom parameters to your tests and generate screenshots for failing tests!