Skip to main content

Jest integration

nut.js provides custom matchers for Jest, which allows you to write UI tests using 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 receives a filename of an image in our resourceDirectory and checks whether it's visible on our screen 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
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("@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).not.toShow("different_image.png");
});
});