ragger 1.37.1__tar.gz → 1.40.0__tar.gz

{ragger-1.37.1 → ragger-1.40.0}/.github/workflows/build_and_tests.yml

@@ -76,13 +76,6 @@ jobs:
         name: boilerplate_binaries_nanos
         path: ./build/
 
-    - name: Create boilerplate manifest
-      run: |
-        echo """[app]
-        build_directory = \"./\"
-        sdk = \"C\"
-        devices =  [\"nanos\", \"nanos+\", \"nanox\", \"stax\", \"flex\"]""" > ledger_app.toml
-
     - name: Check the downloaded files
       run: tree .
 

{ragger-1.37.1 → ragger-1.40.0}/.gitignore

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

{ragger-1.37.1 → ragger-1.40.0}/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.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
@@ -32,6 +54,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - Enable to use both MAIN_APP_DIR and SIDELOADED_APPS options (required to perform Swap tests) 
+ 
 
 ## [1.35.0] - 2025-05-14
 

{ragger-1.37.1/src/ragger.egg-info → ragger-1.40.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragger
-Version: 1.37.1
+Version: 1.40.0
 Summary: Testing framework using Speculos and LedgerComm as backends
 Author-email: Ledger <hello@ledger.fr>
 Project-URL: Homepage, https://github.com/LedgerHQ/ragger
@@ -79,7 +79,7 @@ It mainly consists of an interface which is implemented by three backends:
 
 - two physical backends (although technically they are agnostic, but the
   `SpeculosClient` is superior with an emulator), `LedgerCommBackend` and
-  `LedgerWalletbackend`, 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,

{ragger-1.37.1 → ragger-1.40.0}/README.md

@@ -17,7 +17,7 @@ It mainly consists of an interface which is implemented by three backends:
 
 - two physical backends (although technically they are agnostic, but the
   `SpeculosClient` is superior with an emulator), `LedgerCommBackend` and
-  `LedgerWalletbackend`, 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,

{ragger-1.37.1 → ragger-1.40.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.37.1 → ragger-1.40.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.37.1 → ragger-1.40.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.37.1 → ragger-1.40.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.37.1 → ragger-1.40.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.40.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"]

{ragger-1.37.1 → ragger-1.40.0}/pyproject.toml

@@ -118,3 +118,4 @@ exclude_lines = [
 
 [tool.flake8]
 max-line-length = 120
+extend-ignore = "E502"

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/__version__.py

@@ -1,7 +1,14 @@
 # file generated by setuptools-scm
 # don't change, don't track in version control
 
-__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
@@ -9,13 +16,19 @@ if TYPE_CHECKING:
     from typing import Union
 
     VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
 else:
     VERSION_TUPLE = object
+    COMMIT_ID = object
 
 version: str
 __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
 
-__version__ = version = '1.37.1'
-__version_tuple__ = version_tuple = (1, 37, 1)
+__version__ = version = '1.40.0'
+__version_tuple__ = version_tuple = (1, 40, 0)
+
+__commit_id__ = commit_id = 'g3d7c1dd19'

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/backend/interface.py

@@ -144,8 +144,8 @@ class BackendInterface(ABC):
         :type ins: int
         :param p1: First instruction parameter, defaults to 0
         :type p1: int
-        :param p1: Second instruction parameter, defaults to 0
-        :type p1: int
+        :param p2: Second instruction parameter, defaults to 0
+        :type p2: int
         :param data: Command data
         :type data: bytes
 
@@ -205,8 +205,8 @@ class BackendInterface(ABC):
         :type ins: int
         :param p1: First instruction parameter, defaults to 0
         :type p1: int
-        :param p1: Second instruction parameter, defaults to 0
-        :type p1: int
+        :param p2: Second instruction parameter, defaults to 0
+        :type p2: int
         :param data: Command data
         :type data: bytes
 
@@ -262,8 +262,8 @@ class BackendInterface(ABC):
         :type ins: int
         :param p1: First instruction parameter, defaults to 0
         :type p1: int
-        :param p1: Second instruction parameter, defaults to 0
-        :type p1: int
+        :param p2: Second instruction parameter, defaults to 0
+        :type p2: int
         :param data: Command data
         :type data: bytes
 
@@ -292,7 +292,7 @@ class BackendInterface(ABC):
 
         :raises ExceptionRAPDU: If the `raises` attribute is True, this method
                                   will raise if the backend returns a status code
-                                  not registered a a `valid_statuses`
+                                  not registered as a `valid_statuses`
 
         :return: None
         :rtype: NoneType

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/backend/ledgercomm.py

@@ -106,7 +106,7 @@ class LedgerCommBackend(PhysicalBackend):
         return result
 
     @contextmanager
-    def exchange_async_raw(self, data: bytes = b"") -> Generator[None, None, None]:
+    def exchange_async_raw(self, data: bytes = b"") -> Generator[bool, None, None]:
         self.send_raw(data)
-        yield
+        yield True
         self._last_async_response = self.receive()

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/backend/ledgerwallet.py

@@ -98,7 +98,7 @@ class LedgerWalletBackend(PhysicalBackend):
         return result
 
     @contextmanager
-    def exchange_async_raw(self, data: bytes = b"") -> Generator[None, None, None]:
+    def exchange_async_raw(self, data: bytes = b"") -> Generator[bool, None, None]:
         self.send_raw(data)
-        yield
+        yield True
         self._last_async_response = self.receive()

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/conftest/base_conftest.py

@@ -1,3 +1,4 @@
+import os
 import pytest
 import logging
 from dataclasses import fields
@@ -39,7 +40,12 @@ def pytest_addoption(parser):
                      action="store_true",
                      default=False,
                      help="Have Speculos accept prod PKI certificates instead of test")
-    parser.addoption("--log_apdu_file", action="store", default=None, help="Log the APDU in a file")
+    parser.addoption("--log_apdu_file",
+                     action="store",
+                     default=None,
+                     nargs="?",
+                     const="apdu.log",
+                     help="Log the APDU in a file. If no pattern provided, uses 'apdu_xxx.log'.")
     parser.addoption("--seed", action="store", default=None, help="Set a custom seed")
     # Always allow "default" even if application conftest does not define it
     allowed_setups = conf.OPTIONAL.ALLOWED_SETUPS
@@ -72,10 +78,23 @@ def golden_run(pytestconfig):
     return pytestconfig.getoption("golden_run")
 
 
-@pytest.fixture(scope="session")
-def log_apdu_file(pytestconfig):
+@pytest.fixture(scope=conf.OPTIONAL.BACKEND_SCOPE)
+def log_apdu_file(request, pytestconfig, full_test_name: str):
     filename = pytestconfig.getoption("log_apdu_file")
-    return Path(filename).resolve() if filename is not None else None
+    if filename is None:
+        return None
+
+    path = Path(filename)
+    # Get nb of collected tests to be executed
+    collected_items = len(request.session.items)
+    if collected_items == 1:
+        # Single test - use filename directly
+        return path.resolve()
+    # Multiple tests - create a file per test
+    MAX_TEST_NAME_LENGTH = 100  # Define a safe maximum length for test names
+    truncated_test_name = full_test_name[:MAX_TEST_NAME_LENGTH]  # Truncate if necessary
+    new_filename = f"{path.stem}_{truncated_test_name}{path.suffix}"
+    return Path(new_filename).resolve()
 
 
 @pytest.fixture(scope="session")
@@ -112,6 +131,37 @@ def default_screenshot_path(root_pytest_dir: Path) -> Path:
     return root_pytest_dir
 
 
+@pytest.fixture(scope=conf.OPTIONAL.BACKEND_SCOPE)
+def full_test_name(request) -> str:
+    # Get the name of current pytest test
+    test_name = request.node.name
+
+    if '[' in test_name:
+        # Split all parameters
+        base_name, params = test_name.rsplit('[', 1)
+        params = params.rstrip(']')
+
+        # Split parameters by '-' and filter out device names
+        param_list = [p for p in params.split('-') if p not in DEVICES]
+
+        # Rebuild test name with remaining parameters
+        if param_list:
+            test_name = f"{base_name}[{'-'.join(param_list)}]"
+        else:
+            test_name = base_name
+
+    # Clean up for filename friendliness by replacing special characters with underscores
+    translation_table = str.maketrans({
+        '[': '_',
+        ']': '',
+        '-': '_',
+        '/': '_',
+        "'": '',
+    })
+    clean_name = test_name.translate(translation_table)
+    return clean_name
+
+
 @pytest.fixture
 def test_name(request) -> str:
     # Get the name of current pytest test
@@ -225,15 +275,16 @@ def prepare_speculos_args(root_pytest_dir: Path,
         main_app_path = find_application(project_root_dir / manifest.app.build_directory,
                                          device_name, manifest.app.sdk)
 
-    # Find all libraries that have to be sideloaded
+    # If this repository does not hold the main app, then we need to load this repository's application as a library
     if conf.OPTIONAL.MAIN_APP_DIR is not None:
         # This repo holds the library, not the standalone app: search in root_dir/build
         lib_path = find_application(project_root_dir, device_name, manifest.app.sdk)
         speculos_args.append(f"-l{lib_path}")
 
+    # Legacy lib method, remove once exchange is ported
     if len(conf.OPTIONAL.SIDELOADED_APPS) != 0:
         # We are testing a a standalone app that needs libraries: search in SIDELOADED_APPS_DIR
-        if conf.OPTIONAL.SIDELOADED_APPS_DIR == "":
+        if conf.OPTIONAL.SIDELOADED_APPS_DIR is None:
             raise ValueError("Configuration \"SIDELOADED_APPS_DIR\" is mandatory if "
                              "\"SIDELOADED_APPS\" is used")
         libs_dir = Path(project_root_dir / conf.OPTIONAL.SIDELOADED_APPS_DIR)
@@ -241,6 +292,16 @@ def prepare_speculos_args(root_pytest_dir: Path,
         for coin_name, lib_name in conf.OPTIONAL.SIDELOADED_APPS.items():
             lib_path = find_library_application(libs_dir, coin_name, device_name)
             speculos_args.append(f"-l{lib_name}:{lib_path}")
+    else:
+        # Keep this method instead
+        # Find all external libraries that have to be sideloaded
+        if conf.OPTIONAL.SIDELOADED_APPS_DIR is not None:
+            sideloaded_dir = project_root_dir / conf.OPTIONAL.SIDELOADED_APPS_DIR
+            subdirs = sorted(
+                filter(lambda d: (sideloaded_dir / d).is_dir(), os.listdir(sideloaded_dir)))
+            for subdir in subdirs:
+                lib_path = find_application(sideloaded_dir / subdir, device_name, manifest.app.sdk)
+                speculos_args.append(f"-l{lib_path}")
 
     # Check if custom user seed has been provided through CLI or optional configuration.
     # CLI user seed has priority over the optional configuration seed.

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/conftest/configuration.py

@@ -7,37 +7,39 @@ class OptionalOptions:
     APP_NAME: str
     MAIN_APP_DIR: Optional[str]
     SIDELOADED_APPS: dict
-    SIDELOADED_APPS_DIR: str
+    SIDELOADED_APPS_DIR: Optional[str]
     BACKEND_SCOPE: str
     CUSTOM_SEED: str
     ALLOWED_SETUPS: List[str]
 
 
 OPTIONAL = OptionalOptions(
-    # Use this parameter if you want to make sure the right app is started upon backend instantiation.
-    # This is only used for LedgerWallet and LedgerComm backend.
+    # Use this parameter if you want physical Ragger backends (LedgerWallet and LedgerComm) to start
+    # your application from the Dashboard at test start.
     APP_NAME=str(),
 
-    # If not None, the app being tested with Ragger should be loaded as a library and not as a standalone
-    # app. This parameter points to the repository holding the "main app", i.e the app started by the
-    # backend, which will then use the "local app" as a library.
-    # Use cases : your app is an Ethereum plugin, which will be used as a library by the Ethereum app.
-    # MAIN_APP_DIR contains the directory where the Ethereum app binaries are stored.
-    # example: "./tests/"
+    # If not None, the application being tested with Ragger should be loaded as a library and not as
+    # a standalone application. This parameter points to the repository holding the "main app", i.e
+    # the application started from the Dashboard, which will then use the "local app" as a library.
+    # Example use case: your application is an Ethereum plugin, which will be used as a library by
+    # the Ethereum application.
+    # MAIN_APP_DIR is the directory where the Ethereum application is cloned.
+    #
+    # example: configuration.OPTIONAL.MAIN_APP_DIR = "tests/.test_dependencies/"
+    # Speculos will then start "tests/.test_dependencies/ethereum/build/<device>/bin/app.elf"
+    # There must be exactly one application cloned inside this directory.
     MAIN_APP_DIR=None,
 
-    # use this parameter if you want Speculos to sideload libraries being installed on the device
-    # Useful for Ethereum main app and exchange app, for example
-    # example: {"bitcoin": "Bitcoin", "ethereum": "Ethereum"}
-    # this would result in Speculos being launched with -lbitcoin:/path/to/bitcoin_device.elf
-    # Mutually exclusive with LOAD_MAIN_APP_AS_LIBRARY
+    # Deprecated
     SIDELOADED_APPS=dict(),
 
-    # Mandatory in case SIDELOADED_APPS is used
-    # Relative path to the directory that will store your libs, from the top repository of your application
-    # example: "test/lib_binaries/"
-    # place your compiled application inside with naming "name_device.elf"
-    SIDELOADED_APPS_DIR=str(),
+    # Relative path to the directory that will store library applications needed for the test.
+    # They will be sideloaded by Speculos and can then be called by the main application. This
+    # emulates the applications being installed on the device alongside the main application.
+    #
+    # example: configuration.OPTIONAL.SIDELOADED_APPS_DIR = "tests/.test_dependencies/libraries"
+    # Speculos will then sideload "tests/.test_dependencies/libraries/*/build/<device>/bin/app.elf"
+    SIDELOADED_APPS_DIR=None,
 
     # As the backend instantiation may take some time, Ragger supports multiple backend scopes.
     # You can choose to share the backend instance between {session / module / class / function}
@@ -48,8 +50,10 @@ OPTIONAL = OptionalOptions(
     # Use this parameter if you want speculos to use a custom seed instead of the default one.
     # This would result in speculos being launched with --seed <CUSTOM_SEED>
     # If a seed is provided through the "--seed" pytest command line option, it will override this one.
+    # /!\ DO NOT USE SEEDS WITH REAL FUNDS /!\
     CUSTOM_SEED=str(),
 
+    # /!\ DEPRECATED /!\
     # Use this parameter if you want ragger to handle running different test suites depending on setup
     # Useful when some tests need certain build options and other tests need other build options, or a
     # different Speculos command line
@@ -59,5 +63,6 @@ OPTIONAL = OptionalOptions(
     #
     # "default" setup is always allowed, all tests without explicit decoration depend on default
     # and the --setup option defaults to "default"
+    # /!\ DEPRECATED /!\
     ALLOWED_SETUPS=["default"],
 )

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/firmware/structs.py

@@ -28,6 +28,8 @@ class Firmware(IntEnum):
     NANOX = DeviceType.NANOX
     STAX = DeviceType.STAX
     FLEX = DeviceType.FLEX
+    APEX_P = DeviceType.APEX_P
+    APEX_M = DeviceType.APEX_M
 
     @staticmethod
     def deprec_warning() -> None:

{ragger-1.37.1 → ragger-1.40.0}/src/ragger/firmware/touch/layouts.py

@@ -88,18 +88,6 @@ class TappableCenter(_TappableElement):
     pass
 
 
-class KeyboardConfirmationButton(Element):
-    """
-    This layout is to be used as the confirmation button when coupled with a keyboard.
-
-    On Stax devices, the screen is high enough that this is equivalent to TappableCenter, however
-    on Flex, this button is not centered, but slightly closer to the top of the screen.
-    """
-
-    def confirm(self):
-        self.client.finger_touch(*self.positions)
-
-
 # Headers
 #########
 class RightHeader(_TappableElement):