GuardianTest is an open-source, end-to-end testing framework for web3 developers building on EVM-compatible chains.

Installation

Dependencies

Installing Node.js

• Check if you already have Node installed by opening a terminal or command prompt instance and executing node -v. You should see a version number in the return.
• If you do not have Node already installed, go to Node.js and select the version associated with your operating system.

Installing Foundry

• Check if you already have Anvil installed through Foundry by opening a terminal or command prompt instance and executing anvil -V. You should see a version number in the return. If you do not, follow one of the guides below.

Mac, Linux, and Windows

• Install using Foundryup
• Building from source

Docker

• Installation for Docker

CI

• Installation for CI

Installing GuardianTest

You can install GuardianTest using either npm or yarn:

npm

npm install --save-dev @guardianui/test

yarn

yarn add -D @guardianui/test

Installing Playwright Browsers

You will need to have the latest Playwright browser drivers installed.

npx playwright install

Configuration

Playwright

At your repo's top-level directory create a file called playwright.config.ts. You can find a default configuration in our GuardianTest Configuration Guide

If you already are using Playwright and already have a playwright.config.ts:

• Add /.*gui.(js|ts|mjs)/ to the testMatch entry to make sure Playwright recognizes our tests
  • If you do not have a testMatch entry in the config, add one like shown in the example below
  • If you have existing Playwright tests that are either named with the testName.spec.ts or testName.test.ts naming conventions make the following your testMatch entry: [/.*gui\.(js|ts|mjs)/, /.*(spec|test)\.(js|ts|mjs)/]
• Set fullyParallel to false
• Set workers to 1

env

Create another file called .env in your repo's top-level directory, or add the following to your existing .env file if you already have one. Comment out whichever line you do not use with a # at the start.

# Must fill in one of these API keys; only need one
GUARDIAN_UI_INFURA_API_KEY=
GUARDIAN_UI_ALCHEMY_API_KEY=
GUARDIAN_UI_CHAINSTACK_API_KEY=

package.json

To be able to run tests, add the following to your app's package.json scripts section:

"test:gui": "npx playwright test --project=chromium --headed"

Writing Your First Test

Follow our guide to write your first test

What GuardianTest enables

• Engage with local deployments, staging deployments, OR live production
• Perform tests on Ethereum, Polygon, Arbitrum, or Optimism (more coming soon)
• Pin tests to any block
• Interact with a site using a wallet
• Mock ERC20 balances and allowances
• Validate target contract addresses from app interactions
• Perform any other actions or validation Playwright offers

Why it's good

• Does not rely on MetaMask or any other specific wallet where the brittleness of the tests is caused by changes from the wallet provider
• Creates a closer to production testing environment
  • No modified WAGMI connector
  • Looks like mainnet to the site
• Enables easy mocking of ERC20 balances and allowances
• Enables mocking of any other contract state
• Enables developers to verify wallet interactions
• Enables developers to test app behavior through a transaction completing

How it works

• Spins up an Anvil fork of the desired network at the time of test run
• Uses Playwright to run browser interactions and engage with the site
• Injects a wallet to the browser that's connected to the Anvil fork
• Checks eth_sendTransaction and eth_sendRawTransaction RPC requests when instructed to via gui.validateContractInteraction

Documentation

For full documentation and examples, visit the GuardianTest Docs.

Community

Check out the following places for more GuardianUI-related content:

• Join the discussions on GitHub
• Follow @guardian_ui on Twitter for project updates
• Share your project/organization that's using GuardianTest
• Join the GuardianUI discord to connect with other devs and the GuardianUI team.
• Learn more about additional GuardianUI products and features by visiting our website.

Contributing

If you're interested in contributing, please read the contributing docs before submitting a pull request.

Resources

• Documentation
• Contributing guide
• GuardianUI website