Running an existing SWAP test
This page provides all the essential setup details to help you get started with enabling the SWAP feature in your application.
The Boilerplate application will be used as an example.
Understanding the Exchange test framework
Please look at the sequence diagram. You will see that, in order to perform a SWAP, several communication and authentication steps between Ledger Live (here mocked by Ragger) and the device are required.
These steps are outside the scope of testing your application. We provide the Exchange client, hosted in the Exchange application repository, to perform them automatically.
Looking again at the sequence diagram, the only Python code you will have to write is the Sign transaction request once your application has been started by Exchange.
The Swap functional tests setup
The swap test suite validates the application when it is used by the Exchange application through the os_lib_call mechanism to perform the swap feature.
This mode uses dedicated launch code and requires a different Speculos setup.
These tests are written using:
- pytest — Python testing framework
- Ragger — Ledger's open-source testing library for simulating device interactions
- The python module ledger_app_clients.exchange - The helper module to easily emulate the SWAP context.
Directory structure brief overview:
swap/
|── cal_helper.py # A fake CAL configuration for the BOL currency
├── conftest.py # Pytest fixtures and device setup
├── test_boilerplate.py # Functional test cases
├── helper_tool_build_dependencies.py # A helper script to pull Exchange and Ethereum applications (needed for Speculos to emulate a swap)
├── helper_tool_clone_dependencies.py # A helper script to compile pulled Exchange and Ethereum applications (run after helper_tool_build_dependencies.py INSIDE the Docker)
├── snapshots/ # Ragger UI snapshots
├── snapshots-tmp/ # Temporary snapshot diffs (not tracked in git)
├── requirements.txt # Python dependencies
Compile your application
Build your application in the Ledger docker environment.
Compile the Exchange and Ethereum applications
First, install helper python dependencies in your native (host) environment
Then, execute the clone script in your native (host) environment
Then, execute the build script in the Ledger docker environment. You can use the following command when located in the tests/swap directory.
docker run --user "$(id -u)":"$(id -g)" --rm -ti -v "$(realpath .):/app" "ghcr.io/ledgerhq/ledger-app-builder/ledger-app-builder:latest" python3 helper_tool_build_dependencies.py
Running a first Exchange test
If you are on Linux or WSL, you can run the tests in your native (host) environment.
If you are on MAC you need to run the tests in the Ledger docker environment.
Install python dependencies
Install python dependencies
Run a simple test
To see all available tests:
To list only SWAP tests for Stax:
To run a specific test for Stax:
Running a single test will be useful later for test driven development, don't hesitate to come back to this command and adapt it.
Next steps
Now that you know how to set up and run the swap tests, you will be able to add tests for your own application and run them as you develop the SWAP feature.