Using Snippets

Reuse code by creating and importing snippets in any Browser check via the Node.js require function (require(./snippets/my-snippet.js)).

Snippets are handy when multiple Browser checks target the same site or web app and share test instruction for:

  • a common login procedure
  • a common navigation flow
  • a common setup and/or teardown procedures

How to use snippets in Browser checks

Using snippets is straightforward.

  1. Create a JavaScript snippet. Note that the snippet name will be used as its filename.
  2. Load and require the snippet by referencing it from the ./snippets/ root folder.

Snippets work like any Javascript file on your local disk in a Node.js context so that you can expose functions and properties on the module.exports object.

Note: we used to recommend the Handlebars syntax to run snippts. It’s now deprecated. Use require and exported functions to DRY up your code.

Example: GitHub login

Say we want to validate some parts of the GitHub website only available to logged in users. We want to have separate, small browser checks to have granular feedback whether each part functions.

Create a snippet named github_login in the “code snippets” section with a function that executes the login routine.

async function gitHubLogin (page, username, password) {
  await page.goto("https://github.com/login")
  await page.type("#login_field", username)
  await page.type("#password", password)
  await page.click('[name="commit"]')
}

module.exports = {
  gitHubLogin
}
async function gitHubLogin (page, username, password) {
  await page.goto("https://github.com/login")
  await page.type("#login_field", username)
  await page.type("#password", password)
  await page.click('[name="commit"]')
}

module.exports = {
  gitHubLogin
}

Notice three things:

  • We created a standard async function that expects three parameters: the page object, a username and a password variable.
  • We exported this function on the standard module.exports object.
  • You now have a function you can call in any of your Browser checks to perform a login on GitHub.

Your snippet should look like this now.

github login snippet example

Create a new browser check and require the code snippet you just created.

const playwright = require('playwright')
const { gitHubLogin } = require('./snippets/github_login.js')

const browser = await playwright.chromium.launch()
const page = await browser.newPage()

await gitHubLogin(page, process.env.GITHUB_USER, process.env.GITHUB_PWD)

// your normal check code
await page.click('.header-search-input')
const puppeteer = require('puppeteer')
const { gitHubLogin } = require('./snippets/github_login.js')

const browser = await puppeteer.launch()
const page = await browser.newPage()

await gitHubLogin(page, process.env.GITHUB_USER, process.env.GITHUB_PWD)

// your normal check code
await page.waitForSelector('.application-main')
await page.click('.header-search-input')

Notice we are referencing the GITHUB_USER and GITHUB_PWD environment variables and passing them to the gitHubLogin() function. You should store these in your environment variables.

Legacy: Handlebars Syntax

We still support our legacy Handlebars syntax for referencing snippets in Browser check code but recommend using the require syntax discussed at the beginning of this document.

You can reuse commonly used parts of code by referencing code snippets in any browser check. To do this, you use the Handlebars partial notation {{> my_code_snippet }}.

This comes in very handy when you have multiple browser checks targeting the same site or web app that share a:

  • common login procedure
  • common navigation flow
  • common setup and/or teardown procedures

Using partials is very straightforward. Any code snippets are just copied inline as is.

Example: GitHub login

Say we want to validate some parts of the GitHub website only available to logged in users. We want to have separate, small browser checks to have granular feedback whether each part functions.

  1. Create a snippet named github_login in the “code snippets” section with the code below.
const playwright = require('playwright')
const browser = await playwright.chromium.launch()
const page = await browser.newPage()

await page.goto('https://github.com/login')
await page.type('#login_field', process.env.GITHUB_USER)
await page.type('#password', process.env.GITHUB_PWD)
await page.click('[name="commit"]')
const puppeteer = require('puppeteer')
const browser = await puppeteer.launch()
const page = await browser.newPage()

await page.goto('https://github.com/login')
await page.type('#login_field', process.env.GITHUB_USER)
await page.type('#password', process.env.GITHUB_PWD)
await page.click('[name="commit"]')

Notice we are referencing the GITHUB_USER and GITHUB_PWD environment variables. All environment variables are available in partials / snippets, just like in “normal” browser check scripts. Your snippet should look like the screenshot below.

browser check code snippet

  1. Create a new browser check. Reference the code snippet you just created as a partial. After this, just continue with the normal check. During execution, the code snippet will be inlined before the script is run.
    {{> github_login}}

    // your normal check code
    await page.click('.header-search-input')
    {{> github_login}}

    // your normal check code
    await page.waitForSelector('.application-main')
    await page.click('.header-search-input')

Passing variables to partials

You might want to create a partials that has a generic login routine and then pass it different username / password combinations based on your script. Or you might want to pass other variables to your partials.

Under the hood, we use Handlebars' partials and it supports passing variables. Let’s look at the following example:

This is our partial. We call it log_things.

console.log({{username}})
console.log({{password}})
console.log('{{extra}}')

This is our browser script, using the partial. We fly in two environment variables USERNAME and PASSWORD.

{{> log_things username="process.env.USER" password="process.env.PWD" extra="text" }}

Notice three things:

  1. All partial variables are passed in as key/value pairs, where the value is a “string”.
  2. The environment variables process.env.xxx are evaluated to a string in the partial.
  3. A standard string like the extra="text" pair is passed as is. Notice the extra quotes in the partial.

Using Handlebars helpers

We’ve extended the Handlebars templating system with some handy helpers to make our webhooks even more powerful.

You can find the full list of helpers in the README.md file of the underlying library we are using.


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