Puppeteer Framework Tutorial: Basics and Setup

Test automation is now an integral part of the software development life cycle (SDLC). Most organizations choose open source automation tools to manage their cost and flexibility. There are a lot of Open Source Automation frameworks available in the market such as Playwright, Cypress, WebdriverIO, Testcafe, and Selenium.

Since the tech stack is moving towards Single Page Applications (SPA) such as React and Angular, the NodeJS-based Automation frameworks are gaining popularity. Puppeteer is one of the NodeJS-based Automation frameworks which is a recent favorite in the testing ecosystem which we will be covering in this guide.

What is the Puppeteer Framework?

Puppeteer is a NodeJS-based Automation Framework that allows programming through Javascript. It’s an Open Source and is maintained by Google. Puppeteer framework allows direct communication with Chrome-based browsers such as Chrome and Chromium while its advanced feature allows working with Firefox (Nightly Build) as well.

Advantages of the Puppeteer Framework

• Easy Configuration: Puppeteer is easy to configure and set up
• No Webdriver Dependancy: Unlike Selenium, Puppeteer doesn’t rely on a web driver so that we can expect stable test runs. No more browser/driver incompatibility.
• Faster Executions: Since it directly interacts with the browser, Puppeteer is faster and more stable.
• Test Library/Framework Integration: Puppeteer can easily be integrated into the Mocha and Jest framework.
• Documentation: Puppeteer has good documentation on their API, so it is easy to learn and  implement
• Browser Support: The Puppeteer framework supports Chrome and Firefox 
• Community Support: Since Puppeteer has a huge user base, it has good community support.

Limitations of Puppeteer

• Puppeteer is a thin wrapper, it’s not a complete framework-ready automation tool like Cypress or Testcafe.
• Browser support is limited to only Chrome and Firefox.
• Programming Language support is limited to Javascript.

How to set up Puppeteer Framework from scratch?

This tutorial explains setting up Puppeteer with NodeJS, Javascript, and Jest Framework.

Prerequisites:

1. Install NodeJS
2. Install Visual Studio Code (Recommended)

Setting up Puppeteer and Jest Automation Tool

Step 1: Create an empty directory; let’s name it puppeteer-demo

Step 2: Open the newly created empty directory (puppeteer-demo) in Visual Studio Code.

Step 3: Open a new terminal. You should be pointing to the root of the project: puppeteer-demo

Step 4: Enter Command to create package.json

npm  init

package.json gives the flexibility to create shortcut commands and tracks all dependencies.

While creating the package.json file, the CLI asks for questions. If you wish to answer, you can reply. Else just hit the ENTER key to set the default values.

Step 5: Install the puppeteer npm module

From Visual Studio Code Terminal, enter the command.

npm i puppeteer

Step 6: Install the jest package

Jest provides assertion libraries and configuration for the puppeteer

npm i jest

Step 7: Install jest-puppeteer

Jest-puppeteer provides integration between Puppeteer and jest framework.

npm i jest-puppeteer

Step 8: Create a Jest configuration file

In your project root directory, create a file with the name jest.config.js. Copy and paste the  below code

module.exports = {
preset: 'jest-puppeteer',
testRegex: './*\\.test\\.js$',
}

In the above code, we mention preset as jest-puppeteer, and testRegex helps find the set of puppeteer tests inside the project.

Step 9: Create a jest-puppeteer configuration file

In your project root directory, create a file with the name jest-puppeteer.config.js. Copy and paste the below code

// jest-puppeteer.config.js
module.exports = {
launch: {
headless: false,
product: 'chrome',
args: ['--start-maximized'],
defaultViewport :{width: 1700, height: 800 }

},
browserContext: 'default',
}

In the above code, we are mentioning Chrome as our browser for testing, and the headless mode is turned off. The browser context is set to default.

Step 10: Create a new folder to place our functional tests.

Create new folder ex: tests, at your project root directory level.

Step 11: Create a new Puppeteer test file

Inside your ‘tests’ folder, create a new file (ex: demo.test.js). Copy and paste the below code.

//demo.test.js
describe('Browserstack Demo', () => {
jest.setTimeout(50000);
beforeAll(async () => {
await page.goto('https://www.browserstack.com/')
})

it('Should Verify Forgot Password', async () => {
await page.click('a[href="/users/sign_in"]');
await page.waitForSelector('#user_email_login');
await page.click('a[href="/users/password/new"]');
await page.waitForSelector('input[id="user_email_login"]');
await page.type('input[id="user_email_login"]','ok@example.com')
await page.click('input[type="submit"]');
await page.waitForSelector('p[class="bs-alert-text"]');
const el = await page.$('p[class="bs-alert-text"]');
const text = await page.evaluate(el => el.innerText, el);
await expect(text).toContain("Password reset initiated");
})
})

The test scenario covered is as below: 

• Navigating to browserstack.com
• From Home, we are clicking the Sign In menu item
• Click on Forgot Password, on the Sign In Page
• Enter email-id and Submit
• Verify the Information Message

Step 12: Configure package.json to run the test

In the package.json file, search for “scripts”, and add the below value

"scripts": {
"test": "jest -c ./jest.config.js"
},

Step 13:  Execute First Test with Puppeteer

From the Visual Studio Code Terminal, Enter the below command

npm run test

Once you enter the above test, the execution starts, wait until it finishes.

The execution result will be shown in VS Code Terminal

Execute a Puppeteer Test on BrowserStack

Browserstack provides thousands of real devices for test execution and supports the Puppeteer framework for flawless test execution. Refer to our official Puppeteer docs for detailed steps.

Step 1: Configure jest-puppeteer.config.js 

Once tests execution on your machine are successful, you can execute the same tests on BrowserStack with minor changes listed below

jest-puppeteer.config.js.

In the jest-puppeteer.config.js  file add capabilities, and connect.

The complete jest-puppeteer.config.js  file looks like the one below.

// jest-puppeteer.config.js
const caps_chrome = {
'browser': 'chrome',
'browser_version': 'latest',
'os': 'windows',
'os_version': '10',
'name': 'Puppeteer-jest test on Chrome',
'build': 'puppeteer-jest-build-2',
'browserstack.username': process.env.BROWSERSTACK_USERNAME || 'your_user_name',
'browserstack.accessKey': process.env.BROWSERSTACK_ACCESS_KEY || 'your_access_key'
};


module.exports = {
launch: {
headless: false,
product: 'chrome',
args: ['--start-maximized'],
defaultViewport :{width: 1700, height: 800}

},

 browserContext: 'default',
connect: {
browserWSEndpoint: `wss://cdp.browserstack.com/puppeteer?caps=${encodeURIComponent(JSON.stringify(caps_chrome))}`,
}
}

Note: Copy ‘browserstack.username’ and ‘browserstack.accessKey’ from BrowserStack Account page.

Github Page Documents all different sets of capability options.

Step 2: Execute your scripts

In Visual Studio Code, Terminal enter the below command

npm run test

Once you enter the above command, the script starts executing; wait until it completes.

After completion of execution, we can see the result in the Browserstack Dashboard.

Step 3: View the Results in the Browserstack dashboard

Login to Browserstack and navigate to Dashboard,

Choose the build, and you will see the complete snapshot of your test.

In Conclusion,

Test automation is crucial for product teams to meet the demands of faster delivery and software quality. Running cross-browser Puppeteer tests in parallel allows testers to expand their test coverage, leading to the creation of better applications in quick time spans. Run your Puppeteer tests on local servers with BrowserStack Local, without compromising the security.

Get Started For Free