Quickstart

This quick start gives you all the info to create your first Browser check with Checkly. You should have some prior knowledge of working with Javascript and/or Node.js.

What is a Browser check?

A Browser check is a Node.js script that controls a headless Chromium browser to mimic user behavior. Load a web page, click a link, fill a form input – do everything your visitors might do and check if these interactions lead to the correct results.

Your critical interactions might be:

  • That users can log into my app.
  • That users can add products to a shopping cart.
  • That users can edit their account details.

The combination of automated interactions and assertions leads to confidence that your site works as expected.

Checkly uses the Playwright and Puppeteer frameworks to power your Browser checks. Use these frameworks to control the interactions you want to happen on a web page.

While Playwright and Puppeteer share many similarities, they have evolved at different speeds over the last two years. Playwright’s rapid release cycle and new features such as auto-waiting and the built-in inspector made it gain momentum in the developer community.

We recommend using Playwright if you are just starting out or migrating from Puppeteer to Playwright using puppeteer-to-playwright.

The following code is a valid Browser check.

const playwright = require('playwright')
const browser = await playwright.chromium.launch()
const page = await browser.newPage()
const response = await page.goto('https://checklyhq.com/')

if (response.status() > 399) {
 throw new Error(`Failed with response code ${response.status()}`)
}

await browser.close()
const puppeteer = require('puppeteer')
const browser = await puppeteer.launch()
const page = await browser.newPage()
const response = await page.goto('https://checklyhq.com/')

if (response.status() > 399) {
 throw new Error(`Failed with response code ${response.status()}`)
}

await browser.close()
Checkly currently supports using only Chromium with Playwright and Puppeteer.
Note: It is not possible to use both Playwright and Puppeteer in the same Browser Check script.

Breaking down a Browser check step-by-step

Let’s look at a more real life example and break down each step. The code below logs into Checkly, waits for the dashboard to fully load and then snaps a screenshot.

const playwright = require('playwright') // 1
const browser = await playwright.chromium.launch()
const page = await browser.newPage()

await page.goto('https://app.checklyhq.com/login') // 2

await page.type('input[type="email"]', 'john@example.com') // 3
await page.type('input[type="password"]','mypassword')
await page.click('.btn.btn-success.btn-block')

await page.waitForSelector('.status-table') // 4
await page.screenshot({ path: 'checkly_dashboard.png' })
await browser.close()
const puppeteer = require('puppeteer') // 1
const browser = await puppeteer.launch()
const page = await browser.newPage()

await page.goto('https://app.checklyhq.com/login') // 2

await page.type('input[type="email"]', 'john@example.com') // 3
await page.type('input[type="password"]','mypassword')
await page.click('.btn.btn-success.btn-block')

await page.waitForSelector('.status-table') // 4
await page.screenshot({ path: 'checkly_dashboard.png' })
await browser.close()

1. Initial declarations: We first import a framework (Puppeteer or Playwright) to control a browser. We also declare a browser and a page variable.

2. Initial navigation: We use the page.goto() method to load the first page.

3. Fill out input fields and submit: Using the page.type() and page.click() methods we enter our email address and password and click the login button. You would normally use environment variables here to keep sensitive data out of your scripts. See Login scenarios and secrets for more info.

4. Wait for dashboard and close: The expected behaviour is that the dashboard loads. In our case we can recognise this by the correct loading of the .status-table element in the page. For a visual reference, we also take a screenshot. We then close the browser. Our check is done.

How do I create a Browser check?

Every valid Puppeteer or Playwright script is a valid Browser check. You can create these scripts in two ways:

  1. By using Headless Recorder (our Chrome browser extension) to record a set of actions and generate the Playwright or Puppeteer script automatically.
  2. By writing the Node.js by hand.

A combination of both is also very common, i.e. you record the basic interactions with Headless Recorder and then tweak the generated code with extra things like passwords, extra wait conditions and content checks.

In both cases, you can always run and debug the script on your local machine and tweak it to perfection before uploading it to Checkly.

Every valid Playwright or Puppeteer script is a valid Browser check. If the script passes, your check passes. If the script fails, your check fails.

How do I assert assumptions?

Navigating around your app or site can already give you a lot of confidence your critical business processes are working correctly. However, many times you want to assert specific values on a page.

  • After login, you want the user name to be displayed.
  • On a dashboard, you want certain panels to be visible and filled with data.
  • Submitting a form should return a specific value.

To do this, you can:

  1. Use the popular Jest expect library (Recommended).
  2. Use Node’s built in assert function.
  3. Use the Chai.js library of TDD and BDD assertions.

You can use as many assertions in your code as you want. For example, in the code below we scrape the text from the large button on the Checkly homepage and assert it in two ways.

const playwright = require('playwright')
const expect = require('expect')

const browser = await playwright.chromium.launch()
const page = await browser.newPage()
await page.goto('https://checklyhq.com/')

// get the text of the button
const buttonText = await page.$eval('a.btn-lg', el => el.innerText)

// assert using Jest's expect function
expect(buttonText).toEqual('Start for free')

await browser.close()
const puppeteer = require('puppeteer')
const expect = require('expect')

const browser = await puppeteer.launch()
const page = await browser.newPage()
await page.goto('https://checklyhq.com/')

// get the text of the button
const buttonText = await page.$eval('a.btn-lg', el => el.innerText)

// assert using Jest's expect function
expect(buttonText).toEqual('Start for free')

await browser.close()

Note the following:

  • We use the page.$eval() method to grab the button element and get its innerText property.
  • We use a basic Jest expect().toEqual() statement to verify the text is correct.

When an assertion fails, your check fails. Your check’s result will show the log output for the error. Any configured alerting channels will be triggered, notifying your team that something is up.

failed api monitoring assertion

Next Steps

More Playwright and Puppeteer resources

  • Headless Automation guides, a free & open source knowledge base for Playwright and Puppeteer (maintained by Checkly).
  • playwright.dev is the official API documentation site for the Playwright framework.
  • awesome-playwright is a great GitHub repo full of Playwright-related libraries, tips and resources.
  • pptr.dev is the official API documentation site for the Puppeteer framework.
  • awesome-puppeteer is a great GitHub repo full of Puppeteer-related libraries, tips and resources.

You can contribute to this documentation by editing this page on Github