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.

Note

DappDriver is in active development, so all APIs are subject to change.

Install

DappDriver is available on npm:

yarn add @assert-equals/dappdriver

Get Started

Download a Wallet

First, install MetaMask, MetaMask Flask, Rainbow or Zerion:

npx dappdriver -w metamask

MetaMask Flask

npx dappdriver -w metamask-flask

Rainbow

DappDriver requires a personal access token to call Github’s API over HTTPS to download Rainbow from GitHub's artifact repository. You can configure the token through the GITHUB_TOKEN environment variable:

GITHUB_TOKEN=token npx dappdriver -w rainbow

Zerion

npx dappdriver -w zerion

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().clickAndOpensInWindow<Connect>(Connect);
  }
}

Write Your First Test

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

import { CHROME, DappDriver, METAMASK, PLAYWRIGHT, BrowserOptions } from '@assert-equals/dappdriver';
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:

yarn 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!