Skip to content

E2E:Speculos

Jump to bottom
Victor Alber edited this page May 20, 2026 · 1 revision

E2E Speculos

Speculos is an emulator for Ledger Nano apps. In Ledger Live E2E tests, it lets scenarios interact with emulated Ledger device apps for flows such as address verification, sending, swapping, and other blockchain operations.

Why Speculos

Speculos lets E2E tests exercise behavior closer to real user interactions. Instead of relying only on mocks, tests can instantiate Ledger app binaries, interact with them, and validate the Ledger Live behavior around those device interactions.

How It Works

Speculos acts as a launcher. In Ledger Live E2E tests, the goal is to instantiate it with the correct libraries that will be used later in the test scenario.

In swap flows, up to two libraries can be needed: the app to swap from and the app to swap to. If a swap is performed from ETH to USDT, only the ETH library is needed because USDT is an ERC20 token. To make this work consistently, app candidates are added to a map based on the selected device and latest app versions so each library is present no more than once.

The swap dependencies are loaded at the beginning of a scenario, within the exchange app.

Lifecycle

  1. Spawning Speculos: for each cryptocurrency, a dedicated Speculos instance is spawned. This instance emulates the Nano app needed for the tests.
  2. Running tests: the test scenario interacts with the Speculos instance to simulate real blockchain operations.
  3. Terminating Speculos: when the tests complete, the Speculos instance is terminated to free resources.

Test data can be prepared before the run with the Ledger Live CLI. See E2E prerequisites & environment.

Transaction Broadcast Policy

On CI, transaction broadcasting is limited to Monday nightly runs. Broadcasting every day would create high fees and could exhaust the funds attached to the Speculos seed. Limiting broadcasts keeps the seed usable for the following scenarios.

Desktop local runs can toggle broadcast behavior with DISABLE_TRANSACTION_BROADCAST:

DISABLE_TRANSACTION_BROADCAST=1 pnpm desktop test:playwright:speculos swap

Mobile CI exposes an enable_broadcast workflow input. See Mobile E2E CI.

Device Selection

Select the emulated device with SPECULOS_DEVICE:

export SPECULOS_DEVICE=nanoX

The available device choices depend on the platform workflow:

  • Current Desktop and Mobile README setup examples document nanoSP, nanoX, nanoS, stax, flex, and nanoGen5.
  • Some CI workflow inputs may expose a narrower set of devices. Check the platform workflow before launching a CI run.

Limitations

Speculos can emulate the applications running on Nano devices, but not the underlying device operating system. As a result, some Ledger Live functionality cannot be fully covered by Speculos-based tests.

Examples:

  • App installation: tests cannot simulate downloading and installing apps onto the Nano device.
  • My Ledger section: operations involving app management on the device cannot be fully tested through Speculos.

We continue to explore ways to mitigate these limitations and improve coverage and reliability.


Clone this wiki locally