End-to-end tests for the Bitkit-android and Bitkit-ios mobile app using WebdriverIO and Appium. Supports both Android and iOS platforms.
For pre-release sanity planning, use the shared release QA method or /release-sanity. See 3.1.0 for a worked example of reusing coverage and selecting remaining checks.
| Platform | Tools |
|---|---|
| Android | - Android SDK (API 33 – 35) - Emulator or real device |
| iOS (macOS only) | - Xcode (with Command Line Tools) - FFmpeg – used for video recordings and screenshots → Install via Homebrew: brew install ffmpeg |
General requirements
- Node.js (≥ 22)
- Appium server (installed locally or started via WebdriverIO)
# Clone the repo
git clone https://github.com/synonymdev/bitkit-e2e-tests.git
cd bitkit-e2e-tests
# Install dependencies
npm installartifacts/ # screenshots and (optionally) videos of failed tests
aut/ # Place your .apk / .app files here (default: bitkit_e2e.apk, Bitkit.app)
docker/ # docker compose regtest based backend for Bitkit wallet
test/
├── specs/ # Test suites (e.g., onboarding.e2e.ts)
├── qa-fixtures/ # Local QA device setup (not CI)
├── helpers/ # Test helpers: selectors, setup, actions
tools/ # QA utilities and small manual test tools
ℹ️ Screenshots and (optionally) videos of failed tests will be saved to
artifacts/. To enable video recording, set theRECORD_VIDEO=trueenvironment variable.
If you have bitkit-e2e-tests, bitkit-android, and bitkit-ios checked out in the same parent directory, you can use the helper scripts to build local artifacts (local Electrum by default). The outputs land in ./aut and are ready to be tested.
# Android (builds ../bitkit-android and copies APK to ./aut/bitkit_e2e.apk)
./scripts/build-android-apk.sh
# Legacy RN Android (builds ../bitkit and copies APK to ./aut/bitkit_rn_regtest.apk)
./scripts/build-rn-android-apk.sh
# Legacy RN iOS simulator (builds ../bitkit and copies app to ./aut/bitkit_rn_regtest_ios.app)
./scripts/build-rn-ios-sim.sh
# iOS (builds ../bitkit-ios and copies IPA to ./aut/bitkit_e2e.ipa)
./scripts/build-ios-sim.shOptional backend selection (BACKEND=local is default and can be omitted):
# Android
BACKEND=local ./scripts/build-android-apk.sh
BACKEND=regtest ./scripts/build-android-apk.sh
# Legacy RN Android
BACKEND=regtest ./scripts/build-rn-android-apk.sh
# Legacy RN iOS simulator
BACKEND=regtest ./scripts/build-rn-ios-sim.sh
# iOS
BACKEND=local ./scripts/build-ios-sim.sh
BACKEND=regtest ./scripts/build-ios-sim.shOptional Trezor Bridge support is disabled by default and can be enabled per build:
# Android emulator, local backend
TREZOR_BRIDGE=true ./scripts/build-android-apk.sh
# Android physical device, local backend
TREZOR_BRIDGE=true TREZOR_BRIDGE_URL=http://127.0.0.1:21325 ./scripts/build-android-apk.sh
# Android emulator, staging regtest backend
BACKEND=regtest TREZOR_BRIDGE=true ./scripts/build-android-apk.sh
# iOS simulator, local backend
TREZOR_BRIDGE=true TREZOR_ELECTRUM_URL=tcp://127.0.0.1:60001 ./scripts/build-ios-sim.sh
# iOS simulator, staging regtest backend
BACKEND=regtest TREZOR_BRIDGE=true ./scripts/build-ios-sim.shTo build from a worktree instead of ../bitkit-android / ../bitkit-ios (dirty or release-* checkout), set ANDROID_ROOT / IOS_ROOT.
USDT E2E setup starts a pinned fixture from bitkit-docker,
passes local USDT endpoints into both app builds, and supplies funding/pending
controls plus a real Paykit SDK peer. Keep BACKEND=regtest for Paykit journeys;
VSS, Pubky, Bitcoin and rates retain their existing staging configuration.
./scripts/usdt-fixture build
export USDT_TEST_ENV_FILE=/absolute/path/to/private.env
./scripts/usdt-fixture up
eval "$(./scripts/usdt-fixture env)"
./scripts/usdt-fixture check
./scripts/usdt-fixture smoke
./scripts/usdt-fixture max-smoke
./scripts/usdt-fixture bridge-smokeThe local docker setup includes an opt-in Trezor User Env fixture for manual hardware-wallet checks. It starts the official Trezor emulator and Bridge, but it is not part of the default docker compose up -d stack.
Default emulator state:
- Model:
T2T1 - Firmware:
2-main - Bridge:
node-bridge - Mnemonic: random 12-word BIP39 phrase generated on each
start - PIN: empty
- Passphrase protection: off
- Label:
Bitkit Test Trezor
Start the emulator:
./scripts/trezor-emulator start
./scripts/trezor-emulator statusstart prints the generated mnemonic and the first native regtest receive address (m/84h/1h/0h/0/0) so it can be funded during manual checks.
The bundled helper’s start refuses to wipe or reseed an already-running emulator. Use stop before starting a new one.
For CI or scripts, use JSON output:
./scripts/trezor-emulator start --json > artifacts/trezor-emulator.json
./scripts/trezor-emulator status --jsonstatus --json returns the current receive address metadata, but not the mnemonic.
Use the deterministic seed when you want to reuse known history/funds:
TREZOR_RANDOM_MNEMONIC=false ./scripts/trezor-emulator startOr provide an explicit seed:
TREZOR_MNEMONIC="all all all all all all all all all all all all" ./scripts/trezor-emulator startOverride the printed address coin/path when needed:
TREZOR_ADDRESS_COIN=Testnet TREZOR_ADDRESS_PATH="m/84h/1h/0h/0/0" ./scripts/trezor-emulator startUseful URLs:
- User Env dashboard:
http://localhost:23902for the pinned Android fixture,http://localhost:9002for the bundled fixture. - Trezor Bridge:
http://localhost:21325
Android uses the Trezor User Env image pinned by the selected bitkit-docker revision. The iOS setup uses the pin in docker/docker-compose.yml. Both use the Bridge message format expected by the apps.
# Local backend on pinned bitkit-docker
./scripts/local-backend up
BACKEND=local TREZOR_BRIDGE=true ./scripts/build-android-apk.sh
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@hardware_wallet"
# Staging regtest backend with pinned Trezor
./scripts/local-backend prepare
BACKEND=regtest TREZOR_BRIDGE=true ./scripts/build-android-apk.sh
BITKIT_LOCAL_BACKEND_ROOT="$(./scripts/local-backend path)" \
BACKEND=regtest ./ci_run_android.sh --mochaOpts.grep "@hardware_wallet"For manual checks, open Bitkit and use the app's developer Trezor screen to scan and connect to Bitkit Test Trezor.
This recipe uses staging regtest. If the pinned Trezor emulator is already running, use ./scripts/local-backend run ./scripts/trezor-emulator status to reuse it.
./scripts/local-backend prepare
./scripts/local-backend run ./scripts/trezor-emulator start
./scripts/local-backend run ./scripts/trezor-emulator adb
BACKEND=regtest TREZOR_BRIDGE=true TREZOR_BRIDGE_URL=http://127.0.0.1:21325 ./scripts/build-android-apk.sh# Local backend
cd docker
docker compose up -d
cd ..
./scripts/trezor-emulator start
TREZOR_BRIDGE=true TREZOR_ELECTRUM_URL=tcp://127.0.0.1:60001 ./scripts/build-ios-sim.sh
npm run e2e:ios
# Staging regtest backend
./scripts/trezor-emulator start
BACKEND=regtest TREZOR_BRIDGE=true ./scripts/build-ios-sim.sh
BACKEND=regtest npm run e2e:iosStop the emulator when finished:
# Android pinned fixture
./scripts/local-backend run ./scripts/trezor-emulator stop
# iOS bundled fixture
./scripts/trezor-emulator stopBackend and Trezor are independent. BACKEND=local uses local Bitcoin/Electrum, while BACKEND=regtest uses remote staging regtest services. The Trezor emulator always provides only the device and Bridge. Fund or mine against the same backend the app was built for.
Important: The BACKEND environment variable controls which infrastructure the tests use for blockchain operations (deposits, mining blocks):
| Backend | Infrastructure | When to use |
|---|---|---|
BACKEND=local (default) |
Local Docker stack (Bitcoin RPC on localhost:43782, Electrum on localhost:60001) | Apps built with BACKEND=local |
BACKEND=regtest |
Blocktank API over the internet (remote regtest) | Apps built with BACKEND=regtest |
⚠️ TheBACKENDmust match how the app was built. If the app connects to remote electrum, useBACKEND=regtest. If it connects to localhost, useBACKEND=local.
App override: By default tests use aut/bitkit_e2e.apk (Android) and aut/Bitkit.app (iOS). Set AUT_FILENAME to use a different file in aut/ (e.g. AUT_FILENAME=bitkit_rn_regtest.apk)
# Start the pinned local Android backend and build its APK
./scripts/local-backend up
BACKEND=local ./scripts/build-android-apk.sh
# Run the on-chain smoke test
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@onchain_1"
# Run all tests on Android (regtest backend)
BACKEND=regtest npm run e2e:android
# Run all tests on iOS
npm run e2e:ios
BACKEND=regtest npm run e2e:iosTo run a specific test file:
./scripts/local-backend run ./ci_run_android.sh --spec ./test/specs/onboarding.e2e.ts
# With regtest backend
BACKEND=regtest npm run e2e:android -- --spec ./test/specs/migration.e2e.tsTo run a specific test case:
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "Can pass onboarding correctly"To run against a different app in aut/:
BACKEND=regtest AUT_FILENAME=bitkit_rn_regtest.apk npm run e2e:androidTest suites (and some individual tests) are tagged using a simple @tag convention in the describe / ciIt titles:
describe('@backup - Backup', () => {
ciIt('@backup_1 - Can backup metadata, widget, settings and restore them', async () => {
// ...
});
});💡 Note: Use
ciItinstead ofitin specs. Locally it behaves the same, but on CI it records passing tests in/tmp/lockso retries skip already-green tests and only re-run failures.
You can use Mocha’s --grep option to run only the tests that match a given tag (regex supported). For example:
# Run only backup tests
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@backup"
# Run backup OR onboarding OR onchain tests
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@onchain|@backup|@onboarding"
# Run everything except backup tests
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@backup" --mochaOpts.invertLocal vs staging (CI): the app merge gate uses BACKEND=local. Android greps capability tags (@settings, @send, @boost, …). iOS Mini greps @ios_gate. Staging shards grep dedicated *_staging tags, plus iOS-only @ios_nightly for UI that Android still runs on local:
| Staging grep | Specs |
|---|---|
@pubky_staging |
Public-payments + pubky-profile (@pubky / @paykit / @pubky_profile kept for other greps) |
@ios_nightly |
iOS-only shard for everything off Mini (@settings, @onboarding, @backup, @receive, @onchain_1/_2, @send_1, @multi_address_1, …). Does not queue the Mini. Local-LND specs (@send_3, @multi_address_4) stay on @ios_gate. |
@hardware_wallet |
Android staging only — do not add @hardware_wallet_staging (iOS Mini greps @ios_gate on this describe) |
Bare @staging may still be present next to the *_staging tags. Migration (@migration_*) is a separate nightly / dispatch / release-* PR workflow. See AGENTS.md for the full matrix.
Appium setup for a probe: wipe, onboard, then leave a known wallet on the device. Lives in test/qa-fixtures/ so a normal npm run e2e:* / CI run does not pick it up.
# BACKEND must match the AUT
BACKEND=regtest ./scripts/qa-fixture.sh android empty
BACKEND=regtest ./scripts/qa-fixture.sh ios full| Kind | Wallet |
|---|---|
empty |
onboard only — no funds, no profile |
onchain |
savings |
spending |
savings + spending |
pubky |
Paykit UI + profile, no funds, no contacts |
full |
savings + spending + Paykit UI + profile |
Optional: QA_FIXTURE_ONCHAIN_SATS, QA_FIXTURE_SPENDING_SATS, QA_FIXTURE_PROFILE_NAME.
Writes artifacts/qa-fixture.json and, with a profile, artifacts/qa-fixture.pubky. After it finishes, overlay the PR build (adb install -r / sim install — do not uninstall) and start from TotalBalance-primary.
For fixed-price Paykit requests that the app Request UI cannot create, use the standalone fixture sender. It links a separate issuer to either fixture and supports custom assets, amounts, and conversion rates without rebuilding the apps.
iOS: the script pins SIMULATOR_UDID to the booted simulator (SIMULATOR_NAME, default iPhone 17). Appium auto can attach to a physical device; do not leave that unset.
These helper scripts wrap the regular npm run e2e:* commands and add CI-friendly extras such as log capture and artifact collection. You can also run them locally when debugging.
The Android script will:
- Clear and capture
adb logcatoutput into./artifacts/logcat.txt. - Reverse the regtest port (
60001) for local backend. - Run the Android E2E tests.
- Forward any arguments directly to Mocha/WebdriverIO.
Usage examples:
# Run Android tests against the pinned local backend
./scripts/local-backend run ./ci_run_android.sh
# Run all Android tests with regtest backend (for apps built with BACKEND=regtest)
BACKEND=regtest ./ci_run_android.sh
# Run only @backup tests
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@backup"
# Run migration tests (typically need regtest backend for RN app)
BACKEND=regtest ./ci_run_android.sh --mochaOpts.grep "@migration"
# Run backup OR onboarding OR onchain tests
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@backup|@onboarding|@onchain"
# Run everything except @backup
./scripts/local-backend run ./ci_run_android.sh --mochaOpts.grep "@backup" --mochaOpts.invert
# Run a specific spec file
./scripts/local-backend run ./ci_run_android.sh --spec ./test/specs/onboarding.e2e.tsThe iOS helper mirrors the Android workflow but tailors it for the Apple Simulator:
- Ensures a simulator is booted (boots an
iPhone 17*fallback if none is running). - Captures Bitkit-specific
log streamoutput to./artifacts/simulator.log, restarting automatically if the simulator restarts or the keychain is reset. - Cleans up the background log task when the script exits.
- Passes any extra flags straight through to WebdriverIO/Mocha.
Usage examples:
# Run all iOS tests with local backend (default)
./ci_run_ios.sh
# Run all iOS tests with regtest backend
BACKEND=regtest ./ci_run_ios.sh
# Run only @onboarding-tagged tests
./ci_run_ios.sh --mochaOpts.grep "@onboarding"
# Run a specific spec file
./ci_run_ios.sh --spec ./test/specs/onboarding.e2e.ts- Use
elementById()andtap()helpers to write cross-platform tests. - Use
confirmInputOnKeyboard()to handle keyboard actions across Android/iOS. - Tests are designed to work identically on both platforms where possible.
- To debug, add
console.info()or enablewdiodebug logs. - Use
ciIt()instead ofit()on CI to skip already-passing tests in retries. - In app-repo CI, E2E typically runs in three attempts with
continue-on-error: true. If attempt 3 fails, it implies the same tests failed in attempts 1 and 2 (only failures are re-run), so check step logs/artifacts even if the job is green.
Bridge scenarios are included in the USDT fixture. Run
./scripts/usdt-fixture bridge-smoke before authoring UI tests. After the app
creates a deposit address, ./scripts/usdt-fixture orchestra deposit ADDRESS polygon 3.5 creates a held external deposit; orchestra advance ID completed
credits the local Arbitrum wallet. Outgoing scenarios use the app's real source
transaction. See bridge controls for helpers,
refunds, errors and the simulation boundary.