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, 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, Rainbow or Zerion:

npx dappdriver -w metamask

Installing 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

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

  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

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!