nut.js Jest integration

nut.js provides custom matchers for Jest, which allows to write UI tests using well known syntax.

Setup
toBeAt
toBeIn
toShow

Setup

In order to use our custom matchers we need to extend Jest's expect

const {jestMatchers} = require("@mintplex-labs/nut-js");

expect.extend(jestMatchers);

`toBeAt`

toBeAt is a matcher which verifies mouse cursor position.

It receives a Point which specifies the expected mouse cursor position on screen.

const {jestMatchers, mouse, Point} = require("@mintplex-labs/nut-js");

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that cursor is at a certain position", async () => {
        // GIVEN
        const targetPoint = new Point(10, 10);

        // WHEN
        await mouse.setPosition(targetPoint);

        // THEN
        await expect(mouse).toBeAt(targetPoint);
    });
});

It also supports negation as known from other matchers:

const {jestMatchers, mouse, Point} = require("@mintplex-labs/nut-js");

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that cursor is not at a certain position", async () => {
        // GIVEN
        const targetPoint = new Point(10, 10);
        const wrongPoint = new Point(10, 10);

        // WHEN
        await mouse.setPosition(targetPoint);

        // THEN
        await expect(mouse).not.toBeAt(wrongPoint);
    });
});

`toBeIn`

toBeIn allows us to verify whether our mouse cursor is located within a certain Region or not.

const {jestMatchers, mouse, Point} = require("@mintplex-labs/nut-js");

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that cursor is within a certain region", async () => {
        // GIVEN
        const targetPoint = new Point(10, 10);
        const targetRegion = new Region(5, 5, 10, 10);

        // WHEN
        await mouse.setPosition(targetPoint);

        // THEN
        await expect(mouse).toBeIn(targetRegion);
    });
});

Just like toBeAt, it supports negation:

const {jestMatchers, mouse, Point} = require("@mintplex-labs/nut-js");

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that cursor is not within a certain region", async () => {
        // GIVEN
        const targetPoint = new Point(10, 10);
        const targetRegion = new Region(100, 100, 10, 10);

        // WHEN
        await mouse.setPosition(targetPoint);

        // THEN
        await expect(mouse).not.toBeIn(targetRegion);
    });
});

`toShow`

Sometimes we want to verify that our screen displays a certain image.

toShow receives a filename of an image in our resourceDirectory and checks whether it's visible on our screen or not.

const {jestMatchers, screen} = require("@mintplex-labs/nut-js");

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that the screen shows a certain image", async () => {
        // GIVEN
        screen.config.resourceDirectory = "../../e2e/assets";

        // WHEN

        // THEN
        await expect(screen).toShow("an_image.png");
    });
});

Once again, it is also possible to negate an expectation:

const {jestMatchers, screen} = require("@mintplex-labs/nut-js");

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that the screen shows a certain image", async () => {
        // GIVEN
        screen.config.resourceDirectory = "../../e2e/assets";

        // WHEN

        // THEN
        await expect(screen).not.toShow("different_image.png");
    });
});