libfprint/tests/README.md

`umockdev` Tests
================
`umockdev` tests use fingerprint devices mocked by [`umockdev`
toolchain][umockdev].

This document describes how to create a 'capture' test: a test that
captures a picture of a fingerprint from the device (mocked by
`umockdev`) and compares it with the standard one.

Other kinds of `umockdev` tests can be created in a similar manner. For
match-on-chip devices you would instead create a test specific `custom.py`
script, capture it and store the capture to `custom.pcapng`.

'Capture' Test Creation
-----------------------
A new 'capture' test is created by means of `capture.py` script:

1. Create (if needed) a directory for the driver under `tests`
   directory:

   `mkdir DRIVER`

   Note that the name must be the exact name of the libfprint driver,
   or the exact name of the driver followed by a `-` and a unique identifier
   of your choosing.

2. Prepare your execution environment.

   In the next step a working and up to date libfprint is needed. This can be
   achieved by installing it into your system. Alternatively, you can set
   the following environment variables to run a local build:
   - `export LD_PRELOAD=<meson-build-dir>/libfprint/libfprint-2.so`
   - `export GI_TYPELIB_PATH=<meson-build-dir>/libfprint`

   Also, sometimes the driver must be adapted to the emulated environment
   (mainly if it uses random numbers, see `synaptics.c` for an example).
   Set the following environment variable to enable this adaptation:
   - `export FP_DEVICE_EMULATION=1`

   Run the next steps in the same terminal.

3. Find the real USB fingerprint device with `lsusb`, e.g.:

   `Bus 001 Device 005: ID 138a:0090 Validity Sensors, Inc. VFS7500 Touch Fingerprint Sensor`

   The following USB device is used in the example above:
   `/dev/bus/usb/001/005`.

   For the following commands, it is assumed that the user that's
   running the commands has full access to the device node, whether
   by running the commands as `root`, or changing the permissions for
   that device node.

4. Record information about this device:

   `umockdev-record /dev/bus/usb/001/005 > DRIVER/device`

5. Record interaction of `capture.py` (or other test) with the device. To do
   so, start wireshark and record `usbmonX` (where X is the bus number). Then
   run the test script:

   `python3 ./capture.py DRIVER/capture.png`

   Save the wireshark recording as `capture.pcapng`. The command will create
   `capture.png`.

6. Add driver's name to `drivers_tests` in the `meson.build`.
7. Check whether everything works as expected.

**Note.** To avoid submitting a real fingerprint, the side of finger,
arm, or anything else producing an image with the device can be used.


Possible Issues
---------------

Other changes may be needed to get everything working. For example the
`elan` driver relies on a timeout that is not reported correctly. In
this case the driver works around it by interpreting the protocol
error differently in the virtual environment (by means of
`FP_DEVICE_EMULATION` environment variable).


[umockdev]: https://github.com/martinpitt/umockdev