Skip to main content

An input event recorder and player for automatic testing

Project description

Snitch, an input event recorder and player

Snitch is a Python3 program using the Qt5 framework for GUI and the pyautogui and pynput modules for automation.


A working installation of Python3 with pip package installer.


In order to record and control the mouse on Linux systems, the packages python3-tk and python3-dev are required.

The pyautogui module on Linux relies on the scrot utility to perform screen captures, it must be installed separately. See the note about XWayland at the end of this document.


The installation of the scikit-image module on Windows requires the Microsoft Build Tools 2015 (C++ compiler) to be installed.


The use of Python 3.8 is recommended for the menubar to behave properly.

OCR features

Snitch-CI provides OCR features through the use of the Tesseract OCR software, which must be installed separately. The minimum recommended version is 4.1 (prior versions don't support the use of a custom target character set).

  • On Ubuntu (the official package only provides the 4.0 version, thus the need of adding an external PPA):
    sudo add-apt-repository ppa:alex-p/tesseract-ocr
    sudo apt-get update
    sudo apt-get install tesseract-ocr
  • On Windows download the installer at
  • On macOS, with Homebrew:
    brew install tesseract


Snitch is available on PyPI under the name snitch-ci. You can install it by running the command:

pip install snitch-ci

Once installed, start the program by simply running the commamd snitch.

Building from sources

After having insstalled the prerequisites, use the following commands to respectively:

  • install the required python packages dependencies
  • generate the python code for the Qt ui and rc files
  • start the program
pip install -r requirements.txt
python -m snitch


Preparing a test case

Event recording

Click on the Record button. From now on, all the input events from the mouse and the keyboard are recorded. Similar events may be gouped together, e.g. multiple letters typed consecutively are merged into a single TextEvent. All the recorded events appear in the uper table in the Snitch inteface. The following events are recognized:

  • Mouse move
  • Mouse click
  • Mouse double click
  • Mouse click with secondary button (so called right-click)
  • Mouse drag
  • Any of the above, with keys pressed
  • Text entry
  • Key pressed
  • Shortcuts (simultaneous press of a key and modifiers: Ctrl, Alt, …)

To stop the recording, just click on the stop button. This last click is automatically removed from the list of the recorded events.

Manual event edition

On the right hand side of the recorded events list, the Snitch UI shows the properties (such as click location, which keys are pressed, …) of the currently selected event and buttons to add, remove and reorder events in the list.

Event playback

To start the playback of a recorded sequence, click on the Play button in the upper part of the Snitch UI. The events are played with a default time delay of 0.2s. Each event is selected while played so you can follow the progression of the sequence. You can also stop the playback by pressing Esc.

Note: For technical reasons, keyboard events can't be recorded while events are played back. So the only time the press on the Esc key can be caught is between two events. As a consequence, multiple press on the Esc may be required for the sequence to stop.

Capturing areas of interest

The lower part of the Snitch UI is dedicated to the screenshots management. To record a region of the screen as a reference to compare to the state of the tested application after an automatic playback sequence, click on the Add result button. The screen darkens a bit and the mouse cursor becomes a crosshair. Define the area of interest by drawin a rectangle area around it (click and drag).

On mouse button release, the capture is performend and appears in the list of screenshots. When selecting a screenshot, a preview is displayed on the right hand side of the UI along with its properties (size, position) and buttons to add, remove and reorder the screenshots. Adding a screenshot with the add button is exactly the same as using Add result.


Saving / loading test cases

You can save the recorded sequence of events by clicking on the Save… button or by selecting the File > Save… menu option. The formats available are JSON (the images are Base64 encoded) and Pickle.

Load a previously saved file by selecting the File > Open… menu option.


The following video presents some of the various features for events recording:


This video shows how the the screen captures of the results are taken, and how the differces between the reference image and the test result are displayed.


Running a batch of test cases

Feature under development.


See CI documentation

GitLab integration

See CI documentation

Known issues

Typing speed

While recording keystrokes, typing too fast, especially with key modifiers, can result in skipping the modifier, or assinging it to the next key. Typing slowly can avoid the problem. You can also edit the event manually afterwards and enter the intended text.

Context menus

While using context menus with submenus be sure to click on every submenu title to record a mouse position on the item an prevent the cursor to skip steps on playback.


The most recent versions of gnome-shell are based on XWayland instead of X11 as display server. One of the main features of Wayland is the application separation, i.e. each application is isolated from one another and is not allowed to access graphical properties (window size, position, …) of others. As a consequence, the applications running with the native gnome-shell framework are invisible to Snitch.

Moreover for those versions, even if the actions can be recorded for the native X11 applications, the scrot utility (used by pyautogui to perform screenshots) produces only black pictures. As a workaround, it's possible to install the Gnome native capture utility gnome-screenshot and create a wrapper script acting as scrot. The most basic way to do that is putting the following script in the /usr/bin/scrot file (and granting it execution permissions):

#! /bin/bash
gnome-screenshot -f $@

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

snitch-ci-0.7.2.tar.gz (167.5 kB view hashes)

Uploaded Source

Built Distribution

snitch_ci-0.7.2-py3-none-any.whl (196.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page