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';

export class Dapp extends PageObject {
  private accountsLabel: () => HTMLElement = () => new HTMLElement('#accounts');
  private connectButton: () => HTMLElement = () => new HTMLElement('#connectButton');
  constructor() {
    super('https://metamask.github.io/', 'E2E Test Dapp');
  }

  async getAccounts(): Promise<string> {
    return await this.accountsLabel().getText();
  }

  async connect(): Promise<Connect> {
    return await this.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', () => {
  let dapp: Dapp;
  const browserOptions: 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 = await DappDriver.create<Dapp>(
      'https://metamask.github.io/test-dapp/',
      PLAYWRIGHT,
      CHROME,
      Dapp,
      browserOptions
    );
  });

  afterEach(async () => {
    await DappDriver.dispose();
  });

  it('connects Account One to the dapp', async () => {
    const connectPopup: Connect = await dapp.connect();
    dapp = await connectPopup.accept<Dapp>(Dapp);
    const actualAccount: string = await dapp.getAccounts();
    const expectedAccount: 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!