DappDriver

Automated tests for dApps

DappDriver is a web testing framework designed for testing decentralized applications (dApps).

It's all about being flexible and user-friendly, DappDriver seamlessly integrates both Playwright and Selenium WebDriver.

DappDriver loads MetaMask, MetaMask Flask, Rainbow or Zerion into the browser session, empowering you to efficiently confirm blockchain transactions.

Read on to get started locally in a couple of minutes.

Install

DappDriver is available on npm. Install the core package alongside the wallet package you want to use:

npm install @assert-equals/dappdriver @assert-equals/dappdriver-metamask @assert-equals/dappdriver-wallet

Get Started

Add a Page Object

Then, write your page object in test/page/dapp.ts:

import{HTMLElement,PageObject}from'@assert-equals/dappdriver';import{Connect}from'@assert-equals/dappdriver-wallet';exportclassDappextendsPageObject{privateaccountsLabel: ()=>HTMLElement=()=>newHTMLElement('#accounts');privateconnectButton: ()=>HTMLElement=()=>newHTMLElement('#connectButton');constructor(){super('https://metamask.github.io/','E2E Test Dapp');}asyncgetAccounts(): Promise<string>{returnawaitthis.accountsLabel().getText();}asyncconnect(): Promise<Connect>{returnawaitthis.connectButton().clickAndSwitchToWindow<Connect>(Connect);}}

Write Your First Test

Next, write your test in test/spec/dapp.spec.ts:

Note

Your tests are written once and work with any supported wallet. To switch wallets, just change the wallet option in your browser configuration.

import{CHROME,DappDriver,PLAYWRIGHT,BrowserOptions}from'@assert-equals/dappdriver';import{metamask}from'@assert-equals/dappdriver-metamask';import{Connect}from'@assert-equals/dappdriver-wallet';import{expect}from'chai';import{Dapp}from'../page/dapp';describe('E2E Test Dapp',()=>{letdapp: Dapp;constbrowserOptions: BrowserOptions={extension: {wallet: metamask,seed: 'phrase upgrade clock rough situate wedding elder clever doctor stamp excess tent'// MetaMask test seed https://github.com/MetaMask/metamask-extension/blob/v12.7.1/test/e2e/seeder/ganache.ts}};beforeEach(async()=>{dapp=awaitDappDriver.create<Dapp>('https://metamask.github.io/test-dapp/',PLAYWRIGHT,CHROME,Dapp,browserOptions);});afterEach(async()=>{awaitDappDriver.dispose();});it('connects Account One to the dapp',async()=>{constconnectPopup: Connect=awaitdapp.connect();dapp=awaitconnectPopup.accept<Dapp>(Dapp);constactualAccount: string=awaitdapp.getAccounts();constexpectedAccount: string='0xe18035bf8712672935fdb4e5e431b1a0183d2dfc';expect(actualAccount).to.be.equal(expectedAccount);});});

Run the Test

Finally, run your tests:

npm test

Examples

If you learn best by example, check out our example project to help you get going.

Documentation

Read our API documentation.

Support

Join our community and elevate your decentralized testing experience.

If you like DappDriver, give us a star ⭐ on GitHub!