This guide provides a streamlined setup process for integrating Cypress with Synpress to automate tests for Web3 dapps. While this covers the basic configuration, Synpress offers a wide range of advanced features for comprehensive testing.

Prerequisites

  • Node.js v18+
  • Basic knowledge of Cypress and TypeScript

Installation

Install Cypress and Synpress in your project:

npm install --save-dev cypress @synthetixio/synpress

Setup

  1. Create a Cypress configuration file (cypress.config.ts) in your project root:

    // Import necessary Cypress and Synpress modules
    import { configureSynpressForMetaMask } from '@synthetixio/synpress/cypress'
    import { defineConfig } from 'cypress'
    
    // Define Cypress configuration
    export default defineConfig({
      chromeWebSecurity: true,
      e2e: {
        baseUrl: 'http://localhost:9999',
        specPattern: 'test/cypress/**/*.cy.{js,jsx,ts,tsx}',
        supportFile: 'src/cypress/support/e2e.{js,jsx,ts,tsx}',
        testIsolation: false,
        async setupNodeEvents(on, config) {
          return configureSynpressForMetaMask(on, config)
        },
      },
    })
    
  2. Create a support file (src/cypress/support/e2e.ts):

    // Import Synpress commands for MetaMask
    import { synpressCommandsForMetaMask } from '@synthetixio/synpress/cypress/support'
    
    // Handle uncaught exceptions
    Cypress.on('uncaught:exception', () => {
      // returning false here prevents Cypress from failing the test
      return false
    })
    
    // Initialize Synpress commands
    synpressCommandsForMetaMask()
    
    // Visit the base URL before each test
    before(() => {
      cy.visit('/')
    })
    
  3. Update your tsconfig.json to include Cypress types:

    {
      "compilerOptions": {
        "types": ["cypress"],
        "esModuleInterop": true
      },
      "include": ["cypress.config.ts", "test", "src"],
      "files": ["environment.d.ts"]
    }
    

Writing Tests

Here’s an example of how to write tests using Cypress with Synpress:

  1. Create a test file (e.g., test/cypress/e2e/metamask.cy.ts):

    describe('MetaMask Integration', () => {
      it('should connect wallet and verify account', () => {
        // Click the connect button
        cy.get('#connectButton').click()
    
        // Connect MetaMask to the dApp
        cy.connectToDapp()
    
        // Verify the connected account address
        cy.get('#accounts').should(
          'have.text',
          '0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266'
        )
    
        // Additional test steps can be added here, such as:
        // - Sending transactions
        // - Interacting with smart contracts
        // - Testing dapp-specific functionality
      })
    })
    

Running Tests

To run your Cypress tests with Synpress:

  1. Start your local development server (if testing against a local app).

  2. Run the tests:

    npx cypress run --browser chrome --headed
    

This will execute your tests using Cypress with Synpress integration.

Next Steps