The Needle Editor creates and modifies needles for the OpenQA tests. The advantage of the editor is that it does not need OpenQA to be installed on the system. Only screenshots upon which the needles will be created are needed. With the editor, the needles can be made in advance and then only tested finally in the OpenQA instance.
The editor only supports png screenshots, however if a json needle description already exists for a particular image, you can load that instead and a correct image will load.
The editor is started from the console. You can start it in two ways:
You can open a directory to navigate through images one after another and edit their needles. To use this approach:
Note: The editor reports number of images in the directory, when you have selected it.
You can also open a particular file and edit its needle. To use this approach:
You can navigate through the images back and forth in the loop. To navigate through the image loop:
If you have a VM running, you can load screenshots from that to get the
png image for the needle.:
Note: To have this functionality, you have to have
ImageMagick installed. If your installation requires
sudo to work with VMs, you have to run the editor with
When you have navigated to the image you want to create a needle for, make sure you try loading an existing needle. Not doing so, you could accidentally overwrite it. To load a needle:
Note: You can load the needle again anytime and restore all the original information until the needle has been saved.
When the needle is loaded, you can see all needle information in the right part of the program window. Among others:
You can manually update the following fields:
The needle area can be updated using several techniqes:
When using the keyboard:
Note: When you have updated the area, you have to click Modify active area button for them to take effect on the actual needle.
Note: When you have updated the needle fields, the keyboard shortcuts will not work properly because of lost focus (known issue). Click into the picture field to get the shortcuts to work again.
If you want to store the needle information permanently, you have to save it. To do so:
When saving, the editor creates a json file (the name of the file matches the name of the active image) and stores all needle information in that file. Next time, when you load the needle, the needle information will be restored.
To create a new needle, you must provide the required needle information:
In order to have an area on the needle, you have to add it to it:
You can see the number of areas in the field in the lower right part of the window.
When your area is still active (that means that you have not added a new area yet), it can be removed from the needle again:
When removing the area from the needle, the active area falls back to the previous area (which becomes active) and the rectangle will show its current position. You can repeat the action, until all areas are deleted.
When the needle has more than one area (you can see the number in the lower right part of the program window), only the first area is shown. To see the next area:
This will show the next area in the needle and makes it active. You can update the area or remove it.
Warning: In this version, you cannot navigate in areas. You only can move to the next ones. However, if you remove the area from the needle, the editor will fall back to the previous area and make it active again so you can update or remove it.
If you need to change the first area without removing the next area, use the following workaround:
If you experience a problem, open an issue. Or help with the development. Yup, it is opensource!