ragger 1.21.1__tar.gz → 1.41.0__tar.gz

ragger-1.41.0/.github/workflows/build_and_tests.yml

@@ -0,0 +1,133 @@
+name: Build, test and deploy Ragger
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - '*'
+    branches:
+      - master
+      - develop
+  pull_request:
+    branches:
+      - master
+      - develop
+
+# Cancel previous runs on this reference
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+
+  build_boilerplate_application:
+    name: Build boilerplate application using the reusable workflow
+    uses: LedgerHQ/ledger-app-workflows/.github/workflows/reusable_build.yml@v1
+    with:
+      app_repository: LedgerHQ/app-boilerplate
+      app_branch_name: master
+      upload_app_binaries_artifact: boilerplate_binaries
+
+  build_boilerplate_application_nanos:
+    name: Build boilerplate application for Nanos S using the reusable workflow
+    uses: LedgerHQ/ledger-app-workflows/.github/workflows/reusable_build.yml@v1
+    with:
+      app_repository: LedgerHQ/app-boilerplate
+      app_branch_name: nanos_baseline
+      upload_app_binaries_artifact: boilerplate_binaries_nanos
+
+  prepare_matrix:
+    name: Prepare matrix from TOML file
+    runs-on: ubuntu-latest
+    outputs:
+      devices: ${{ steps.get_devices.outputs.devices }}
+    env:
+      APP_MANIFEST: "ledger_app.toml"
+
+    steps:
+      - name: Clone
+        uses: actions/checkout@v4
+      - name: Install ledgered
+        run: pip install ledgered
+      - name: Get devices from TOML
+        id: get_devices
+        run: |
+          # get device list as a single line json formatted value
+          compatible_devices="$(ledger-manifest --output-devices "${APP_MANIFEST}" -j | jq -rc '.devices')"
+
+          echo "devices=${compatible_devices}" | sed 's/+/p/' >> "${GITHUB_OUTPUT}"
+
+  build_install_test:
+    name: Install and test the library
+    needs: [prepare_matrix, build_boilerplate_application, build_boilerplate_application_nanos]
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python_version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        device: ${{ fromJson(needs.prepare_matrix.outputs.devices) }}
+
+    steps:
+    - name: Clone
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Setup Python version
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python_version }}
+
+    - name: Speculos dependencies
+      run: sudo apt-get update && sudo apt-get install -y qemu-user-static tesseract-ocr libtesseract-dev python3-pyqt6
+
+    - name: Build & install
+      run: |
+        pip install -U .[tests,all_backends]
+        pip install -U "click>=8"
+
+    - name: Install speculos for Nanos
+      if: ${{ matrix.device == 'nanos' }}
+      run: |
+        pip install -U speculos==v0.25.5
+
+    - name: Download app binaries
+      if: ${{ matrix.device != 'nanos' }}
+      uses: actions/download-artifact@v4
+      with:
+        name: boilerplate_binaries
+        path: ./build/
+
+    - name: Download app binaries for Nano S
+      if: ${{ matrix.device == 'nanos' }}
+      uses: actions/download-artifact@v4
+      with:
+        name: boilerplate_binaries_nanos
+        path: ./build/
+
+    - name: Check the downloaded files
+      run: tree .
+
+    - name: Run unit tests and generate coverage
+      run: pytest -v --tb=short tests/unit --cov ragger --cov-report xml
+
+    - name: Run functional tests and generate coverage
+      run: pytest -v --tb=short tests/functional --cov ragger --cov-report xml --cov-append --device ${{ matrix.device }}
+
+    - name: Upload to codecov.io
+      uses: codecov/codecov-action@v5
+      env:
+        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+      with:
+        name: codecov-ragger
+        flags: ${{ matrix.device }}-py${{ matrix.python_version }}
+
+  package_and_deploy:
+    name: Build and deploy the Ragger Python package
+    needs: [build_install_test]
+    uses: LedgerHQ/ledger-app-workflows/.github/workflows/reusable_pypi_deployment.yml@v1
+    with:
+      package_name: ragger
+      publish: ${{ startsWith(github.ref, 'refs/tags/') }}
+    secrets:
+      pypi_token: ${{ secrets.PYPI_PUBLIC_API_TOKEN }}

{ragger-1.21.1 → ragger-1.41.0}/.github/workflows/codeql-analysis.yml

@@ -12,6 +12,11 @@ on:
       - develop
   schedule:
     - cron: '35 0 * * 5'
