Categories
API Testing Automated Testing

API “approval” testing using Jest

I recently added some API integration testing examples to my Playwright/Jest e2e automated testing repository using Supertest.

I wanted to also explore the use of Jest for approval testing of REST JSON APIs.

Jest has in built support for snapshot testing which is most commonly used to test how React components are rendered – however Jest snapshot testing can also be used to test any serializable values.

Snapshot tests are an example of what are are also known as approval tests: whereby the expected output of a test is generated the first time it is run and compared against this on subsequent runs. Changes to the output can be “approved” which become the new baseline.

These are no where near as common as “assertion” based tests whereby an automated test performs some action and asserts some results.

Assertion tests can be used to assist test driven development, whereas approval tests are generated after the fact so they can be useful for outside-in software development, API integration testing of known endpoints, and for legacy code where no assertion based or lower level tests exist.

I wrote the same integration tests in both approval and assertion style to show how these differ.

Say we have an endpoint that returns all the blog posts we have seeded into our system, we could write some assertions on the content:

const response = await request.get('/posts')
expect(response.status).toBe(200)
expect(response.body.length).toBe(3)
expect(response.body[0].id).toBe(1)
expect(response.body[0].title).toBe('Post 1')
expect(response.body[1].id).toBe(2)
expect(response.body[1].title).toBe('Post 2')
expect(response.body[2].id).toBe(3)
expect(response.body[2].title).toBe('Post 3')

Since we’re testing an existing endpoint with known “approved” behaviour we can generate and test a snapshot of it:

  const response = await request.get('/posts')
  expect(response.status).toBe(200)
  expect(response.body).toMatchSnapshot()

The first time we run this the following is generated in a separate file:

// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`can GET a REST API and check response using approval style 1`] = `
Array [
  Object {
    "id": 1,
    "title": "Post 1",
  },
  Object {
    "id": 2,
    "title": "Post 2",
  },
  Object {
    "id": 3,
    "title": "Post 3",
  },
]
`;

We commit this to our codebase and if any of the body returned for this endpoint is changed our test fails (with an option to approve the new result as the new baseline).

The benefit of these approval tests is they are quicker to write for an existing endpoint (since they are generated automatically) and are complete in that any change to the body returned will be highlighted – compared to our assertion based tests which only test specific things.

The downside to these tests is they are generated after the fact – so aren’t compatible with test driven development – and need to take into account if there is any dynamic content that changes between test runs – so these generally aren’t good for non-deterministic systems.

Feel free to check out the source code for these API integration tests and let me know what you think and whether you’ve had experience, good or bad, with approval testing.

Categories
e2e Testing

Playwright + Jest = 💖

We were looking at a possible replacement for our dated Protractor + Cucumber e2e testing framework. As we move away from Angular to React microapps we have found that Protractor doesn’t work very well/efficiently and cucumber isn’t giving us any benefits.

It was a good opportunity to do some research/tinkering to answer the question lingering in my mind: in 2020 what e2e testing tool would I use by default for a dynamic react based web application?

After some experimentation it came down to Puppeteer + Jest or Playwright + Jest. I’ll compare those in this post.

Why Jest?

As explained previously we don’t need a BDD framework, but we do need something that allows us to specify our tests, create assertions and run these tests (in parallel). Jest, particularly when using the Jest Circus test runner, seems the most mature tool in this regard in 2020. Whilst Jest is often associated with React as it handles the snapshot test results also, it doesn’t need to be used with React and it’s possible and easy to use it as a standalone Node.js testing library.

Parallel Support

Jest by default runs tests across files in parallel and uses the available resources to scale appropriately using processes/threads. I’ve found this particularly good as I write independent e2e tests which can scale through parallelism, and using Puppeteer and Playwright you can spawn new incognito browser contexts to run these.

Auto-Retry Support

Whilst I believe in writing deterministic e2e automated tests, since e2e tests are full-stack there are often external dependencies and services beyond our control (like a third party domain provider) and I’d rather prioritize test reliability over test perfection. With this mind I think it’s important to be able to automatically retry a single failing test scenario before failing a build, and the Jest Circus test runner supports this:

jest.retryTimes(1)

test('can wait for an element to appear', async () => {
  global.page = await pages.spawnPage()
  await nav.visitHomePage(global.page)
  await global.page.waitForSelector('#elementappearschild', { visible: true, timeout: 5000 })
}, jestTimeoutMS)

HTML Reports and Screenshots

Nice looking HTML reports are easy to achieve by using jest-stare and screenshots are easy to generate using Jest Circus hooks.

Playwright or Puppeteer?

I’m a fan of Puppeteer however Playwright is a much nicer browser automation library. Whilst it adds support for Firefox and Webkit, even if you’re running your e2e tests in one browser (Chromium) I’d still recommend Playwright over Puppeteer any day of the week. Here’s why:

Automatic Waiting

I’ve found the automatic waiting in Playwright just works™️ Especially when dealing with dynamically rendered react web apps I’ve found my Puppeteer code looks is full of page.waitFor calls to make it run reliably:

await page.waitFor('#loadedchild', { visible: true, timeout: 5000 })

Whilst this is occasionally necessary in Playwright (in particular waiting for an iFrame to switch into), I’ve found it’s almost never required which reminds me of good old Watir days.

Nicer API

Whilst the APIs are similar, Playwright is just nicer to use. Take grabbing some text from a div, in Puppeteer:

await page.goto(`${config.get('baseURL')}`)
await page.waitFor('#loadedchild', { visible: true, timeout: 5000 })
const element = await page.$('#loadedchild')
const text = await (await element.getProperty('textContent')).jsonValue()
expect(text).toBe('Loaded!')

In Playwright:

await page.goto(`${config.get('baseURL')}`)
const text = await page.textContent('#loadedchild')
expect(text).toBe('Loaded!')

Summary

If I was writing an e2e web testing framework from scratch in 2020 I would use Playwright + Jest. Playwright offers automatic waiting and a nice API, whilst Jest offers a solid runner with parallel support, automatic retries and the ability to easily generate HTML reports and capture screenshots.

I’ve created one repository for Playwright + Jest #
And another for Puppeteer + Jest to compare #

As an aside we put changing node libraries on hold for our e2e test framework and will look at some test infrastructure improvements instead.