Skip to main content
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