+# Cancel previous runs on this reference
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 
 jobs:
   analyze:
@@ -22,16 +27,13 @@ jobs:
       contents: read
       security-events: write
 
-    strategy:
-      fail-fast: false
-
     steps:
     - name: Checkout repository
       uses: actions/checkout@v4
 
     # Initializes the CodeQL tools for scanning.
     - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
+      uses: github/codeql-action/init@v3
       with:
         languages: "python"
         # If you wish to specify custom queries, you can do so here or in a config file.
@@ -40,10 +42,10 @@ jobs:
         # queries: ./path/to/local/query, your-org/your-repo/queries@main
         queries: +security-and-quality
 
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
     # If this step fails, then you should remove it and run the build manually (see below)
     - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
+      uses: github/codeql-action/autobuild@v3
 
     # ℹ️ Command-line programs to run using the OS shell.
     # 📚 https://git.io/JvXDl
@@ -57,6 +59,6 @@ jobs:
     #   make release
 
     - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
+      uses: github/codeql-action/analyze@v3
       with:
         config-file: .codeql-config.yaml

{ragger-1.21.1 → ragger-1.41.0}/.github/workflows/documentation.yml

@@ -11,6 +11,11 @@ on:
     branches:
       - develop
       - master
+# Cancel previous runs on this reference
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 
 jobs:
   generate:

{ragger-1.21.1 → ragger-1.41.0}/.github/workflows/fast-checks.yml

@@ -7,6 +7,11 @@ on:
       - develop
       - master
   pull_request:
+# Cancel previous runs on this reference
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 
 jobs:
   lint:
@@ -59,8 +64,8 @@ jobs:
     - name: Clone
       uses: actions/checkout@v4
     - name: Check misspellings
-      uses: codespell-project/actions-codespell@v1
+      uses: codespell-project/actions-codespell@v2
       with:
         builtin: clear,rare
         check_filenames: true
-        ignore_words_list: assertIn,
+        ignore_words_list: assertIn,crate,

{ragger-1.21.1 → ragger-1.41.0}/.gitignore

@@ -6,9 +6,9 @@ coverage.xml
 build/
 dist/
 __version__.py
+.python-version
 
 tests/snapshots-tmp/
