Meeshkan generated Puppeteer scripts with Jest and GitHub actions

COO & co-founder

Mar 23, 2021

Download the Puppeteer script screenshot

This blog is on the tail of some great news — Meeshkan now lets you export Puppeteer test case scripts! That changelog can be referred to here. This article is a great read if you're already a Meeshkan user and looking to implement the scripts in your workflow.

Some backstory #

Meeshkan as a "UI tests generated by your users and run automatically" — product was born in September of 2020. Before then we'd worked on all sorts of testing, mocking, and ambitious dev projects but they all culminated in this direction.

This is to say that downloading tests are a stepping stone to our product vision. It's an incredibly impactful step that fulfills the flow we've promised to Meeshkan users: record production user behavior, create test cases, and run them automatically against your staging branch.

Puppeteer and why we chose it #

Puppeteer is a Node library that provides a high-level API to control headless Chrome or Chromium over the DevTools Protocol. It can also be configured to use full (non-headless) Chrome or Chromium.
- Google Developers

Introducing new dependencies into someone's stack is a sacred thing. We're continuing to deliver on our value, by slotting into your workflow irrespective of the tooling you might be using. Meeshkan records browser events that can be transcribed into any browser scripting technology, and we had narrowed down our options to Selenium vs Puppeteer. Internally, we have a lot of experience with the Puppeteer API, and decided to go with that to better support our users and deliver a more fluid experience.

Now, let's implement!#

With the Puppeteer script, there are boundless possibilities. We'll walk through 3 levels of complexity and the benefits that they offer.

All of the following steps will require you to work with a downloaded script from a test case in Meeshkan. Visit an individual user story, and click the more button in the top right corner. Then click the button "Download Puppeteer script" from the drop down, and a file with the User Story's name and a .js extension should begin downloading.

Inside the codebase of the project you're working with, install puppeteer.

yarn add puppeteer --dev

yarn add puppeteer --dev

1. Out of the box Puppeteer #

With your JavaScript file downloaded, open it in the IDE of your choice (I'm using VS Code). This is what my file looks like (I've added a few comments for clarity):

// set-a-new-authentication-token.js
const puppeteer = require("puppeteer")

;(async () => {
    const browser = await puppeteer.launch({ headless: false })
    const page = await browser.newPage()

    await page.goto(`https://app.meeshkan.com/meeshkan-webapp`)
    await page.setViewport({
        width: 1903,
        height: 1057,
        deviceScaleFactor: 1,
    })
    await new Promise((r) => setTimeout(r, 5000))

    // Navigate to the settings page
    const button = await page.$x(
        "/html/body/div[1]/div/nav/div/div[4]/div/button[2]"
    )
    await button[0].click()
    await new Promise((r) => setTimeout(r, 5000))

    // Navigate to the details section
    const link = await page.$x(
        "/html/body/div[1]/div/nav/div/div[2]/div[2]/div/div[2]/a[3]"
    )
    await link[0].click()
    await new Promise((r) => setTimeout(r, 5000))

    // Fill in the key input
    const input1 = await page.$x(
        "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
    )
    await input1[0].click()
    await (
        await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[2]/input")
    )[0].type("test", { delay: 100 })
    await new Promise((r) => setTimeout(r, 5000))

    // Fill in the value input
    const input2 = await page.$x(
        "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
    )
    await input2[0].click()
    await (
        await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[3]/input")
    )[0].type("hello-world", { delay: 100 })
    await new Promise((r) => setTimeout(r, 5000))

    // Submit the form
    await page.click("button", { text: "Save token" })
    await new Promise((r) => setTimeout(r, 5000))

    // Delete the cookie (cleanup)
    const button1 = await page.$x(
        "/html/body/div[1]/div/div/div/div[6]/div[5]/button"
    )
    await button1[0].click()
    await new Promise((r) => setTimeout(r, 5000))

    await browser.close()
})()

// set-a-new-authentication-token.js
const puppeteer = require("puppeteer")

