Package: ragger
RaggerThis 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 usesSpeculosClientto 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 theSpeculosClientis superior with an emulator),LedgerCommBackendandLedgewWalletbackend, which use respectively theLedgerCommlibraryor theLedgerWalletlibraryto discuss
with a physical device. In these cases, the physical device must be started,
with the expected applicationinstalledandrunning, and connected to the
computer through USB.More complete documentation can be foundhere.InstallationPython packageRagger is available onhttps://pypi.org. To install it fully, just run:pip install ragger[all_backends]You can also install it from sources. At the root of thegitrepository, run:pip install '.[all_backends]'The extra index is important, as it brings the latest version of Speculos.ExtrasSometimes 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 inragger. Installingraggerwithout extra meansit
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 dependenciesIf the Speculos extra is installed (to use theSpeculosBackend), system dependencies are needed.Check the docfor these.FeaturesThesrc/ragger/backend/interface.pyfile 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.Thesrc/ragger/navigator/navigator.pyfile 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 asnavigate_until_textbut compare screenshots taken at
each step with "golden images".ExamplesWithpytestThe backends can be easily integrated in apytesttest suite with the following files:Aconftest.pywhich can be heavily based onthis template.Ausage.mdwhich can be heavily based onthis template.Tests files which would looks like:#---------- some_tests.py ----------TESTS_ROOT_DIR=Path(__file__).parentdeftest_something(backend,firmware):rapdu:RAPDU=backend.exchange(<whatever>)assertrapdu.status==0x9000deftest_with_user_action_and_screenshot_comparison(backend,firmware,navigator,test_name):withbackend.exchange_async(<whatever>)iffirmware.device=="nanos":instructions=[NavIns(NavInsID.RIGHT_CLICK),NavIns(NavInsID.RIGHT_CLICK),NavIns(NavInsID.BOTH_CLICK),]eliffirmware.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_responseassertrapdu.status==0x9000assertverify(rapdu.data)Thebackendfixture used to discuss with the instantiated backend is documentedhere.Thenavigatorfixture used to navigate with the instantiated backend is documentedhere.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 backendThe tests of this repository are basically the same as this example, except
the tests run on the three current firmwares (NanoS, NanoX and NanoS+).DocumentationThe complete documentation can be foundhere.
If you want to generate it locally, you'll need thedocdependencies to
generate the documentation:pipinstall.[doc]You will also need thegraphvizpackage in order to generate some dependency
diagrams:apt-getinstallgraphvizOnce done, you can generate the documentation:(cddoc&&makegen_resources&&makehtml)Repository deployment, versions & tagsVersions and changes are documented into theCHANGELOG.mdfile.Merging on master or pushing a tag on the GitHub repository triggers a deployment. Python packages
are deployed intopypi.org.if triggered via a merge, the package will be a "pre-release", with a version matching<M>.<m>.<p+1>-dev<N>with:Mthe major number of the latest version,mthe minor number of the latest version,pthe patch number of the latest version,Nthe 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 theCHANGELOG.mdfile. If not, the CI will fail.