Setup with Cypress - Synpress Docs

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

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)
    },
  },
})

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('/')
})

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:

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:

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

Run the tests:

npx cypress run --browser chrome --headed

This will execute your tests using Cypress with Synpress integration.

Next Steps

Explore the API documentation for detailed Synpress functionalities
Check out example projects in the Synpress GitHub repository
Join our Discord community for support and best practices

​Prerequisites

​Installation

​Setup

​Writing Tests

​Running Tests

​Next Steps