https://github.com/assert-equals/dappdriver
🕹️ DappDriver is an e2e testing framework designed for testing decentralized applications (dApps) using MetaMask, Rainbow or Zerion
https://github.com/assert-equals/dappdriver
automation blockchain browser chrome dapp dapp-developers e2e-tests end-to-end-testing ethereum extension metamask playwright rainbow selenium testing web3 webdriver zerion
Last synced: about 2 months ago
JSON representation
🕹️ DappDriver is an e2e testing framework designed for testing decentralized applications (dApps) using MetaMask, Rainbow or Zerion
- Host: GitHub
- URL: https://github.com/assert-equals/dappdriver
- Owner: assert-equals
- License: mit
- Created: 2024-03-02T15:35:37.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-05-05T17:11:55.000Z (about 2 months ago)
- Last Synced: 2025-05-05T17:21:29.581Z (about 2 months ago)
- Topics: automation, blockchain, browser, chrome, dapp, dapp-developers, e2e-tests, end-to-end-testing, ethereum, extension, metamask, playwright, rainbow, selenium, testing, web3, webdriver, zerion
- Language: TypeScript
- Homepage: https://dappdriver.xyz/
- Size: 2.55 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
DappDriver
Automated tests for dApps
[DappDriver](https://github.com/assert-equals/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](https://playwright.dev/) and [Selenium WebDriver](https://www.selenium.dev/).
DappDriver loads [MetaMask](https://metamask.io/), [MetaMask Flask](https://metamask.io/flask/), [Rainbow](https://rainbow.me/) or [Zerion](https://zerion.io/) 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](https://www.npmjs.com/package/@assert-equals/dappdriver):
```shell
yarn add @assert-equals/dappdriver
```
## Get Started
**Download a Wallet**
First, install MetaMask, MetaMask Flask, Rainbow or Zerion:
```shell
npx dappdriver -w metamask
```
MetaMask Flask
Install MetaMask Flask:
```shell
npx dappdriver -w metamask-flask
```
Rainbow
DappDriver requires a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) to call Github’s API over HTTPS to download Rainbow from GitHub's artifact repository. You can configure the personal access token through the `GITHUB_TOKEN` environment variable by adding it to your profile (`~/.bash_profile`, `~/.zshrc`).
Configure the environment variable (`~/.bash_profile`, `~/.zshrc`):
```shell
export GITHUB_TOKEN='*****'
```
Install Rainbow:
```shell
npx dappdriver -w rainbow
```
Zerion
Install Zerion:
```shell
npx dappdriver -w zerion
```
**Add a Page Object**
Then, write your page object in `test/page/dapp.ts`:
```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 {
return await this.accountsLabel().getText();
}
async connect(): Promise {
return await this.connectButton().clickAndOpensInWindow(Connect);
}
}
```
**Write Your First Test**
Next, write your test in `test/spec/dapp.spec.ts`:
```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(
'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);
const actualAccount: string = await dapp.getAccounts();
const expectedAccount: string = '0xe18035bf8712672935fdb4e5e431b1a0183d2dfc';
expect(actualAccount).to.be.equal(expectedAccount);
});
});
```
**Run the Test**
Finally, run your tests:
```shell
yarn test
```
## Examples
If you learn best by example, check out our [example project](https://github.com/assert-equals/DappDriver-examples) to help you get going.
## Documentation
Read our [API documentation](https://assert-equals.github.io/DappDriver/).
## Support
Join our [community](https://github.com/assert-equals/DappDriver/discussions) and elevate your decentralized testing experience.
If you like DappDriver, [give us a star ⭐ on GitHub!](https://github.com/assert-equals/DappDriver)