API and Data Types
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
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");
});
});