Jest integration

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

Setup

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

const {jestMatchers} = require("@nut-tree/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("@nut-tree/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("@nut-tree/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("@nut-tree/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("@nut-tree/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 takes any search query supported by find and checks whether it's visible on our screen or not.

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

expect.extend(jestMatchers);

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

        // WHEN

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

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

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

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that the API-screen does not show a piece of text", async () => {
        // GIVEN

        // WHEN

        // THEN
        await expect(screen).not.toShow(textLine(/^some text .*$/));
    });
});

toWaitFor

toShow expects things to be in place right here, right now. But since graphical user interfaces are a very dynamic environment to test, such an expectation does not always work out. Sometimes you want to give your application additional time to finish e.g. an animation. To comfort that, the toWaitFor matcher is based on screen.waitFor, which allows you to make your test expectations more flexible without having to define static timeouts.

toWaitFor takes any search query supported by find, an optional timeoutMs after which the expectation will fail, as well as an optional updateInterval to specify the interval in ms in which the search query should be executed.

The default values for timeoutMs and updateInterval are 5000 and 500, respectively.

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

expect.extend(jestMatchers);

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

        // WHEN

        // THEN
        await expect(screen).toWaitFor(imageResource("an_image.png"), 7000, 300);
    });
});

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

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

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that the API-screen does not show a piece of text", async () => {
        // GIVEN

        // WHEN

        // THEN
        await expect(screen).not.toWaitFor(textLine(/^some text .*$/));
    });
});

toHaveColor

Sometimes we want to verify that a certain Point on our screen has a certain color.

toHaveColor receives a Point and checks whether it has the expected RGBA color value or not.

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

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that the API-screen shows a certain image", async () => {
        // GIVEN
        const targetPoint = new Point(10, 10);
        const wantedColor = new RGBA(255, 0, 0, 255);

        // WHEN

        // THEN
        await expect(targetPoint).toHaveColor(wantedColor);
    });
});

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

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

expect.extend(jestMatchers);

describe("Basic test with custom Jest matchers", () => {
    it("should verify that the API-screen shows a certain image", async () => {
        // GIVEN
        const targetPoint = new Point(10, 10);
        const unwantedColor = new RGBA(255, 0, 255, 255);

        // WHEN

        // THEN
        await expect(targetPoint).not.toHaveColor(unwantedColor);
    });
});