Martin Grandrath

How to use Jest matchers with Vitest

Sun, 07 Jul 2024 00:00:00 GMT

A while ago I migrated a test suite from Jest to Vitest. Every thing went fine except that I needed to find out how we could continue to use jest-dom with Vitest. Jest-dom is useful when writing tests for DOM elements with testing-library. It provides handy assertions like for example expect(someButton).toBeDisabled().

Luckily Vitest is largely compatible with Jest and so Jest matchers can be used as is.

First we need to create a setup file. I use the name vitest-setup.mjs but it can be anything you like. Just make sure it matches the configuration below.

// vitest-setup.mjs

import { expect } from "vitest";
import * as matchers from "@testing-library/jest-dom/matchers";

expect.extend(matchers);

Next we add the setup file to the configuration.

// vitest.config.mjs

import { defineConfig } from "vitest/dist/config";

export default defineConfig({
  test: {
    setupFiles: ["./vitest-setup.mjs"],
  },
});

In case we are using TypeScript we need to add the additional matchers to Vitest's types.

// vitest-testing-library-matchers.d.ts

import "vitest";
import type { TestingLibraryMatchers } from "@testing-library/jest-dom/types/matchers";

declare module "vitest" {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  interface Assertion<T = any> extends TestingLibraryMatchers<T, void> {}
}

Ensure that TypeScript picks up this declaration file.

// tsconfig.json

{
  "include": ["*.d.ts", …],
  …
}

Now we can write tests that make use of Jest-dom. 🎉

// greeting.spec.tsx

import { describe, expect, it } from "vitest";
import { render, screen } from "@testing-library/react";
import { Greeting } from "./greeting";

describe("<Greeting>", () => {
  it("should say Hello", () => {
    render(<Greeting name="Vitest" />);
    const heading = screen.getByRole("heading");
    expect(heading).toHaveTextContent("Hello, Vitest!");
  });
});

100% code coverage? Easy!

Sun, 23 Jun 2024 00:00:00 GMT

"Code coverage" measures the amount of production code (usually as a percentage) that is executed when running the test suite. It is often used as a proxy metric for assessing the overall test quality of a code base. Code analysis tools like SonarQube are able to, for example, fail the build pipeline if the code coverage metric falls below a certain threshold.

There is however a subtle shortcoming of this metric that too few people seem to be aware of. As I said it measures the amount of production code that is executed when running the test suite. It does not take into account whether the test does anything meaningful with that.

Let's create a small example to illustrate the issue. Take this straightforward FizzBuzz implementation and an accompanying test that tests nothing:

// fizz-buzz.ts
export const fizzBuzz = (n: number): string => {
  const fizz = n % 3 ? "Fizz" : "";
  const buzz = n % 5 ? "Buzz" : "";

  return fizz + buzz || String(n);
};

// fizz-buzz.test.ts
describe("fizzBuzz", () => {
  it("implements Fizz Buzz", () => {
    expect(1).toEqual(1);
  });
});

Running the test (e.g. running vitest with the --coverage flag) results in a code coverage of 0% – no surprise there. But what happens if we call the fizzBuzz function inside our test?

// fizz-buzz.test.ts
import { fizzBuzz } from "./fizz-buzz.ts"

describe("fizzBuzz", () => {
  it("implements Fizz Buzz", () => {
    // call to `fizzBuzz` without doing anything with its result
    fizzBuzz(1);

    expect(1).toEqual(1);
  });
});

Now we measure a code coverage of 100% of lines and 66.66% of branches:

--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |     100 |    66.66 |     100 |     100 |                   
 fizz-buzz.ts |     100 |    66.66 |     100 |     100 | 2-3               
--------------|---------|----------|---------|---------|-------------------

We can take this further by adding more calls to our test that cover all the different cases:

// fizz-buzz.test.ts
import { fizzBuzz } from "./fizz-buzz.ts"

describe("fizzBuzz", () => {
  it("implements Fizz Buzz", () => {
    fizzBuzz(1);
    fizzBuzz(3);
    fizzBuzz(5);
    fizzBuzz(15);

    expect(1).toEqual(1);
  });
});

Now our code coverage passes with flying colors:

--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |     100 |      100 |     100 |     100 |                   
 fizz-buzz.ts |     100 |      100 |     100 |     100 |                   
--------------|---------|----------|---------|---------|-------------------

The point I'm trying to make is that you need to be mindful when it comes to code coverage as a quality metric. Be aware that a development team needs to care about code and test quality. Measuring code coverage and making it visible is a sensible thing to do but requiring a minimum coverage value might do more harm than good if a team has no stakes or interest in actual code quality.

Testing touch gestures with Playwright

Wed, 01 May 2024 00:00:00 GMT

