Needly is an openQA needle editor written in Python. It creates or modifies needles for the openQA tests.
The openQA needle consists of two files, a png screenshot and the json definition file. The definition file provides various information to the openQA engine, including the tags, types, and areas to look for. Users can use this application to edit (or create) all the necessary information quickly and draw the areas using the built-in WYSIWYG editor. When the needle is saved, it is fully compatible with the openQA engine.
The advantage of the editor is that it does not need openQA to be installed on the system. The needle files are all you need to work with them.
The editor only supports png screenshots. To open the needle, you can either load that png file or the json definition file. Both ways will open the needle in the editor.
virsh
)Currently, you can run the editor from the console.
./needly.py
starts the editor without any image loaded. You can open an image using the Ctrl-O combination. Or you can load the entire directory into a front using Ctrl-D. ./needly.py needle.png
starts the editor with that particular image loaded which can be useful to edit an existing needle quickly.You can open an entire directory and navigate through images one after another and edit their needles. To use this approach:
You can also open a particular file and edit its needle. To use this approach:
In the current version, when you have loaded a picture, the definition file is not loaded automatically so that you can recreate the needle from scratch which is useful when reneedling test suites where bigger changes are to expected. However, if you would rather want to edit the current definiton file, you need to load it using Needle > Load (Ctrl-L).
You can reload the needle again anytime and restore all the original information until you save the definition file.
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 Area > Modify area (Ctrl-M) to update the actual needle.
If you want to store the needle information permanently, you have to save it. To do so:
When saving, the editor overwrites the definiton file and the original needle cannot be restored.
When you create a needle can do it for an existing image or you can take a screenshot from a connected virtual machine (see later). To create a new needle for an existing image:
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.
If, however, you need to remove an area added earlier but you do not want to remove the later areas, you need to save the needle first, then reload it, which puts you to the earliest area and makes it active. Then you can move to later areas using Area > Go to next area (Ctrl-G).
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 do not have any screenshot to be used as a needle, you can create one by taking a screenshot from an existing and running virtual machine:
screenshot.png
and displayed in the application.Note: To have this functionality, you have to have libvirt
, virsh
, and ImageMagick
installed.
Warning: If your virtual machine does not run in user space, it might not be visible by the application. There are several ways to fix it:
virt-manager
add a new, user related, connection to libvirt. Click File > Add connection and then choose QEMU/KVM user relation as the hypervisor. Now, any VM created under this connection will be available to be used in the application. (recommended) virsh
(out of scope of this document)sudo
(not-recommended).If you experience a problem, open an issue. Or help with the development. Yup, it is opensource!