@nut-tree/nut-js NPM

nut.js (Native UI Toolkit)

	GitHub Actions
Master
Develop

About

nut.js is a cross-platform native UI automation / testing tool.

It allows for native UI interactions via keyboard and / or mouse, but additionally gives you the possibility to navigate the screen based on image matching.

Sponsoring

nut.js is developed with community in mind.

A huge "Thank you!" goes out to all sponsors who make open source a bit more sustainable!

Demo

Check out this demo video to get a first impression of what nut.js is capable of.

Examples

nut-tree/trailmix contains a set of ready to use examples which demo the usage ot nut.js.

API Docs

nut.js provides public API documentation auto-generated by TypeDoc.

Discussion

In nut-tree/rfc documents regarding larger design / implementation changes in nut.js are up for discussion.

Community

Feel free to join our Discord community

Modules

This list gives an overview on currently implemented and planned functionality. It's work in progress and will undergo constant modification.

Clipboard

Copy text to clipboard
Paste text from clipboard

Keyboard

Support for standard US keyboard layout
Support for multimedia keys

Mouse

Support for mouse movement
Support for mouse scroll
Configurable movement speed
Mouse drag

Window

List all windows
Retrieve active window
Retrieve window title
Retrieve window size and position

Screen

Find an image on screen
Find all image occurrences on screen
Wait for an image to appear on screen
Retrieve RGBA color information on screen
Hooks to trigger actions based on images
Highlighting screen regions

Integration

Jest
Electron

Sample

The following snippet shows a valid nut.js example (on macOS)

"use strict";

const { keyboard, Key, mouse, left, right, up, down, screen } = require("@nut-tree/nut-js");

const square = async () => {
  await mouse.move(right(500));
  await mouse.move(down(500));
  await mouse.move(left(500));
  await mouse.move(up(500));
};

const openSpotlight = async () => {
  await keyboard.pressKey(Key.LeftSuper);
  await keyboard.pressKey(Key.Space);
  await keyboard.releaseKey(Key.Space);
  await keyboard.releaseKey(Key.LeftSuper);
};

(async () => {
    await square();
    await openSpotlight();
    await keyboard.type("calculator");
    await keyboard.type(Key.Return);
})();

Installation

nut.js comes with a pre-built version of OpenCV for your respective target platform. In order to use these pre-compiled bindings, certain runtime conditions have to be met.

Prerequisites

This section lists runtime requirements for nut.js on the respective target platform. nut.js is built and tested against node 10 and later as well as Electron 4 and later, so in order to use nut.js please make sure to use one of these versions.

Windows

In order to install nut.js on Windows, please make sure to have the Microsoft Visual C++ Redistributable installed.

macOS

On macOS, Xcode command line tools are required. You can install them by running

xcode-select --install

Attention:

In case you're experiencing problems like your mouse not moving or your keyboard not typing, please make sure to give the process you're executing your tests with accessibility permissions.

If an application wants to use accessibility features, a permission pop-up should be shown. If not, you could try to manually add the application you're running the script from.

Settings -> Security & Privacy -> Privacy -> Accessibility -> Add...

Linux

Depending on your distribution, Linux setups may differ.

In general, nut.js requires

libXtst

Installation on *buntu distributions:

sudo apt-get install libxtst-dev

Setups on other distributions might differ.

Install `nut.js`

Running

npm i @nut-tree/nut-js

yarn add @nut-tree/nut-js

will install nut.js and its required dependencies.

Snapshot releases

nut.js also provides snapshot releases which allows to test upcoming features.