ragger 1.23.0

Description:

ragger 1.23.0

Ragger



This library aims at reducing the cost of running code on both Speculos emulator
or on a real device.
It mainly consists on an interface which is implemented by three backends:


an emulator-only backend, SpeculosBackend, which uses
SpeculosClient
to run an app on a Speculos emulator. With this backend, APDU can be send directly,
without having to connect a device, start a docker or anything.


two physical backends (although technically they are agnostic, but the
SpeculosClient is superior with an emulator), LedgerCommBackend and
LedgewWalletbackend, which use respectively the
LedgerComm library or the
LedgerWallet library to discuss
with a physical device. In these cases, the physical device must be started,
with the expected application installed and running, and connected to the
computer through USB.


More complete documentation can be found here.
Installation
Python package
Ragger is available on https://pypi.org. To install it fully, just run:
pip install ragger[all_backends]

You can also install it from sources. At the root of the git repository, run:
pip install '.[all_backends]'

Extras
Sometimes we just need some function embedded in the library, or just one backend. It can be
bothersome (and heavy) to import all dependencies when just one or none are needed.
This is why backends are stored as extra in ragger. Installing ragger without extra means it
comes without any backends.
Extra are straightforward: [speculos], [ledgercomm] and [ledgerwallet]. In the previous
section, [all_backends] was used: it is a shortcut to [speculos,ledgercomm,ledgerwallet].
Speculos dependencies
If the Speculos extra is installed (to use the SpeculosBackend), system dependencies are needed.
Check the doc for these.
Features
The src/ragger/backend/interface.py file describes the methods that can be implemented by the
different backends and that allow to interact with a device (either a real device or emulated):

send: send a formatted APDU.
send_raw: send a raw APDU.
receive: receive a response ADPU.
exchange: send a formatted APDU and wait for a response (synchronous).
exchange_raw: send a raw APDU and wait for a response (synchronous).
exchange_async: send a formatted APDU and give back the control to the caller (asynchronous).
exchange_async_raw: send a raw APDU and give back the control to the caller.
right_click: perform a right click on a device.
left_click: perform a left click on a device.
both_click: perform a click on both buttons (left + right) of a device.
finger_touch: performs a finger touch on the device screen.
compare_screen_with_snapshot: compare the current device screen with the provided snapshot.
pause_ticker: pause the backend time.
resume_ticker: resume the backend time.
send_tick: request the backend to increase time by a single step.

The src/ragger/navigator/navigator.py file describes the methods that can be implemented by the
different device navigators and that allow to interact with an emulated device:

navigate: navigate on the device according to a set of navigation instructions provided.
navigate_and_compare: navigate on the device according to a set of navigation instructions
provided then compare each step screenshot with "golden images".
navigate_until_snap: navigate on the device until a snapshot is found and then validate.
navigate_until_text: navigate on the device until a text string is found on screen and then
validate.
navigate_until_text_and_compare: same as navigate_until_text but compare screenshots taken at
each step with "golden images".

Examples
With pytest
The backends can be easily integrated in a pytest test suite with the following files:

A conftest.py which can be heavily based on this template.
A usage.md which can be heavily based on this template.
Tests files which would looks like:

#---------- some_tests.py ----------

TESTS_ROOT_DIR = Path(__file__).parent


def test_something(backend, firmware):
rapdu: RAPDU = backend.exchange(<whatever>)
assert rapdu.status == 0x9000


def test_with_user_action_and_screenshot_comparison(backend, firmware, navigator, test_name):
with backend.exchange_async(<whatever>)
if firmware.device == "nanos":
instructions = [
NavIns(NavInsID.RIGHT_CLICK),
NavIns(NavInsID.RIGHT_CLICK),
NavIns(NavInsID.BOTH_CLICK),
]
elif firmware.device == "stax":
instructions = [
NavIns(NavInsID.USE_CASE_REVIEW_TAP),
NavIns(NavInsID.USE_CASE_REVIEW_TAP),
NavIns(NavInsID.USE_CASE_REVIEW_CONFIRM),
NavIns(NavInsID.USE_CASE_STATUS_WAIT)
]
else:
instructions = [
NavIns(NavInsID.RIGHT_CLICK),
NavIns(NavInsID.BOTH_CLICK),
]
navigator.navigate_and_compare(TESTS_ROOT_DIR, test_name, instructions)
rapdu: RAPDU = backend.last_async_response
assert rapdu.status == 0x9000
assert verify(rapdu.data)

The backend fixture used to discuss with the instantiated backend is documented
here.
The navigator fixture used to navigate with the instantiated backend is documented
here.
After implementing the tests, the test suite can be easily switched on the different backends:
pytest <tests/path> # by default, will run tests on the Speculos emulator
pytest --backend [speculos|ledgercomm|ledgerwallet] <tests/path> # will run tests on the selected backend

The tests of this repository are basically the same as this example, except
the tests run on the three current firmwares (NanoS, NanoX and NanoS+).
Documentation
The complete documentation can be found here.
If you want to generate it locally, you'll need the doc dependencies to
generate the documentation:
pip install .[doc]

You will also need the graphviz package in order to generate some dependency
diagrams:
apt-get install graphviz

Once done, you can generate the documentation:
(cd doc && make gen_resources && make html)

Repository deployment, versions & tags
Versions and changes are documented into the CHANGELOG.md file.
Merging on master or pushing a tag on the GitHub repository triggers a deployment. Python packages
are deployed into pypi.org.

if triggered via a merge, the package will be a "pre-release", with a version matching
<M>.<m>.<p+1>-dev<N> with:

M the major number of the latest version,
m the minor number of the latest version,
p the patch number of the latest version,
N the number of commits since the latest version.


if triggered via a tag, the package will be a release with the tag as the version.
The version embedded into the tag must also fit with the latest version documented into the
CHANGELOG.md file. If not, the CI will fail.