;(async () => {
    const browser = await puppeteer.launch({ headless: false })
    const page = await browser.newPage()

    await page.goto(`https://app.meeshkan.com/meeshkan-webapp`)
    await page.setViewport({
        width: 1903,
        height: 1057,
        deviceScaleFactor: 1,
    })
    await new Promise((r) => setTimeout(r, 5000))

    // Navigate to the settings page
    const button = await page.$x(
        "/html/body/div[1]/div/nav/div/div[4]/div/button[2]"
    )
    await button[0].click()
    await new Promise((r) => setTimeout(r, 5000))

    // Navigate to the details section
    const link = await page.$x(
        "/html/body/div[1]/div/nav/div/div[2]/div[2]/div/div[2]/a[3]"
    )
    await link[0].click()
    await new Promise((r) => setTimeout(r, 5000))

    // Fill in the key input
    const input1 = await page.$x(
        "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
    )
    await input1[0].click()
    await (
        await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[2]/input")
    )[0].type("test", { delay: 100 })
    await new Promise((r) => setTimeout(r, 5000))

    // Fill in the value input
    const input2 = await page.$x(
        "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
    )
    await input2[0].click()
    await (
        await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[3]/input")
    )[0].type("hello-world", { delay: 100 })
    await new Promise((r) => setTimeout(r, 5000))

    // Submit the form
    await page.click("button", { text: "Save token" })
    await new Promise((r) => setTimeout(r, 5000))

    // Delete the cookie (cleanup)
    const button1 = await page.$x(
        "/html/body/div[1]/div/div/div/div[6]/div[5]/button"
    )
    await button1[0].click()
    await new Promise((r) => setTimeout(r, 5000))

    await browser.close()
})()

This is a test that I'm setting up for the Meeshkan webapp to make sure that Meeshkan users can successfully add authentication tokens to their projects' settings page. The user story that triggered the generation of this Puppeteer script was created by Meeshkan users who performed this logic.

We're going to manually 'test' to see if this user story can run or, in other words, if users can perform this action. You'll want to be cd'd into the directory with the script and use node to invoke the Puppeteer script.

node ./tests/set-a-new-authentication-token.js

node ./tests/set-a-new-authentication-token.js

You should see a browser window pop open and be driven without any input needed. This can take a few seconds! There are two ways to know if the test is successful:

Watching — Does the correct thing happen before your eyes?
Terminal output — does the terminal complete without complaining or are there errors?

The type of errors that could pop up are those of basic assertions. These include:

A page doesn't exist
An element doesn't exist
An element does exist, but an action cannot be performed on it

For some, this is a bit too manual; let's see if we can add a bit of automation to this.

2. Puppeteer per commit with GitHub actions #

I really couldn't rave enough about GitHub actions and how smooth the workflow is (once you get past the unforgivingness of YAML syntax, that is 😉).

Navigating to the "Actions" tab in GitHub, let's create a new workflow. This will open a draft editor with a folder/file structure of .github/workflows/main.yaml relative to the root of your repository.

Create a new GitHub action

The initial YAML file will have comments at almost every line explaining the make-up of a GitHub Action file.

First, we'll change the name of the Test suite to "Meeshkan tests"
Then change the on: or frequency of test runs to push
Create our first job that sets up the node environment, installs dependencies, and runs the Puppeteer script.

#  main.yaml
name: Meeshkan tests

on: push

jobs:
  trigger-puppeteer:
  name: Run the puppeteer scripts generated by Meeshkan
  runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: '14'

      - name: Install dependencies & Run test
        run: |
          yarn install --prefer-offline --frozen-lockfile
          node ./tests/set-a-new-authentication-token.js

#  main.yaml
name: Meeshkan tests

on: push

jobs:
  trigger-puppeteer:
  name: Run the puppeteer scripts generated by Meeshkan
  runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: '14'

      - name: Install dependencies & Run test
        run: |
          yarn install --prefer-offline --frozen-lockfile
          node ./tests/set-a-new-authentication-token.js

Now, what we previously did locally will run per-commit via GitHub actions.

This is still light on the assertions though. In the next step, we'll look into defining more conditions for the test to succeed.

3. Writing assertions with Jest #

Jest is a super popular JavaScript testing framework that allows you to write tests simply. This is the option that Meeshkan internally chose. We already had Jest installed in our repo, so it was an easy extension for us.

To extend Jest with Puppeteer, we will use jest-puppeteer. I'd suggest following the setup details in this repository. The important bits I found:

Your jest.config.js should now define the preset as jest-puppeteer.
Make sure you don't have a testEnvironment set from a previous or default configuration; the package will take care of this.
If you're using TypeScript, check out this documentation as well.

