End-to-End (E2E) testing is a crucial part of ensuring an application works flawlessly from start to finish. E2E testing ensures that every component of your application interacts seamlessly, providing the functionality, security, and trust users expect. 

E2E testing is essential in web3 for several reasons. User Experience: helps identify and fix issues that could impact the user experience. Security: uncovers security vulnerabilities. Integration: resolves integration problems between various components of a Dapp.

Using E2E testing, a developer can be confident that all parts of an application – the frontend, backend, database, and any other service linked to it – work as expected when a user interacts with them. 

E2E testing in the Cosmos Ecosystem

Historically, it’s been challenging to find proper tools and frameworks to perform E2E testing in the Cosmos ecosystem. While some testing tools have existed, none have been able to ensure the seamless cohesion of a blockchain, application, and wallet.

Recently, the Agoric Systems team has made headway in this area. In building our multi-chain orchestration platform, our product and engineers have contributed to the Cosmos ecosystem by contributing to and sharing tools that simplify application development. One notable tool is the Synpress testing framework, an end-to-end testing framework that enables application testing with the Keplr Wallet.

Developers can now perform browser based testing to simulate real world user interactions to ensure that their applications successfully communicate with both the blockchain and the wallet.

Introducing the agoric/synpress Testing Framework

Agoric/synpress is a robust E2E testing framework designed specifically for applications using the Keplr wallet. It is based on Cypress, a popular JavaScript-based testing framework, and integrates it with Keplr for seamless interaction with blockchain networks during tests. It is a fork of the Synpress testing framework by Synthetix, adding features that make it an ideal choice for Cosmos SDK developers:

Keplr Integration: Agoric/synpress provides enhanced support for the Keplr wallet, a major wallet used with Cosmos SDK. It enables smooth interaction between the testing environment and the Keplr wallet, ensuring that wallet-related functionalities such as transaction signing, account management, and network switching are thoroughly tested. This integration ensures that developers can simulate real user interactions with the Keplr wallet, leading to more reliable and secure Dapps.

Comprehensive Dapp UI Testing: Agoric/synpress includes all the tools and interactions required for in-depth testing of an application’s user interface. This means you can test the complete user journey, from connecting the wallet and performing transactions to interacting with different Dapp features. The framework comes with pre-built commands and utilities that simplify the testing process.

Agoric/synpress is used by Agoric Systems to test the working of all applications we create. The Inter Protocol application and its sub-modules are continuously tested using agoric/synpress to ensure that all parts of the application are always working smoothly.

Getting started with Synpress

Prerequisites

Before diving into E2E testing with Synpress, make sure you have the following:

  • Node.js and npm

  • A Cosmos SDK-based blockchain network (e.g., Agoric, Osmosis)

  • Keplr wallet extension

Installation and Configuration

To get started with agoric/synpress, first install the @agoric/synpress framework as a dev dependency in your project:

npm install --save-dev @agoric/synpress

Next, add a directory for tests with a structure like so:

project_dir
└── src
└── tests
    └── e2e
        └── .eslintrc.js
        └── support.js
        └── specs
            └── example-spec.js

creating two more files:

  1. .eslintrc.js

const path = require('path');
const synpressPath = path.join(
  process.cwd(),
  '/node_modules/@agoric/synpress',
);
module.exports = {
  extends: `${synpressPath}/.eslintrc.js`,
};

  1. support.js

import '@agoric/synpress/support/index';

This should give us the basic boilerplate to get started with writing tests.

Writing E2E Tests with Synpress

Structure of an E2E Test

An E2E test typically involves setting up the test environment, interacting with the application through the browser, and verifying the expected outcomes.

Writing Your First Test

Create a new test file in the tests directory and write a test using the commands given by agoric/synpress:

describe('Keplr', () => {

	it(`should setup a Keplr wallet`, () => {
      cy.setupWallet({
	secretWords: "pineapple cow fat water ....."
});
      cy.visit('/');
    });    

	it(`should accept connection with wallet`, () => {
      cy.contains('Connect Wallet').click();
      cy.acceptAccess();
    });    

    it(`should confirm make an offer transaction`, () => {
      cy.contains('Make an Offer').click();
      cy.confirmTransaction();
    });
});

The above test represents a basic scenario where the user creates a new wallet, connects the wallet to the Dapp, and then performs a transaction. While this is the most basic of cases, agoric/synpress can handle more complex interactions such as:

  • Handling multiple accounts and transactions

  • Retrieving account balance and address

  • Simulating different network conditions

Running the Tests

Executing Tests Locally

Run your tests locally with the following command:

EXTENSION=keplr synpress run

Best Practices for UI Testing

  • Keep Tests Independent: Each test should run independently without relying on the state left by previous tests.

  • Use Clear Assertions: Make sure your assertions are specific and provide clear feedback.

  • Handle Asynchronous Operations: Properly handle promises and asynchronous code to avoid flaky tests.

Continuous Integration and Testing in CI/CD Pipelines

Agoric/synpress also allows you to easily Integrate your E2E tests into your CI/CD pipeline to ensure consistent testing across different environments. Popular CI tools like GitHub Actions, GitLab CI, or Jenkins can be configured to run these tests automatically. Agoric/synpress lends itself well to being integrated into a CI pipeline: the tests can be containerized to ensure consistent and reliable behavior on a CI runner. A quick example can be found in the agoric/synpress repository. 

Resources and Further Reading

Stay on the cutting edge of web3 development. Subscribe to the Agoric Developer Newsletter for more on chain abstraction, orchestration, and multi-chain design. 

Join us to learn more about orchestration in person around the world, or online at a Welcome to Agoric session!

Want to be the first to try the Orchestration API? Complete the Getting Started tutorial and let us know about your experience on Discord.  Our DevRels are happy to help!