Comment on page

Testing with Web3.js + Cypress

A step-by-step guide for creating an E2E automation project and using your private StealthTest environment.
Before you begin, please make sure to create your StealthTest environment and have access to the RPC URL and chain ID.
This document is intended to act as a guide on how to implement a strategy with Web3.js , Cypress, and Synpress for automation projects. It is not an out-of-the-box implementation of the frameworks. These frameworks change weekly and everyone is different in regards to how they approach writing tests.
For more information on Web3.js please access the documentation here: web3.js documentation

Framework Overview

There are multiple tools available for use with web3.js that, when used together, create an excellent framework for interacting with dapps and ensuring successful end-to-end (E2E) tests. Some of the tools we will be using are :
Synpress is E2E testing framework based on Cypress and Playwright with support for MetaMask.”
Synpress is an excellent tool for interacting with Metamask during automated tests. It effectively ensures compatibility between the latest version of Metamask and the framework, thereby guaranteeing stable and reliable test results.
“Cypress is a very popular automation framework that can be used to test anything that runs in a browser.”
Cypress is highly focused on E2E testing, as well as Component Testing, and is widely regarded as the standard for all E2E testing nowadays. It boasts impressive speed and power, offering a comprehensive set of tools to build resilient automation frameworks.


Now that we have examined some of the frameworks and tools at our disposal, let's discuss the possibilities that arise when we utilize them collectively.
Cypress will be the primary framework we'll be using, coupled with Synpress and web3.js. Cypress will be used to open a browser and act as if it is a user interacting with the Daap. Then, a transaction will be triggered using a Metamask wallet. The triggering of the Metamask wallet will be facilitated by a helper provided by Synpress. Subsequently, the transaction will be confirmed with the wallet, and we will utilize web3.js to directly validate with the blockchain that the transaction was successful.
At this point, you might be thinking:
  • “Well, can’t I just trust my Dapp, to ensure the transaction was successful?”
In web3, blockchains function as independent services or databases that manage themselves. While you can interact with a blockchain, particularly testnets, you cannot directly control their state to guarantee the proper functioning of your Daap.
This is where StealthTest comes to the rescue.
With StealthTest, you can execute tests in isolation without concerns about exposing transactions, smart contracts, and other sensitive data when testing on a Testnet.
StealthTest also offers a faucet that provides unlimited tokens for each running environment. This enables you to repeatedly simulate transactions and different scenarios without concerns about costs and waiting time for testing.

Getting Started

1. Node.js and npm installed (
2. Familiarity with Ethereum, smart contracts, and basic JavaScript.
Step 1: Set Up Your Project:
1. Create a new directory for your project and navigate to it in your terminal.
2. Run npm init to initialize your project and follow the prompts.
3. Install the required dependencies:
npm install cypress web3 @synthetixio/[email protected]
Step 2: Configure Synpress:
1. Create a synpress.config.js file in your project directory.
2. Configure Synpress by specifying the Ethereum network you want to use for testing. You can also set up a local blockchain for testing using Ganache.
module.exports = {
networks: {
development: {
provider: new Web3.providers.HttpProvider('http://localhost:8545'),
accounts: {
mnemonic: 'your mnemonic here', // Use a mnemonic for your test accounts
Step 3: Write Cypress Tests:
1. Create a cypress directory in your project root.
2. Inside the cypress directory, create a integration folder to hold your test files.
3. Write Cypress tests using Web3.js and Synpress within your test files.
  • For example, create a test file named sample-test.js:
describe("connect wallet spec", () => {
beforeEach(() => {
afterEach(() => {
it("should connect wallet with success", () => {
it("import private key and connect wallet using imported metamask account", () => {
// Perform interactions and assertions
//Get current balance of wallet
web3.eth.getBalance(address, (err, wei) => { balance = web3.utils.fromWei(wei, 'ether') }).then(console.log)
This is just one of the ways you can confirm the balance from the blockchain. You can make this test cleaner by putting it in its own file and calling it from the test, vs. having all the code within the spec file for Cypress. This will allow you to keep the web3.js code and Cypress/Synpress logic separated and more maintainable.
Step 4: Run Your Tests:
1. Ensure you have the SteathTest environment running or make sure you're connected to the desired Ethereum network.
2. In your terminal, run the following command to start the Cypress test runner:
npx cypress open
3. Click on the sample-test.js file in the Cypress test runner to run your test.
After the test has finished running, you now have a way to validate not only from your web dapp that things are working visually, but you can confirm it directly with the blockchain.