// This is what our jest.config.js looks like
module.exports = {
    displayName: "webapp",
    preset: "jest-puppeteer",
    moduleFileExtensions: ["ts", "tsx", "js", "jsx"],
}

// This is what our jest.config.js looks like
module.exports = {
    displayName: "webapp",
    preset: "jest-puppeteer",
    moduleFileExtensions: ["ts", "tsx", "js", "jsx"],
}

Writing assertions are straightforward functions. We'll be describing a user story, which Jest will call a test suite, declaring its expectations at certain points. I will be breaking the suite up into logical steps via assertions. First, let's look at one step.

// This + the jest-puppeteer preset will handle our environment and expose some new functionality like '.toMatch()'
import "expect-puppeteer"

describe('Save an authentication token', () => {
// Setup & steps
    it('clicks submit on the form', async () => {
        await page.click('button', { text: 'Save token' });
        await expect(page).toClick('button', { text: 'Save token' });

        await new Promise((r) => setTimeout(r, 5000));
    }, 100000);
// More steps
}

// This + the jest-puppeteer preset will handle our environment and expose some new functionality like '.toMatch()'
import "expect-puppeteer"

describe('Save an authentication token', () => {
// Setup & steps
    it('clicks submit on the form', async () => {
        await page.click('button', { text: 'Save token' });
        await expect(page).toClick('button', { text: 'Save token' });

        await new Promise((r) => setTimeout(r, 5000));
    }, 100000);
// More steps
}

describe expects it statements and succeeds or fails depending on each assertion. Let's make sure that this works locally before moving on. The full file we're operating with is:

// meeshkan-exports.test.js
import "expect-puppeteer"

describe("Save an authentication token", () => {
    jest.setTimeout(100000)

    beforeAll(async () => {
        await page.setCookie({
            name: "a0:session",
            value: process.env.COOKIE,
            domain: process.env.TEST_URL.startsWith("localhost")
                ? "localhost"
                : process.env.TEST_URL,
        })
        await page.goto(
            `${
                process.env.TEST_URL.startsWith("localhost") ? "http://" : "https://"
            }${process.env.TEST_URL}/meeshkan-webapp`
        )
        await page.setViewport({
            width: 1813,
            height: 1057,
            deviceScaleFactor: 1,
        })
        await new Promise((r) => setTimeout(r, 10000))
    })

    it("loads the dashboard", async () => {
        await expect(page).toMatch("Confidence score")
    })

    it("should navigate to the settings page", async () => {
        const button = await page.$x(
            "/html/body/div[1]/div/nav/div/div[4]/div/button[2]"
        )
        await button[0].click()
        await page.waitForNavigation()
        await new Promise((r) => setTimeout(r, 1000))
    }, 100000)

    it("fills out the form", async () => {
        // Navigate to the details section
        const link = await page.$x(
            "/html/body/div[1]/div/nav/div/div[2]/div[2]/div/div[2]/a[3]"
        )
        await link[0].click()

        // Fill in the key input
        const input1 = await page.$x(
            "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
        )
        await input1[0].click()
        await (
            await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[2]/input")
        )[0].type("test", { delay: 100 })

        // Fill in the value input
        const input2 = await page.$x(
            "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
        )
        await input2[0].click()
        await (
            await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[3]/input")
        )[0].type("hello-world", { delay: 100 })

        // Asserts the form should be filled
        await expect(page).toFillForm('form[name="createAnAuthenticationToken"]', {
            key: "test",
            value: "hello-world",
        })
    }, 100000)

    it("clicks submit on the form", async () => {
        await page.click("button", { text: "Save token" })
        await expect(page).toClick("button", { text: "Save token" })

        await new Promise((r) => setTimeout(r, 5000))
    }, 100000)

    it("deletes the token", async () => {
        const button1 = await page.$x(
            "/html/body/div[1]/div/div/div/div[6]/div[5]/button"
        )
        await button1[0].click()

        await new Promise((r) => setTimeout(r, 5000))
        await expect(page).not.toMatch("hello-world")
    }, 100000)
})

// meeshkan-exports.test.js
import "expect-puppeteer"

describe("Save an authentication token", () => {
    jest.setTimeout(100000)

    beforeAll(async () => {
        await page.setCookie({
            name: "a0:session",
            value: process.env.COOKIE,
            domain: process.env.TEST_URL.startsWith("localhost")
                ? "localhost"
                : process.env.TEST_URL,
        })
        await page.goto(
            `${
                process.env.TEST_URL.startsWith("localhost") ? "http://" : "https://"
            }${process.env.TEST_URL}/meeshkan-webapp`
        )
        await page.setViewport({
            width: 1813,
            height: 1057,
            deviceScaleFactor: 1,
        })
        await new Promise((r) => setTimeout(r, 10000))
    })

    it("loads the dashboard", async () => {
        await expect(page).toMatch("Confidence score")
    })

    it("should navigate to the settings page", async () => {
        const button = await page.$x(
            "/html/body/div[1]/div/nav/div/div[4]/div/button[2]"
        )
        await button[0].click()
        await page.waitForNavigation()
        await new Promise((r) => setTimeout(r, 1000))
    }, 100000)

    it("fills out the form", async () => {
        // Navigate to the details section
        const link = await page.$x(
            "/html/body/div[1]/div/nav/div/div[2]/div[2]/div/div[2]/a[3]"
        )
        await link[0].click()

        // Fill in the key input
        const input1 = await page.$x(
            "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
        )
        await input1[0].click()
        await (
            await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[2]/input")
        )[0].type("test", { delay: 100 })

        // Fill in the value input
        const input2 = await page.$x(
            "/html/body/div[1]/div/div/div/div[6]/form/div[2]/input"
        )
        await input2[0].click()
        await (
            await page.$x("/html/body/div[1]/div/div/div/div[6]/form/div[3]/input")
        )[0].type("hello-world", { delay: 100 })

        // Asserts the form should be filled
        await expect(page).toFillForm('form[name="createAnAuthenticationToken"]', {
            key: "test",
            value: "hello-world",
        })
    }, 100000)

    it("clicks submit on the form", async () => {
        await page.click("button", { text: "Save token" })
        await expect(page).toClick("button", { text: "Save token" })

        await new Promise((r) => setTimeout(r, 5000))
    }, 100000)

    it("deletes the token", async () => {
        const button1 = await page.$x(
            "/html/body/div[1]/div/div/div/div[6]/div[5]/button"
        )
        await button1[0].click()

        await new Promise((r) => setTimeout(r, 5000))
        await expect(page).not.toMatch("hello-world")
    }, 100000)
})

The frontend team at Meeshkan uses NX as a set of dev-tools to manage our mono-repo. It makes it super slick to run tests, deploy incrementally, share resources (called libs), etc.

jest

So our test command is not likely how you'd do it. Depending on your set up, you'll run something like:

jest

jest

This is where you would take the time to swap out your base URL (process.env.TEST_URL), and add cookies if your service/user story requires you to be registered.

Once you've verified the behavior locally, we'll implement this newly found functionality in our GitHub action!

Green checks on GitHub

Now to get the green checks on a GitHub PR, more specific conditions will need to be met. The file will now read:

#  main.yaml
name: Meeshkan tests

on: push

jobs:
  run-jest-puppeteer-scripts:
  name: Run the puppeteer scripts generated by Meeshkan
  runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: '14'

      - name: Install dependencies & Run test
        run: |
          yarn install --prefer-offline --frozen-lockfile
          jest

#  main.yaml
name: Meeshkan tests

on: push

jobs:
  run-jest-puppeteer-scripts:
  name: Run the puppeteer scripts generated by Meeshkan
  runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v1
        with:
          node-version: '14'

      - name: Install dependencies & Run test
        run: |
          yarn install --prefer-offline --frozen-lockfile
          jest

4. Bonus — using `await-vercel`#

Since Meeshkan uses Vercel, we also implemented an interesting workaround to test our hosted staging environment instead of a local build. The GitHub action await-vercel allows us to define the URL and poll for it to be finished deploying.

We suggest a parallel setup for whichever host you use as some issues only come out of the woodwork when hosted.

First, we add a job to the beginning of our main.yml file. You'll then add your team's Vercel token as a GitHub secret to the repository you're testing and pass it as an environment variable.

#  main.yaml
jobs:
  wait-for-vercel-deployment:
    runs-on: ubuntu-18.04
    steps:
      - uses: UnlyEd/github-action-await-vercel@v1.1.0
        id: await-vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

#  main.yaml
jobs:
  wait-for-vercel-deployment:
    runs-on: ubuntu-18.04
    steps:
      - uses: UnlyEd/github-action-await-vercel@v1.1.0
        id: await-vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}

If you were to only be testing against a non-closing branch, like staging, you can pass the deployment-url hardcoded as such:

+        with:
+         deployment-url: your-env-team.vercel.app

+        with:
+         deployment-url: your-env-team.vercel.app

If you work with feature branches, we'll need to set this dynamically! We'll add three new steps that:

Get the branch name and then
Transform that to the deployment URL which is stored as a step variable named branch and finally
Display the status of the deployment URL.

Vercel settings

Vercel uses a deployment URL pattern of ${projectName}-git-${branchName}-${teamName}.vercel.app. You can find the project name and team name in the URL or settings of your project. Our project name in this screenshot is webapp and team name meeshkanml.

This is our await-vercel configuration so far:

#  main.yaml
jobs:
  wait-for-vercel-deployment:
    runs-on: ubuntu-18.04
    steps:
      - name: Get branch name
        id: branch
        run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"

      - name: Get deploy url
        id: url
        run: echo webapp-git-${{ steps.branch.outputs.branch }}-meeshkanml.vercel.app

      - uses: UnlyEd/github-action-await-vercel@v1.1.0
        id: await-vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        with:
          deployment-url: webapp-git-${{ steps.branch.outputs.branch }}-meeshkanml.vercel.app
          timeout: 60 # Wait for 1 minute before failing

      - name: Display deployment status
        run: "echo The deployment at ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).url }} is ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).readyState }}"

#  main.yaml
jobs:
  wait-for-vercel-deployment:
    runs-on: ubuntu-18.04
    steps:
      - name: Get branch name
        id: branch
        run: echo "##[set-output name=branch;]$(echo ${GITHUB_REF#refs/heads/})"

      - name: Get deploy url
        id: url
        run: echo webapp-git-${{ steps.branch.outputs.branch }}-meeshkanml.vercel.app

      - uses: UnlyEd/github-action-await-vercel@v1.1.0
        id: await-vercel
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        with:
          deployment-url: webapp-git-${{ steps.branch.outputs.branch }}-meeshkanml.vercel.app
          timeout: 60 # Wait for 1 minute before failing

      - name: Display deployment status
        run: "echo The deployment at ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).url }} is ${{ fromJson(steps.await-vercel.outputs.deploymentDetails).readyState }}"

Finally, you'll want to make sure that this step blocks the testing step that we configured above! You'll do this by passing needs: wait-for-vercel-deployment to the run-jest-puppeteer-tests step.

#  main.yaml
name: Meeshkan tests

on: push

jobs:
  wait-for-vercel-deployment:
    # what we wrote for waiting for vercel here

  run-jest-puppeteer-tests:
    needs: wait-for-vercel-deployment
    # what we wrote for running tests here

#  main.yaml
name: Meeshkan tests

on: push

jobs:
  wait-for-vercel-deployment:
    # what we wrote for waiting for vercel here

  run-jest-puppeteer-tests:
    needs: wait-for-vercel-deployment
    # what we wrote for running tests here

In conclusion #

Meeshkan outputting Puppeteer scripts is the first step in running tests generated by your users for a better release experience. How you implement these may vary from the above, so please get in touch if you have questions, or a cool new way of implementing it yourself that you'd like us to add!

Newer post Older post

Don’t miss the next post!

Absolutely no spam. Unsubscribe anytime.

Meeshkan generated Puppeteer scripts with Jest and GitHub actions

Some backstory.css-1jyz0wa{color:var(--chakra-colors-gray-700);font-weight:var(--chakra-fontWeights-normal);outline:2px solid transparent;outline-offset:2px;opacity:0;margin-left:var(--chakra-space-2);}.css-1jyz0wa:focus,.css-1jyz0wa[data-focus]{opacity:1;box-shadow:var(--chakra-shadows-outline);}#

Puppeteer and why we chose it#

Now, let's implement!#

1. Out of the box Puppeteer#

2. Puppeteer per commit with GitHub actions#

3. Writing assertions with Jest#

4. Bonus — using await-vercel#

In conclusion#