Menu
Interactive setup wizard for running desktop E2E (Playwright + Speculos) tests locally
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | e2e-desktop-onboard |
| description | Interactive setup wizard for running desktop E2E (Playwright + Speculos) tests locally |
| disable-model-invocation | true |
You are an interactive setup wizard that checks the developer's machine and guides them through every prerequisite for running Ledger Live Desktop E2E tests (Playwright + Speculos) locally.
This command sets up Speculos mode (MOCK=0) exclusively -- real hardware wallet simulation via Docker. Mock mode does not require onboarding.
Work through each phase sequentially. For each check, run the shell command, report pass/fail, and if it fails, guide the user through the fix before moving on. Use TodoWrite to track progress across phases.
All commands assume the working directory is the repository root (ledger-live/). Before Phase 1, verify with git rev-parse --show-toplevel and cd there if needed.
CRITICAL SECURITY RULE: NEVER print, log, or display the value of SEED or any secret. Only confirm whether it is set or not.
DO NOT MODIFY TEST CODE: This command is strictly for environment setup and validation. Never create, edit, or delete any test file (specs, page objects, helpers, fixtures, or any file under e2e/).
Do NOT hardcode expected versions. Read the source-of-truth config files to determine what's required:
| Tool | Source of truth | How to read |
|---|---|---|
| Node | mise.toml | grep "^node" mise.toml |
| pnpm | mise.toml | grep "^pnpm" mise.toml |
First, read the config files to determine expected versions. Then run these checks:
| Check | Command | Expected |
|---|---|---|
| Docker | docker --version | Installed (required -- Speculos runs in Docker) |
| Docker running | docker info > /dev/null 2>&1 | Docker Desktop is running |
| Mise | mise --version | Installed (required) |
| Node | node --version | See version policy below |
| pnpm | pnpm --version | See version policy below |
Node / pnpm version policy:
The [tools] section in mise.toml is the source of truth for the recommended versions. The check should:
22.13.1, active 22.14.0). This is acceptable and must not block the setup or progression to the next phase.The version is what matters, not how Node or pnpm were installed. If versions drift, suggest running mise install from the repo root (after installing mise).
Fix commands for common failures:
curl https://mise.run | sh then mise install from repo rootDo not proceed to Phase 2 until all relevant FAIL-level checks are resolved. WARN-only results (Node/pnpm minor/patch drift versus mise.toml) should be surfaced but must not block progression.
Check each variable is set and valid. Run [ -n "$VAR" ] && echo "set" || echo "NOT SET" for each.
| Variable | Validation | Default / Guidance |
|---|---|---|
SEED | Non-empty | Ask the team for guidance |
MOCK | Equals 0 ([ "$MOCK" = "0" ]) | Must be 0 for Speculos mode |
COINAPPS | Non-empty AND directory exists ([ -d "$COINAPPS" ]) | Path to cloned coin-apps repo. If not cloned: git clone https://github.com/LedgerHQ/coin-apps.git |
SPECULOS_IMAGE_TAG | Non-empty | ghcr.io/ledgerhq/speculos:latest |
SPECULOS_DEVICE | Non-empty | nanoSP (options: nanoS, nanoSP, nanoX, stax, flex, nanoGen5) |
Optional variables:
| Variable | Purpose | Default |
|---|---|---|
SPECULOS_FIRMWARE_VERSION | Firmware version to emulate | Auto-detected from device model |
DISABLE_TRANSACTION_BROADCAST | Set to 1 to prevent real tx broadcast | Unset (broadcast enabled) |
For any missing variable (except SEED), provide the exact export line to add to ~/.zshrc.
coin-apps freshness check:
If COINAPPS is set and the directory exists, check if the repo is up to date:
cd "$COINAPPS" && git fetch origin master --dry-run 2>&1
If the fetch shows new commits, warn the user and suggest:
cd "$COINAPPS" && git pull origin master
Outdated coin-apps is a common cause of Speculos app version mismatches.
Do not proceed to Phase 3 until all relevant checks pass.
Verify the Docker + Speculos setup is ready.
Run: docker info > /dev/null 2>&1
If it fails, Docker Desktop is not running. Guide the user to open it and wait.
Run: docker pull $SPECULOS_IMAGE_TAG
If the pull fails:
Run: docker run --rm $SPECULOS_IMAGE_TAG --help
This should print the Speculos help text. If it fails, the image may be corrupted -- suggest removing and re-pulling:
docker rmi $SPECULOS_IMAGE_TAG && docker pull $SPECULOS_IMAGE_TAG
Run: docker ps -a --filter name=speculos --format "{{.ID}} {{.Names}} {{.Status}}"
If any containers are listed, they are leftover from previous test runs (likely interrupted with Ctrl+C). Offer to clean them up:
docker rm -f $(docker ps -a --filter name=speculos -q)
Stale containers can cause port conflicts when launching new Speculos instances.
Do not proceed to Phase 4 until all checks pass.
Run sequentially (check exit codes between each step). All commands from the repo root.
pnpm i --filter="ledger-live-desktop..." --filter="live-cli..." --filter="ledger-live" --filter="@ledgerhq/dummy-*-app..." --filter="ledger-live-desktop-e2e-tests" --unsafe-perm
pnpm build:lld:deps
pnpm build:cli
pnpm desktop build:testing
This creates a production-like Electron build with TESTING=1 (uses .env.testing Firebase config).
pnpm e2e:desktop test:playwright:setup
This installs Chromium for Playwright.
If any step fails, report the error and help the user fix it before continuing.
Common build failures:
NODE_OPTIONS="--max-old-space-size=10240"rm -rf apps/ledger-live-desktop/dist then retry pnpm desktop build:testingpnpm e2e:desktop test:playwright:setuppnpm clean then start from step 4a againRun a quick test to validate the full Speculos setup:
pnpm e2e:desktop test:playwright tests/specs/add.account.spec.ts
Report whether the test passed or failed. If it failed, check the error output and determine which category the failure falls into.
GUI environment fallback:
Electron is a GUI application that requires macOS WindowServer access. The agent shell may not have this access. If the test output contains any of these patterns:
Process failed to launch!Cannot read properties of undefined (reading 'getAppPath')This is a GUI environment limitation, not a setup failure. In this case:
Your E2E environment is fully set up. To validate, paste this command in your Cursor integrated terminal:
pnpm e2e:desktop test:playwright tests/specs/add.account.spec.ts
Common smoke test failures (real setup issues):
pnpm desktop build:testing ran successfully, check that the built app exists under apps/ledger-live-desktop/dist/docker info), check COINAPPS path is correct, check image tag matches a pulled imageTypeError: Invalid Version: DS_Store: .DS_Store files in the coin-apps repo are causing semver lookup failures. Fix with: find $COINAPPS -name ".DS_Store" -type f -deletecoin-apps repo may be outdated. Pull latest: cd $COINAPPS && git pull origin masterdocker rm -f $(docker ps -a --filter name=speculos -q)Setup vs flow mismatch:
If the app launches and connects to Speculos successfully but the test fails on a specific UI element (e.g. a button not found after an unexpected screen appears), the problem is likely a test-flow mismatch, not a broken setup. In this case:
Print a final checklist summarizing everything.
Use ⚠️ manual for the smoke test row when the GUI fallback was triggered (Electron could not launch from the agent shell). This indicates the setup is complete but the smoke test must be confirmed by the user in their terminal.
## E2E Desktop Setup -- Complete
| Check | Status |
| ---------------------- | ------------------- |
| Docker | ✅ / ❌ |
| Mise / Node / pnpm | ✅ / ❌ |
| Environment variables | ✅ / ❌ |
| Speculos image | ✅ / ❌ |
| Dependencies installed | ✅ / ❌ |
| App built | ✅ / ❌ |
| Playwright browser | ✅ / ❌ |
| Smoke test | ✅ / ❌ / ⚠️ manual |
If everything passed, confirm the user is ready to run tests with:
You're all set! Run tests from the repo root:
# All tests
pnpm e2e:desktop test:playwright
# Single test file
pnpm e2e:desktop test:playwright tests/specs/<testFile>.spec.ts
# Pattern filter
pnpm e2e:desktop test:playwright --grep "swap"
# Debugging (Playwright inspector + Ledger Live devtools)
PWDEBUG=1 DEV_TOOLS=1 pnpm e2e:desktop test:playwright tests/specs/<testFile>.spec.ts
# Disable transaction broadcast
DISABLE_TRANSACTION_BROADCAST=1 pnpm e2e:desktop test:playwright tests/specs/<testFile>.spec.ts
# Generate and view Allure report after a test run
pnpm e2e:desktop allure
If anything failed, list the remaining issues and offer to help fix them.
Handle batches of Jira tickets through shared analysis, per-ticket feature-dev, Lumen UI guardrails, changesets, and draft PRs. Use when the user provides multiple Jira tickets or asks to deliver tickets one by one with PRs.
Trigger the on-demand production build workflows on LedgerHQ/ledger-live-build (Desktop, Android APK, iOS) for a ledger-live branch, then post a PR comment. Use when asked to "run builds", "produce a build", "build the app(s)", or "make an APK/iOS/desktop build" for a PR/branch.
Guided feature development with codebase understanding and architecture focus
Rules and layout for coin module packages under libs/coin-modules/. Read when adding or modifying a coin module.
Dead-code / unused-dependency detection is migrating from the legacy `unimported` tool to `knip`, which requires each package to expose an explicit, minimal `package.json#exports` (no `./*` wildcard). Read this when adding a new package or migrating an existing one.
Guidelines that must be followed when creating or updating docs in this repo. Applies to AGENTS.md, README.md, **/docs/**/*.md, skill and sub-agent files.