@nut-tree/nut-js NPM

nut.js (Native UI Toolkit)

About

nut.js is a cross-platform native UI 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.

Sample

The following snippet shows a valid NUT example (on macOS)

"use strict";

const { keyboard, Key, mouse, left, right, up, down } = 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);
};

describe("Basic test", () => {
  it("Should run a simple test", 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.

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

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.

Manual build

As a fallback, nut.js is able to build all required dependencies by itself. To do so, some setup is required on the respective target platform.

Windows

In order to install nut.js on Windows, Windows Build Tools and Python 2 are required. You can either set them up manually, or install them via npm:

npm install --global windows-build-tools

yarn global add windows-build-tools

macOS

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

xcode-select --install

Linux

Depending on your distribution, Linux setups may differ.

In general, nut.js requires

Python 2
g++
make
libXtst
libPng

Installation on *buntu distributions:

sudo apt-get install build-essential python libxtst-dev libpng++-dev

Setups on other distributions might differ.

For reference, please see:

Install `nut.js`

Running

npm i @nut-tree/nut-js

yarn add @nut-tree/nut-js

will install nut.js and its required dependencies.

Examples

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

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 German special characters

Mouse

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

Process

Retrieve the region of a process window

Screen

findOnScreen
waitFor
Hooks to trigger actions based on images

Integration

Jest

native system automation testing keyboard mouse process memory window screen monitor display timer clock clipboard

jimp node-abort-controller @nut-tree/default-clipboard-provider @nut-tree/libnut @nut-tree/provider-interfaces @nut-tree/shared

4.1.1-next.20240410220014

14 days ago

4.2.1-next.20240411081530

14 days ago

4.2.0

14 days ago

4.1.1-next.20240404054657

21 days ago

4.0.2-next.20240403182259

21 days ago

4.1.0

21 days ago

4.0.2-next.20240402001842

23 days ago

4.0.1

27 days ago

4.0.2-next.20240329095553

27 days ago

4.0.1-next.20240327230300

28 days ago

4.0.1-next.20240327224834

28 days ago

4.0.1-next.20240319201406

1 month ago

4.0.1-next.20240318211618

1 month ago

4.0.1-next.20240311221001

1 month ago

4.0.1-next.20240226121016

2 months ago

4.0.1-next.20240225200111

2 months ago

4.0.1-next.20240221122450

2 months ago

4.0.0

2 months ago

4.0.1-next.20240219223956

2 months ago

4.0.1-next.20240219234607

2 months ago

4.0.1-next.20240219000149

2 months ago

4.0.1-next.20240219214207

2 months ago

4.0.1-next.20240218230755

2 months ago

4.0.1-next.20240218225747

2 months ago

4.0.1-next.20240216213539

2 months ago

4.0.1-next.20240216224425

2 months ago

4.0.1-next.20240215202348

2 months ago

4.0.1-next.20240215210745

2 months ago

4.0.1-next.20240215202843

2 months ago

3.1.3-next.20240211202600

2 months ago

3.1.3-next.20240203224720

3 months ago

3.1.3-next.20231214235005

4 months ago

3.1.3-next.20231212192745

4 months ago

3.1.3-next.20230714152353

10 months ago

3.1.3-next.20231009191505

7 months ago

3.1.3-next.20230923080516

7 months ago

3.1.3-next.20230923073549

7 months ago

3.1.3-next.20231017222032

6 months ago

3.1.3-next.20231009120904

7 months ago

3.1.3-next.20231009212119

7 months ago

3.1.3-next.20231009211720

7 months ago

3.1.3-next.20231017104719

6 months ago

3.1.3-next.20231009200031

7 months ago

3.1.3-next.20230714135006

10 months ago

3.1.3-next.20231003103733

7 months ago

3.1.3-next.20230628204014

10 months ago

3.1.2-next.20230606114510

11 months ago

3.1.2-next.20230605200101

11 months ago

3.1.3-next.20230606132723

11 months ago

3.1.2-next.20230605190145

11 months ago

3.1.2

11 months ago

3.1.2-next.20230606114628

11 months ago

3.1.2-next.20230605184002

11 months ago

3.1.2-next.20230310000145

1 year ago

3.0.1-next.20230305223411

1 year ago

3.1.1

1 year ago

3.1.0

1 year ago

3.1.2-next.20230306003533

1 year ago

3.0.1-next.20230305221856

1 year ago

3.0.1-next.20230305211709

1 year ago

3.0.1-next.20230305222714

1 year ago

3.1.1-next.20230305234619

1 year ago

3.1.1-next.20230306001608

1 year ago

3.0.1-next.20230305223010

1 year ago

3.1.1-next.20230306002125

1 year ago

3.1.2-next.20230428170832

12 months ago

3.0.1-next.20230305155424

1 year ago

3.1.2-next.20230425191149

1 year ago

3.1.1-next.20230305225824

1 year ago

3.0.1-next.20230305214515

1 year ago

3.0.1-next.20230217194627

1 year ago

2.3.1-next.20230114023020

1 year ago

2.3.1-next.20221215205853

1 year ago

2.3.1-next.20230117012025

1 year ago

2.3.1-next.20230115095803

1 year ago

2.3.1-next.20230112233519

1 year ago

3.0.1-next.20230117103019

1 year ago

3.0.0

1 year ago

3.0.1-next.20230124085453

1 year ago

2.3.1-next.20230114023421

1 year ago

2.3.1-next.20230114025042

1 year ago

3.0.1-next.20230123111112

1 year ago

2.3.1-next.20230116112600

1 year ago

2.3.1-next.20230109081638

1 year ago

3.0.1-next.20230123072601

1 year ago

2.3.1-next.20221214235749

1 year ago

2.3.1-next.20221215201349

1 year ago

2.3.1-next.20230114132815

1 year ago

2.3.1-next.20230114022603

1 year ago

2.3.1-next.20221107224206

1 year ago

2.3.1-next.20221115224324

1 year ago

2.3.1-next.20221108104612

1 year ago

2.3.1-next.20221016183346

2 years ago

2.3.1-next.20220927235103

2 years ago

2.3.1-next.20221016194821

2 years ago

2.3.1-next.20221026222249

1 year ago

2.3.1-next.20220927221816

2 years ago

2.3.1-next.20221023213237

2 years ago

2.3.1-next.20220930144218

2 years ago

2.3.1-next.20221026223955

1 year ago

2.2.1-next.20220822220048

2 years ago

2.2.1-next.20220831203906

2 years ago

2.1.2-next.20220822193246

2 years ago

2.3.0

2 years ago

2.2.1

2 years ago

2.2.0

2 years ago

2.1.2-next.20220822203339

2 years ago

2.3.1-next.20220922101221

2 years ago

2.2.1-next.20220915205116

2 years ago

2.2.2-next.20220922093930

2 years ago

2.2.2-next.20220915212335

2 years ago

2.1.2-next.20220822194036

2 years ago

2.2.2-next.20220920200626

2 years ago

2.1.2-next.20220805175205

2 years ago

2.1.2-next.20220727212415

2 years ago

2.1.2-next.20220817051351

2 years ago

2.1.2-next.20220819121545

2 years ago

2.1.2-next.20220807055457

2 years ago

2.1.2-next.20220816002503

2 years ago

2.1.2-next.20220731175633

2 years ago

2.1.1-next.20220525192924

2 years ago

2.1.1-next.20220517203340

2 years ago

2.1.1-next.20220520232935

2 years ago

2.0.2-next.20220517090834

2 years ago

2.1.2-next.20220601132833

2 years ago

2.1.1

2 years ago

2.1.0

2 years ago

2.0.2-next.20220506202315

2 years ago

2.1.1-next.20220525204106

2 years ago

2.0.2-next.20220517150834

2 years ago

2.0.2-next.20220510195411

2 years ago

2.0.2-next.20220513214416

2 years ago

2.0.2-next.20220425083536

2 years ago

2.0.2-next.20220324192242

2 years ago

2.0.2-next.20220324193210

2 years ago

2.0.2-next.20220417195739

2 years ago

2.0.2-next.20220429180423

2 years ago

2.0.2-next.20220425084711

2 years ago

2.0.2-next.20220324192152

2 years ago

2.0.2-next.20220417201630

2 years ago

2.0.2-next.20220328204410

2 years ago

2.0.2-next.20220324192425

2 years ago

2.0.2-next.20220324192533

2 years ago

2.0.2-next.20220417180722

2 years ago

2.0.2-next.20220324192259

2 years ago

2.0.2-next.20220417210619

2 years ago

2.0.2-next.20220313123831

2 years ago

2.0.1-next.20220104200732

2 years ago

2.0.1-next.20220121202344

2 years ago

2.0.2-next.20220201210655

2 years ago

2.0.1

2 years ago

2.0.0

2 years ago

2.0.0-next.20211228014825

2 years ago

2.0.2-next.20220121214305

2 years ago

2.0.0-next.20220101132110

2 years ago

2.0.1-next.20220121161914

2 years ago

2.0.1-next.20220121173452

2 years ago

2.0.1-next.20220121204945

2 years ago

2.0.1-next.20220121160301

2 years ago

2.0.2-next.20220203202630

2 years ago

2.0.0-next.20211228024245

2 years ago

2.0.1-next.20220121162834

2 years ago

2.0.0-next.20211231132239

2 years ago

2.0.0-next.20211228025103

2 years ago

2.0.0-next.20211228021022

2 years ago

2.0.1-next.20220111170425

2 years ago

2.0.1-next.20220121202941

2 years ago

2.0.0-next.20211231122242

2 years ago

2.0.1-next.20220113233513

2 years ago

2.0.0-next.20211228025919

2 years ago

2.0.2-next.20220205155656

2 years ago

2.0.1-next.20220117231322

2 years ago

2.0.1-next.20220111164815

2 years ago

2.0.0-next.20220101203143

2 years ago

2.0.1-next.20220112151704

2 years ago

2.0.0-next.20211229220351

2 years ago

2.0.1-next.20220101205324

2 years ago

2.0.1-next.20220104155257

2 years ago

1.7.1-next.20211213213310

2 years ago

1.7.1-next.20211216223713

2 years ago

1.7.1-next.20211124112701

2 years ago

1.7.1-next.20211126230432

2 years ago

1.7.1-next.20211126233033

2 years ago

1.7.1-next.20211214223558

2 years ago

1.7.1-next.20211210233328

2 years ago

1.7.1-next.20211211215422

2 years ago

1.7.1-next.20211116232401

2 years ago

1.7.1-next.20211115155253

2 years ago

1.7.1-next.20211203210108

2 years ago

1.7.1-next.20211209075030

2 years ago

1.7.1-next.20211116233225

2 years ago

1.7.1-next.20211127001917

2 years ago

1.7.1-next.20211126212257

2 years ago

2.0.0-RC1

2 years ago

1.7.1-next.20211126152815

2 years ago

1.7.1-next.20211109220301

2 years ago

1.7.1-next.20211207232526

2 years ago

1.7.1-next.20211214222837

2 years ago

2.0.0-next.20211217004227

2 years ago

1.7.1-next.20211201082202

2 years ago

1.7.1-next.20211028184450

2 years ago

1.7.1-next.20211105102142

2 years ago

1.7.1-next.20211104190436

2 years ago

1.7.1-next.20211106205459

2 years ago

1.7.1-next.20211103003423

2 years ago

1.7.1-next.20211027215834

2 years ago

1.7.1-next.20211025212155

2 years ago

1.7.1-next.20211026201327

2 years ago

1.7.1-next.20211025225653

2 years ago

1.7.1-next.20211021190727

3 years ago

1.7.1-next.20211010221755

3 years ago

1.7.1-next.20211011183502

3 years ago

1.7.1-next.20210927204322

3 years ago

1.7.1-next.20210927200257

3 years ago

1.7.1-next.20210926195602

3 years ago

1.7.1-next.20210918203233

3 years ago

1.7.1-next.20210918151806

3 years ago

1.7.1-next.20210910064537

3 years ago

1.7.1-next.20210909112351

3 years ago

1.7.1-next.20210905191441

3 years ago

1.7.1-next.20210905200022

3 years ago

1.7.1-next.20210905191653

3 years ago

1.7.1-next.20210905212807

3 years ago

1.7.1-next.20210905210637

3 years ago

1.7.1-next.20210905183929

3 years ago

1.7.1-next.20210830205442

3 years ago

1.7.1-next.20210828213645

3 years ago

1.7.1-next.20210818083308

3 years ago

1.7.1-next.20210818083032

3 years ago

1.7.1-next.20210818083441

3 years ago

1.7.1-next.20210813225557

3 years ago

1.7.1-next.20210813223043

3 years ago

1.7.1-next.20210811201857

3 years ago

1.6.1-next.20210714213509

3 years ago

1.7.1-next.20210715073601

3 years ago

1.7.0

3 years ago

1.6.1-next.20210714212120

3 years ago

1.6.1-next.20210713203039

3 years ago

1.6.1-next.20210713201944

3 years ago

1.6.1-next.20210625094914

3 years ago

1.6.1-next.20210601212135

3 years ago

1.6.1-next.20210603163242

3 years ago

1.6.1-next.20210408180637

3 years ago

1.6.1-next.20210408195718

3 years ago

1.6.1-next.20210405212542

3 years ago

1.6.1-next.20210330191717

3 years ago

1.6.0

3 years ago

1.6.1-next.20210301085834

3 years ago

1.5.1-next.20210218071742

3 years ago

1.5.1-next.20210205082250

3 years ago

1.5.1-next.20210131151227

3 years ago

1.5.1-next.20210124221315

3 years ago

1.5.1-next.20210124220954

3 years ago

1.5.1-next.20210124220948

3 years ago

1.5.1-next.20210113211008

3 years ago

1.5.1-next.20210107114029

3 years ago

1.5.1-next.20210107115106

3 years ago

1.5.1-next.20201203193311

3 years ago

1.5.1-next.20201110140748

3 years ago

1.5.1-next.20200914115152

4 years ago

1.5.1-next.20200903052855

4 years ago

1.5.1-next.20200828135302

4 years ago

1.5.1-next.20200816103929

4 years ago

1.5.0

4 years ago

1.4.3-next.20200814113940

4 years ago

1.4.3-next.20200813090951

4 years ago

1.4.3-next.20200723090742

4 years ago

1.4.2

4 years ago

1.4.2-next.20200716200528

4 years ago

1.4.2-next.20200712215001

4 years ago

1.4.2-next.20200622220440

4 years ago

1.4.2-next.20200519152015

4 years ago

1.4.2-next.20200518171457

4 years ago

1.4.2-next.20200514215400

4 years ago

1.4.2-next.20200514202444

4 years ago

1.4.2-next.20200513232519

4 years ago

1.4.2-next.20200513211517

4 years ago

1.4.2-next.20200512230939

4 years ago

1.4.1

4 years ago

1.4.2-next.20200511123609

4 years ago

1.4.1-next.20200507012528

4 years ago

1.4.1-next.20200505053330

4 years ago

1.4.0

4 years ago

1.3.3-next.20200504215723

4 years ago

1.3.3-next.20200504211803

4 years ago

1.3.3-next.20200501095523

4 years ago

1.3.3-next.20200429215927

4 years ago

1.3.3-next.20200428225252

4 years ago

1.3.3-next.20200428164027

4 years ago

1.3.3-next.20200427205151

4 years ago

1.3.3-next.20200319174151

4 years ago

1.3.3-next.20200317080331

4 years ago

1.3.3-next.20200316065659

4 years ago

4 years ago

4 years ago

4 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

5 years ago

nut.js (Native UI Toolkit)

About

Sample

Installation

Prerequisites

Windows

macOS

Linux

Manual build

Windows

macOS

Linux

Install nut.js

Examples

Modules

Clipboard

Keyboard

Mouse

Process

Screen

Integration

Install `nut.js`