3.0.0

Breaking changes introduced with nut.js version 3.0.0

OptionalSearchParameters

With the improvements to screen.find and its siblings, OptionalSearchParameters received an update as well. It no longer carries a searchMultipleScales property, but instead now holds a generic providerData property. The searchMultipleScales property stemmed from a time when screen.find was limited to image search, but with the introduction of different find providers, this property did not make sense anymore.

Instead, search provider specific configuration like searchMultipleScales can now be passed via the providerData property.

Required changes from a users perspective

Instead of setting searchMultipleScales on OptionalSearchParameters, you now have to pass it via providerData:

await screen.find(imageResource("my-image.png"), {
    providerData: {
        searchMultipleScales: true
    },
});

Required changes from a developer perspective

Developers of custom nut.js providers have to adjust their packages such that they'll correctly handle providerData. To ensure compatibility with nut.js 3.0.0, you could add a peerDependency to @nut-tree/nut-js version 3.0.0 or higher in your providers package.json.

{
  ...
  "peerDependencies": {
    "@nut-tree/nut-js": ">=3.0.0"
  },
  ...
}

It's also considered a good practice to export an interface that describes the structure of providerData for a given provider.

Image

The Image class has been adjusted to also carry information about an images bits per pixel and byte width.

If you are loading images using the existing loader functions like loadImage or imageResource, you don't have to adjust anything.

In case you're manually creating Image instances, please make sure to also provide the newly added properties bitsPerPixel and byteWidth.

Clipboard

The previous naming scheme of clipboard.copy(...) and clipboard.paste(...) repeatedly caused people to think it would literally copy and paste content to the environment, instead of just setting/getting the current clipboard content.

To avoid further confusion, the copy and paste methods have been renamed to setContent and getContent respectively.

// Pre 3.0.0
await clipboard.copy("Hello World");

// 3.0.0
await clipboard.setContent("Hello World");

// Pre 3.0.0
const clipboardContent = await clipboard.paste();

// 3.0.0
const clipboardContent = await clipboard.getContent();