Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

The motivation behind the package is to provide a simple interface on top of Puppeteer. In terms of interaction with the page and running expectations.

Miss Piggy - Test runner for Puppeteer

Quick start

First install the package via

> npm install miss-piggy


> yarn add miss-piggy

Then create a scenario file scenario.spec.js with the following content:

module.exports = {
  description: "Verifying that I'm saying the age of my blog",
  steps: [
    async (context) => {
      await``, {
        waitUntil: "domcontentloaded",
    async (context) => {
      await context.clickByText("Stats");
      await context.waitForNavigation();
  expectations: [
      pageURLPattern: /blog\/stats$/,
      items: [
          where: "html",
          value: /This blog is (\d+) years old/,

And finally run ./node_modules/.bin/miss-piggy --verbose=1. The result will be:

🖥️  Spec files found in /Users/krasimir/Work/Krasimir/miss-piggy:
  ⚙️ /examples/scenario.spec.js


  Description: Verifying that I'm saying the age of my blog
  File: scenario.spec.js
  ⚙️ step 1/2
    ❯ about:blank
  ⚙️ step 2/2


  📋 Test summary:
    no expectations for this page
    ✅ html: /This blog is (\d+) years old/

  The /logs/scenario.spec.js/report.log file is generated.


  ✨ Results:
    ✅ /examples/scenario.spec.js

After the execution of the scenarios the runner creates bunch of logs that show you how the step went. In those logs you'll see how the HTML was before and after the step, screenshots, console log messages, errors and requests. Our little example above for example produced:

log example



Arguments that you can pass to the miss-piggy:

arg value description
--spec Path to a file. It runs a single spec file.
--specPattern Regexp string. Default set to "spec\.js" A pattern which will match your spec files.
--specDir Path. By default is the directory where the process is started Defines where the module will search for spec files.
--verbose Default is false If you pass this argument you'll get a bit more information on what is the current page URL and what the browser is doing.
--logDir Path. By default is set to "logs" Where the module will place the logs.


> ./node_modules/.bin/miss-piggy --verbose --spec=./myspecfile.spec.js

Writing spec files

The overall format of the spec file should be:

module.exports = {
  description: "<text>",
  steps: [ <step definition> ],
  expectations: [ <expectation definition> ],

Defining a step

A step is basically an async function that receives a single argument - context. It's an object that contains the following methods/properties:

property description
browser The result of await puppeteer.launch()
page The result of await browser.newPage()
async clickByText(, selector = '*', idx = 0) A function that clicks on a element in the page. The first argument is a string or a xpath. The second argument let you specify the tag name of the DOM element. By default is set to * which basically means every element. And the last argument of the function is an number specifying which of the matched element to be clicked (if there are more elements matching).
async type(, xpath = '//input', idx = 0) Types the provided string to a DOM element matching the xpath. The index as a third argument is needed if more then one elements is matching.
async delay() A function to pause the step.
async screenshot() Well, creates a screenshot. The file is placed in the logs folder
async waitForNavigation() If you need to wait for a page load. It's basically a direct proxy to Puppeteer's waitForNavigation.
async getPageURL() A function that returns the current page URL
async content() It gives you the HTML of the current page
pageLog An array of items that represent console logs/errors and requests happening inside the browser.


The expectations are objects that have pageURLPattern and items. The pattern is a regular expression that will match the URL of your page. In the items we pass other objects with two properties - where and value. The where is specifying the area which you want to expect. And the value is the actual item that you are searching for. For example:

    pageURLPattern: /blog\/stats$/,
    items: [
        where: "html",
        value: /This blog is (\d+) years old/,

Here are the supported item pairs:

Google analytics dataLayer.

  where: "dataLayer",
  value: ["event", "conversion", { send_to: "xxxx", allow_custom_scripts: true }],

Search in the HTML. value could be also an xpath or RegExp.

  where: "html",
  value: "Test runner for Puppeteer",

Matching the URL by a given string. The value could be a string but also a RegExp.

  where: "url",
  value: "users/registration/thank-you",

Matching http request.

    where: "request",
    value: {
      method: "GET",
      url: "",



Test runner for Puppeteer




No releases published


No packages published