Package: needly
Needly (Version 2.5)Needlyis an openQA needle editor written in Python. It creates or modifies needles for the openQA tests.The openQA needle consists of two files, apngscreenshot and thejsondefinition file. The definition file provides various information to the openQA engine, including thetags,types, andareasto 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 supportspngscreenshots. To open the needle, you can either load thatpngfile or thejsondefinition file. Both ways will open the needle in the editor.Requirements to run the applicationPython 3Tkinterthe Pillow libraryRecommended requirements to have better user experienceLibvirt (to run VMs that can be controllable withvirsh)ImageMagick (to work with screenshots)Using the editorStarting the editorCurrently, you can run the editor from the console.Running./needly.pystarts the editor without any image loaded. You can open an image using theCtrl-Ocombination. Or you can load the entire directory into a front usingCtrl-D.Running./needly.py needle.pngstarts the editor with that particular image loaded which can be useful to edit an existing needle quickly.Reading the imagesEditing multiple files in a directoryYou can open an entire directory and navigate through images one after another and edit their needles. To use this approach:ClickFile > Open directoryor useCtrl-D.Use the dialogue to select a directory from which the screenshots will be loaded.Circle over the images usingLoad next(Ctrl-N) orLoad previous(Ctrl-P) from theFilemenu.Editing a single fileYou can also open a particular file and edit its needle. To use this approach:Click theFile > Open fileor use theCtrl-Okey.Use the dialogue to locate the file you want to edit.Working with needlesLoading the needle informationIn 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 usingNeedle > Load(Ctrl-L).You can reload the needle again anytime and restore all the original information until you save the definition file.Reading the needle information.When the needle is loaded, you can see all needle information in the right part of the program window.
Among others:the name of the active imageneedle propertiesneedle tagsactive area coordinatesnumber of areas in the needlethe content of the needle json fileUpdating the needle informationYou can manually update the following fields:the coordinatesthe propertiesthe tagsthe area typeRedrawing the areaThe needle area can be updated using several techniqes:You can use the mouse to draw a new needle area.You can manually update the coordinates in the coordinate fields on the right.You can use keys to change the size of the area.When using the keyboard:UsingLeft,Right,Up, andDownarrows changes the coordinates of the lower right corner in steps of 1 px each.Using theShiftkey combined with arrows changes the coordinates of the upper left corner in steps of 1 px each.Holding theCtrlkey when pressing arrows increases one step to 5 pxs.Holding theAltkey when pressing arrows increases one step to 25 pxs.Note: When you have updated the area, you have to clickArea > Modify area(Ctrl-M)
to update the actual needle.Saving a needleIf you want to store the needle information permanently, you have to save it. To do so:Click on theNeedle > Save, or use theCtrl-Sshortcut to save the needle.When saving, the editor overwrites the definiton file and the original needle cannot be restored.Creating a new needle from scratchWhen 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:Open the existing image.Fill in all needed info:needle tagneedle areaneedle type (match, ocr, or exclude)needle properties (not compulsory)Draw a rectangle around the area or use any of the approaches fromRedrawing the areasection.ClickArea > Add areabutton or press theCtrl-Ato add the area to the needle.If you wish to add another area (the needle can have more areas), just draw a new area and repeatStep 3to add it to the needle.Click theNeedle > Save(Ctrl-S) to save the needle permanently.Working with areasAdd an area to the needleIn order to have an area on the needle, you have to add it to it:Press theArea > Add areabutton (Ctrl-A) to add the area to the needle.Repeat for another area.You can see the number of areas in the field in the lower right part of the window.Removing an active areaWhen your area is still active (that means that you have not added a new area yet), it can be removed
from the needle again:Click on theArea > Remove areabutton (Ctrl-R) to remove it from the needle.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 usingArea > Go to next area(Ctrl-G).Showing next areaWhen 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:Click on theArea > Go to next area(Ctrl-G).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:Save the needle (Ctrl-S).Load the needle (Ctrl-L).Now, the editor makes the very first area active and you can modify it (Ctrl-M).Move to the next area (Ctrl-G) to modify it.Repeat until you have modified required areas.Save the needle (Ctrl-S).Taking screenshots from a VMIf 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:Click on thevMachine > Connect a VMto open a dialogue to connect to a running VM. Now, the application will be able to take screenshots from that virtual machine. When you need to connect to a different VM, repeate this step.When the application is connected to a VM (indicated in the lower right part), you can take a screenshot any time usingvMachine > Take screenshot(Ctrl-T). The screenshot will be saved asscreenshot.pngand displayed in the application.In order to protect the screenshot from being overwritten with another press of the key shortcut, type in the tag name, and use theFile > Set name from tag(Ctrl-X) to rename thepngfile.Note:To have this functionality, you have to havelibvirt,virsh, andImageMagickinstalled.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:Invirt-manageradd a new, user related, connection to libvirt. ClickFile > Add connectionand then chooseQEMU/KVM user relationas the hypervisor. Now, any VM created under this connection will be available to be used in the application. (recommended)Fix the rights of the user to be able to manipulate the system VMs viavirsh(out of scope of this document)Run the editor withsudo(not-recommended).Reporting a problemIf you experience a problem, open an issue. Or help with the development. Yup, it is opensource!