Recently I needed to find a way to implement an automated test that ensured that the pinch-to-zoom gesture (i.e. placing two fingers on the screen and moving them apart to zoom in) worked on a page in mobile browsers. "But," I hear you object, "why would you want to test pinch-to-zoom? It's a native browser feature. It doesn't make sense to test it." Yes, it is true that the zoom gesture is a browser feature. And it is also true that we don't need to test it's implementation. But it is also the case that our own page can contain code that disables the native behavior. In our particular case we were including a third party library that contained some CSS that disabled some gestures in order for that library to handle them itself. This piece of CSS sneaked in as part of an update and kept unnoticed for quite some time. When we realized that zooming in on the page did not work anymore we decided to look into creating an automated test to prevent this issue to come up again in the future.

Playwright and the Chrome DevTools Protocol

To simulate a pinch-to-zoom gesture we need to dispatch two touchstart events (one for the thumb and one for the index finger) followed by touchmove events that represent moving the fingers apart and finally two touchend events for lifting the fingers up and thus ending the gesture. Unfortunately Playwright does not support these touch events directly (as of version 1.43.1). While the Mouse class offers methods like down(), move() and up() for clicking and dragging with a mouse, the Touchscreen class only implements a tap() method for simple one-finger taps on the screen.

We found a workaround for this limitation though. Playwright provides the CDPSession class. It enables Playwright tests to issue raw Chrome DevTools Protocol (CDP) commands. Among other things these commands include a variety of input events. It's important to point out that the Chrome DevTools Protocol is browser dependent and can not be used for testing Firefox. This was acceptable in our use case because we wanted to detect if some code (CSS or otherwise) broke the native zoom behavior. Of course we would not detect an issue with pinch-to-zoom that only affects non-Chrome browsers. While this is certainly not ideal it's better than nothing and it was able to detect the actual issue at hand.

CDP provides a single command for triggering pinch-to-zoom gestures: Input.synthesizePinchGesture. It accepts coordinates for the center of the gesture as well as a scale factor which determines whether the page should be zoomed in (i.e. moving the fingers apart) or zoomed out (i.e. moving the fingers towards each other). Unfortunately it is marked as experimental and we had issues with it in our CI/CD pipeline. Instead we simulated the pinch gesture using three Input.dispatchTouchEvent commands: the first puts two fingers on the screen (touchStart), the second moves them apart (touchMove), and the third lifts them from the screen (touchEnd).

// The point where the thumb and index finger start the gesture
const pinchStart = { x: 200, y: 200 };

// The point where the thumb ends the gesture
const thumbPinchEnd = { x: 100, y: 100 };

// The point where the index finger ends the gesture
const indexFingerPinchEnd = { x: 300, y: 300 };

const cdpSession = await page.context().newCDPSession(page);
await cdpSession.send("Input.dispatchTouchEvent", {
  type: "touchStart",
  touchPoints: [pinchStart, pinchStart],
});
await cdpSession.send("Input.dispatchTouchEvent", {
  type: "touchMove",
  touchPoints: [thumbPinchEnd, indexFingerPinchEnd],
});
await cdpSession.send("Input.dispatchTouchEvent", {
  type: "touchEnd",
  touchPoints: [],
});

Determining if the page is zoomed in

What has been sort of complicated in the past and required a fair bit of knowledge about browser geometry and things like the difference between the visual and the layout viewport has become rather straightforward with the introduction of the VisualViewport API. It provides a scale property that tells you the scale factor right away. 1 if the page is not zoomed at all, a number between 0 and 1 if it is zoomed out and a number greater than 1 if it is zoomed in.

We can query this value from the browser by using Playwright's evaluate method:

const scaleFactor = await page.evaluate(() => {
  return visualViewport?.scale;
});

We use the optional chaining operator ? because the visualViewport object can be null (in case the document is not fully active) and otherwise a type aware IDE will complain. Because Playwright waits for the page to be active when we use await page.goto(…) we don't need to worry about that. If you use TypeScript you can alternatively use the non-null assertion operator ! instead.

The final test:

import { test, expect } from "@playwright/test";

const pinchToZoomGesture = async (page) => {
  const pinchStart = { x: 200, y: 200 };
  const thumbPinchEnd = { x: 100, y: 100 };
  const indexFingerPinchEnd = { x: 300, y: 300 };

  const cdpSession = await page.context().newCDPSession(page);
  await cdpSession.send("Input.dispatchTouchEvent", {
    type: "touchStart",
    touchPoints: [pinchStart, pinchStart],
  });
  await cdpSession.send("Input.dispatchTouchEvent", {
    type: "touchMove",
    touchPoints: [thumbPinchEnd, indexFingerPinchEnd],
  });
  await cdpSession.send("Input.dispatchTouchEvent", {
    type: "touchEnd",
    touchPoints: [],
  });
};

test("page supports pinch-to-zoom gesture", async ({ page, browserName }) => {
  // We need to skip this test on non-Chromium browsers because the Chrome
  // DevTools Protocol (CDP) that we use to trigger touch events is only
  // available in Chromium browsers.
  test.skip(browserName !== "chromium");

  // Replace `playwright.dev` with the actual page under test.
  await page.goto("https://playwright.dev/");
  await pinchToZoomGesture(page);

  const scaleFactor = await page.evaluate(() => {
    return visualViewport?.scale;
  });

  expect(scaleFactor).toBeGreaterThan(1);
});