-ledger_app.toml
 
 # doc
 doc/images/*generated*

{ragger-1.21.1 → ragger-1.41.0}/CHANGELOG.md

@@ -5,6 +5,229 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.41.0] - 2025-12-09
+
+### Added
+
+- Class `StatusWords` with default Status Words values, as defined in the SDK
+
+## [1.40.4] - 2025-11-20
+
+### Fixed
+
+- Fix navigation in functions `xxx_with_warning` with multiple warning screens for Nano on NBGL
+
+## [1.40.3] - 2025-11-06
+
+### Fixed
+
+- Add new parameter in `navigation_scenario` functions `xxx_with_warning` to specify the number of warning screens
+
+## [1.40.2] - 2025-09-09
+
+### Fixed
+
+- Fix APEX keyboards positions
+
+## [1.40.1] - 2025-09-03
+
+### Fixed
+
+- Fix APEX BUTTON_LOWER_LEFT coordinates
+
+## [1.40.0] - 2025-08-01
+
+### Added
+
+- Add two new devices: Apex_p and Apex_m
+
+## [1.39.0] - 2025-07-22
+
+### Added
+
+- Align libraries loading for swap standalone tests with library loading for eth plugin tests
+
+## [1.38.0] - 2025-07-16
+
+### Changed
+
+- `log_apdu_file` option allows to set the filename pattern when executing multiple tests
+
+### Fixed
+
+- yield true on async to notify the action has been completed (physical backends)
+
+## [1.37.1] - 2025-05-16
+
+### Fixed
+
+- minor bug fixes on the PhysicalDevice navigation flow
+- OCR enhancements on physical backend to detect words
+
+### Added
+- Key presses shortcuts (y/n) to navigate through the ragger GUI with a physical backend
+
+## [1.37.0] - 2025-05-16
+
+### Changed
+
+- `exchange_async_raw` on the speculos backend can yield if the apdu has a response or not as a boolean
+
+## [1.36.1] - 2025-06-16
+
+### Fixed
+
+- Added toml as a dependency (requided in utils/misc.py)
+
+## [1.36.0] - 2025-05-30
+
+### Changed
+
+- Enable to use both MAIN_APP_DIR and SIDELOADED_APPS options (required to perform Swap tests) 
+ 
+
+## [1.35.0] - 2025-05-14
+
+### Changed
+
+- Using `ledgered` Devices instead of local `Firmware` / `FIRMWARES`.
+  Basically `ledgered.device.DeviceType` replaces the `ragger.firmware.Firmware` enum, and
+  `ledgered.device.Devices` replaces `FIRMWARES`.
+- `ragger.firmware.Firmware` is now a proxy to `ledgered` types and prints deprecation messages.
+
+## [1.34.0] - 2025-04-28
+
+### Changed
+
+- Use pytest builtin --log-level instead of custom --Verbose
+
+### Fixed
+
+- Fix scenario navigation regular expression matching partial words
+
+## [1.33.0] - 2025-04-23
+
+### Added
+
+- conftest: `--no-nav` option to completely disable the navigation during the tests.
+- Retrieve `sdk_graphics` from elf file
+- Add new functions `review_xxx_with_warning` to include the warning screen acknowledge
+- Adapt `NavigationScenarioData` for Nano using NBGL
+
+## [1.32.1] - 2025-04-04
+
+### Fixed
+
+- Reviews navigation on touchable devices (Flex, Stax) no longer 'taps', but 'swipes'
+
+## [1.32.0] - 2025-03-31
+
+### Changed
+
+- Upgrade PyQt5 to PyQt6
+
+## [1.31.1] - 2025-03-26
+
+### Fixed
+
+- Add missing method to physical device interface
+
+## [1.31.0] - 2025-03-26
+
+### Changed
+
+- Reactivate logs like "Saving screenshot to image" (which were removed in v1.29.0)
+
+## [1.30.0] - 2025-03-21
+
+### Added
+
+- Added support for Python 3.13
+
+## [1.29.0] - 2025-03-06
+
+### Changed
+
+- Use `--Verbose` option to increase `pytest` verbosity. It adds log timestamps, some test-specific
+  logs, and the verbose option is forwarded to Speculos.
+
+## [1.28.0] - 2025-03-05
+
+### Added
+
+- Added --pki_prod option that can be forwarded to Speculos upon usage
+
+## [1.27.1] - 2025-02-26
+
+### Fixed
+
+- Fixed backend being instantiated even when the test needs a different setup
+
+## [1.27.0] - 2025-02-21
+
+### Added
+
+- Added support for different test setup
+
+## [1.26.0] - 2025-02-06
+
+### Added
+
+- Added support for Python 3.12
+- SWIPE support for physical backend
+
+### Removed
+
+- Drop support for Python 3.8
+
+### Fixed
+
+- `_actionhint` element location (covered previously by the snapshot image)
+- Physical backend -specific imports (`PIL`, `tesseract`) are postponed to avoid raising when using
+  Speculos only
+
+## [1.25.0] - 2024-12-20
+
+### Added
+- navigator: `Navigator.navigate_until_text_and_compare` and `Navigator.navigate_until_text` now
+             accept a `snap_start_idx` argument, like `Navigator.navigate_and_compare`.
+
+## [1.24.0] - 2024-10-03
+
+### Added
+- conftest: Added 'all_eink' option for the `--device` argument to target Stax + Flex
+- conftest: Added a autouse fixture to skip unsupported devices
+
+### Fixed
+
+- firmware/stax: Choice List positions were no longer correct compared to latest NBGL evolutions
+
+## [1.23.0] - 2024-07-25
+
+### Changed
+
+- Rust app: get target directory from cargo metadata (workspace compatible)
+
+## [1.22.1] - 2024-07-23
+
+### Fixed
+
+- firmware/flex: Wrong keyboard position
+
+## [1.22.0] - 2024-07-22
+
+### Added
+
+- firmware/flex: Added the suggestion buttons positions (used with keyboard)
+
+### Changed
+
+- firmware/stax: Updated the suggestion buttons positions (used with keyboard)
+
+### Fixed
+
+- firmware/flex: Wrong keyboard position
+
 ## [1.21.1] - 2024-07-16
 
 ### Fixed

{ragger-1.21.1/src/ragger.egg-info → ragger-1.41.0}/PKG-INFO

@@ -1,24 +1,26 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: ragger
-Version: 1.21.1
+Version: 1.41.0
 Summary: Testing framework using Speculos and LedgerComm as backends
 Author-email: Ledger <hello@ledger.fr>
 Project-URL: Homepage, https://github.com/LedgerHQ/ragger
 Project-URL: Bug Tracker, https://github.com/LedgerHQ/ragger/issues
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS :: MacOS X
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: bip_utils>=2.4.0
 Requires-Dist: py-sr25519-bindings<0.3.0,>=0.2.0
-Requires-Dist: ledgered>=0.6.3
+Requires-Dist: ledgered>=0.10.1
+Requires-Dist: toml
 Provides-Extra: tests
 Requires-Dist: pytest; extra == "tests"
 Requires-Dist: pytest-cov; extra == "tests"
@@ -30,7 +32,6 @@ Requires-Dist: flake8-pyproject; extra == "checkers"
 Requires-Dist: mypy; extra == "checkers"
 Requires-Dist: types-toml; extra == "checkers"
 Requires-Dist: bandit; extra == "checkers"
-Requires-Dist: pyqt5-stubs; extra == "checkers"
 Provides-Extra: doc
 Requires-Dist: pylint; extra == "doc"
 Requires-Dist: sphinx; extra == "doc"
@@ -40,21 +41,24 @@ Requires-Dist: sphinx-copybutton; extra == "doc"
 Requires-Dist: Jinja2>=3.0; extra == "doc"
 Requires-Dist: docutils==0.16; extra == "doc"
 Provides-Extra: speculos
-Requires-Dist: speculos>=0.9.1; extra == "speculos"
+Requires-Dist: speculos>=0.13.1; extra == "speculos"
 Requires-Dist: mnemonic; extra == "speculos"
 Provides-Extra: ledgercomm
 Requires-Dist: ledgercomm>=1.2.1; extra == "ledgercomm"
 Requires-Dist: ledgercomm[hid]>=1.2.1; extra == "ledgercomm"
-Requires-Dist: pyqt5; extra == "ledgercomm"
+Requires-Dist: pyqt6; extra == "ledgercomm"
 Requires-Dist: pytesseract; extra == "ledgercomm"
+Requires-Dist: pillow; extra == "ledgercomm"
 Provides-Extra: ledgerwallet
 Requires-Dist: ledgerwallet>=0.4.0; extra == "ledgerwallet"
-Requires-Dist: pyqt5; extra == "ledgerwallet"
+Requires-Dist: pyqt6; extra == "ledgerwallet"
 Requires-Dist: pytesseract; extra == "ledgerwallet"
+Requires-Dist: pillow; extra == "ledgerwallet"
 Provides-Extra: all-backends
 Requires-Dist: ragger[speculos]; extra == "all-backends"
 Requires-Dist: ragger[ledgercomm]; extra == "all-backends"
 Requires-Dist: ragger[ledgerwallet]; extra == "all-backends"
+Dynamic: license-file
 
 # Ragger
 
@@ -66,16 +70,16 @@ Requires-Dist: ragger[ledgerwallet]; extra == "all-backends"
 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:
+It mainly consists of an interface which is implemented by three backends:
 
 - an emulator-only backend, `SpeculosBackend`, which uses
   [`SpeculosClient`](https://github.com/LedgerHQ/speculos/blob/master/speculos/client.py)
-  to run an app on a Speculos emulator. With this backend, APDU can be send directly,
+  to run an app on a Speculos emulator. With this backend, APDU can be sent 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
+  `LedgerWalletBackend`, which use respectively the
   [`LedgerComm` library](https://github.com/LedgerHQ/ledgercomm) or the
   [`LedgerWallet` library](https://github.com/LedgerHQ/ledgerctl/) to discuss
   with a physical device. In these cases, the physical device must be started,
@@ -125,7 +129,7 @@ different backends and that allow to interact with a device (either a real devic
 
 * `send`: send a formatted APDU.
 * `send_raw`: send a raw APDU.
-* `receive`: receive a response ADPU.
+* `receive`: receive a response APDU.
 * `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).

{ragger-1.21.1 → ragger-1.41.0}/README.md

@@ -8,16 +8,16 @@
 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:
+It mainly consists of an interface which is implemented by three backends:
 
 - an emulator-only backend, `SpeculosBackend`, which uses
   [`SpeculosClient`](https://github.com/LedgerHQ/speculos/blob/master/speculos/client.py)
-  to run an app on a Speculos emulator. With this backend, APDU can be send directly,
+  to run an app on a Speculos emulator. With this backend, APDU can be sent 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
+  `LedgerWalletBackend`, which use respectively the
   [`LedgerComm` library](https://github.com/LedgerHQ/ledgercomm) or the
   [`LedgerWallet` library](https://github.com/LedgerHQ/ledgerctl/) to discuss
   with a physical device. In these cases, the physical device must be started,
@@ -67,7 +67,7 @@ different backends and that allow to interact with a device (either a real devic
 
 * `send`: send a formatted APDU.
 * `send_raw`: send a raw APDU.
-* `receive`: receive a response ADPU.
+* `receive`: receive a response APDU.
 * `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).

{ragger-1.21.1 → ragger-1.41.0}/doc/index.rst

@@ -2,8 +2,7 @@ The Ragger framework
 ====================
 
 ``Ragger`` is a Python framework which aims at simplifying the test and overall
-automatic manipulation of applications running on Ledger devices: NanoS, NanoS+,
-NanoX, Stax and Flex.
+automatic manipulation of applications running on Ledger devices.
 
 It is composed of a tiny wrapper around other Ledger's libraries which abstract
 and/or provide access to Ledger's cold wallet, and higher-level classes allowing

{ragger-1.21.1 → ragger-1.41.0}/doc/rationale.rst

@@ -103,7 +103,7 @@ Dealing with UI and user interaction is never simple. Nano devices has only two
 user physical inputs, through the two buttons, which already allows some
 elaborate combinations that could be challenging to test automatically.
 
-With the touchable screens of Stax or Flex devices, the number of possibilities
+With the touchable screens devices, the number of possibilities
 drastically increases.
 
 ``Ragger`` embeds tools allowing to ease the development and the maintenance of

{ragger-1.21.1 → ragger-1.41.0}/doc/source.rst

@@ -74,6 +74,9 @@ should expect. This is declared with this class:
 
    .. autoattribute:: FLEX
 
+   .. autoattribute:: APEX_P
+      
+   .. autoattribute:: APEX_M      
 
 ``ragger.firmware.touch``
 ++++++++++++++++++++++++

{ragger-1.21.1 → ragger-1.41.0}/doc/tutorial_conftest.rst

@@ -429,6 +429,9 @@ Running the tests on specific device is automatically integrated with the
 - ``--device nanox``,
 - ``--device nanosp``,
 - ``--device stax``,
+- ``--device flex``,
+- ``--device apex_p``,
+- ``--device apex_m``,
 - ``--device all``.
 
 This last option can only work with the :class:`SpeculosBackend

{ragger-1.21.1 → ragger-1.41.0}/doc/tutorial_screen.rst

@@ -1,6 +1,6 @@
 .. _tutorial_screen:
 
-Complex UI management - Flex / Stax
+Complex UI management - touchable screen devices
 ===================================
 
 Interacting programmatically with an application tends to be a non-trivial
@@ -16,7 +16,7 @@ specifically about the UI, we saw :ref:`previously
 to cope with simple physical interactions (like on the Nano devices: only two
 buttons). But what to do with more complex interfaces?
 
-In particular, interacting with the touch screen devices (Stax or Flex) can be
+In particular, interacting with the touch screen devices can be
 bothersome. It is hard to track of button positions, pages layouts and such.
 
 Study case
@@ -66,7 +66,7 @@ to change some button position, or if higher-level graphic objects (such as
 the "info" button to the top left -, all this code becomes deprecated.
 
 
-That's why ``Ragger`` mimics the Flex/Stax SDK graphics library and provides
+That's why ``Ragger`` mimics the SDK graphics library and provides
 :term:`Layout` and :term:`Use Case` (:term:`Page` will also come soon) classes
 that keep track of every interactive screen elements and expose meaningful
 methods to interact with them.
@@ -131,7 +131,7 @@ way than if positions were still necessary:
    First of all, the buttons may be at the same place, but they don't carry the
    same purpose, and it is a good idea to reflect that on the code.
 
-   Second, if in a future version the Flex/Stax design changes and one of these
+   Second, if in a future version the devices design changes and one of these
    button moves somewhere else on the screen's footer, **the layouts will be
    updated accordingly** in ``Ragger``, and the ``CancelFooter`` or ``ExitFooter``
    will still be valid, hence all code using this class remains valid too.

ragger-1.41.0/ledger_app.toml

@@ -0,0 +1,5 @@
+# Fake boilerplate application manifest for ragger tests
+[app]
+build_directory = "./"
+sdk = "C"
+devices =  ["nanos", "nanos+", "nanox", "stax", "flex", "apex_p"]