stellar-wallet-mock
What
A Playwright testing library that mocks the Freighter wallet browser extension, letting you run headless E2E tests against Stellar/Soroban dApps without a real wallet extension. No browser extension needed. No manual wallet interaction. Works with any dApp that uses @stellar/freighter-api — zero dApp code changes required. An npm package is coming shortly — for now, install directly from GitHub.
Zero dApp Code Changes
Works transparently with any dApp using @stellar/freighter-api.
Real Transaction Signing
Uses your Stellar secret key to sign actual transactions via ed25519.
Soroban Auth Support
Handles signAuthEntry() for smart contract authorization automatically.
CI/CD Ready
Works in headless environments like GitHub Actions with no extra setup.
Why
Testing Stellar dApps end-to-end traditionally requires a real browser wallet extension, manual clicks through approval dialogs, and often test-specific code paths in your dApp. stellar-wallet-mock eliminates all of that by intercepting the window.postMessage protocol between your dApp and the Freighter wallet extension.
The goal is to automate your frontend tests — verify that your dApp connects to wallets, reads contract state, and submits transactions correctly, all without manual interaction.
Compatibility
Intercepting postMessage is enough for dApps that use @stellar/freighter-api directly. But popular frameworks like Scaffold Stellar and @creit-tech/stellar-wallets-kit also check localStorage on page load to restore previous wallet connections. If those keys are missing, the dApp shows a “Connect Wallet” modal — which hangs headless tests because there's no user to click it.
To handle this, the mock pre-seeds localStorage with the keys these libraries expect (e.g. @StellarWalletsKit/activeAddress, walletId, walletAddress), so the dApp boots directly into a connected state. See localStorage Pre-Seeding in How It Works for the full list of keys.
Current Limitations
- Freighter only — currently only mocks the Freighter wallet. Other Stellar wallets (xBull, Albedo, Lobstr, etc.) use different communication protocols and are not yet supported. Support for additional wallets is planned for future releases.
- Chromium only — Playwright's
page.exposeFunction()is used for signing, which works best with Chromium-based browsers. - No multi-account support — a single secret key is used per page. To test multi-account flows, use separate pages or fixtures.