Migration Guide - v3 to v4

​

Key Changes and Improvements

1. Installation: The package name remains the same: @synthetixio/synpress.
2. Configuration (cypress.config.ts): The setup within your Cypress configuration file has changed. You now use configureSynpressForMetaMask (or configureSynpressForEthereumWalletMock) to integrate Synpress.
3. Support Files (support/e2e.ts): You now import specific command sets (synpressCommandsForMetaMask or synpressCommandsForEthereumWalletMock) instead of a global import.
4. Test Structure: The automatic page visit in before() hook, which was a recommended approach, is now replaced with test isolation set to false.
5. API Changes: Several Cypress commands have been renamed or removed for clarity and consistency. A detailed mapping is provided below.
6. Test Execution: You use the standard cypress run command, but headed mode is currently required on CI.
7. Wallet Setup Files: Synpress v4 introduces “wallet setup files” (*.setup.{ts,js,mjs}) to define how the wallet should be pre-configured (importing a seed phrase, adding networks, etc.).

​

Migration Steps

​

1. Update Dependencies

pnpm update cypress @synthetixio/synpress --latest
# OR
npm update cypress @synthetixio/synpress --latest
# OR
yarn upgrade cypress @synthetixio/synpress --latest

​

2. Update cypress.config.ts

// cypress.config.ts
import { defineConfig } from 'cypress';
import { configureSynpressForMetaMask } from '@synthetixio/synpress/cypress';

export default defineConfig({
  chromeWebSecurity: false, // Keep this if you had it before
  e2e: {
    baseUrl: 'http://localhost:9999', // Adjust if your base URL is different
    specPattern: 'test/cypress/**/*.cy.{js,jsx,ts,tsx}', // Adjust if your spec pattern is different
    supportFile: 'src/cypress/support/e2e.{js,jsx,ts,tsx}', // Adjust if needed
    testIsolation: false, // Important for reusing the cached browser context
    setupNodeEvents(on, config) {
      return configureSynpressForMetaMask(on, config);
    },
  },
});

​

3. Update Support File (src/cypress/support/e2e.ts)

// src/cypress/support/e2e.ts
import { synpressCommandsForMetaMask } from '@synthetixio/synpress/cypress/support';

// Optional: If you had custom error handling, keep it.
Cypress.on('uncaught:exception', () => {
  return false;
});

synpressCommandsForMetaMask();

// REMOVE the before() hook with cy.visit('/');

// src/cypress/support/e2e.ts
- import { synpressCommandsForMetaMask } from '@synthetixio/synpress/cypress/support';
+ import { synpressCommandsForEthereumWalletMock, mockEthereum } from '@synthetixio/synpress/cypress/support'

// Optional: If you had custom error handling, keep it.
Cypress.on('uncaught:exception', () => {
  return false;
});

- synpressCommandsForMetaMask();
+ synpressCommandsForEthereumWalletMock();
+ mockEthereum()

​

4. Update TypeScript Configuration (tsconfig.json)

// tsconfig.json
{
  "compilerOptions": {
    "types": ["cypress"],
    "esModuleInterop": true // Important for compatibility
  },
  "include": ["cypress.config.ts", "test", "src"],
  "files": ["environment.d.ts"]
}

​

5. Update Test Files

• Update Commands: Replace v3 commands with their v4 equivalents. See the “Detailed API Changes” section below for a comprehensive mapping.
• Example:
  Copy

  // Old v3 test
  describe('My Test Suite', () => {
    before(() => {
      cy.visit('/');
    });
  
    it('should connect to MetaMask', () => {
      cy.acceptMetamaskAccess(); // v3
      cy.get('#someElement').should('be.visible');
    });
  });
  
  // New v4 test
  describe('My Test Suite', () => {
    before(() => {
      cy.visit('/');
    });
  
    it('should connect to MetaMask', () => {
      cy.connectToDapp(); // v4
      cy.get('#someElement').should('be.visible');
    });
  });
  

​

6. Create Wallet Setup Files (New in v4)

• Create a Directory: By default, Synpress expects these files in test/wallet-setup. You can change this using the Synpress CLI.
• File Naming: Files must follow the pattern *.setup.{ts,js,mjs} (e.g., basic.setup.ts, connected.setup.ts).
• File Content: Use the defineWalletSetup function to define the setup steps.
  Copy

  // test/wallet-setup/basic.setup.ts
  import { defineWalletSetup } from '@synthetixio/synpress'
  import { MetaMask } from '@synthetixio/synpress/playwright'
  import 'dotenv/config';
  
  const SEED_PHRASE = process.env.SEED_PHRASE;
  const PASSWORD = process.env.WALLET_PASSWORD;
  
  export default defineWalletSetup(PASSWORD, async (context, walletPage) => {
    const extensionId = await getExtensionId(context, 'MetaMask');
    const metamask = new MetaMask(context, walletPage, PASSWORD);
  
    await metamask.importWallet(SEED_PHRASE);
  });
  
  

  This example imports a wallet using a seed phrase. You can customize this to:
  • Import from a private key.
  • Add custom networks.
  • Connect to a dapp (for a “pre-connected” state).
  • Change MetaMask settings.
  • …and anything else you can do within the MetaMask UI.

​

7. Build the Cache

npx synpress
# OR
pnpm run synpress # If you have a script named 'synpress' in your package.json

1. Find your *.setup.{ts,js,mjs} files.
2. Generate a unique hash for each setup function.
3. Launch a browser instance for each unique setup.
4. Execute the setup function (installing MetaMask, importing the wallet, etc.).
5. Save the browser context (the cache) to the .cache-synpress directory.

• --headless: Run the cache building process in headless mode (no browser window visible). Useful for local development to see what’s happening.
• --force: Force a rebuild of the cache, even if a cache with the same hash already exists. Use this if you’ve made changes to your setup file or if you suspect the cache is corrupted.
• --debug: Enables additional logging during the cache building, and preserves logs.
• [dir]: Specify a custom directory containing the wallet setup files (defaults to test/wallet-setup).

npx synpress --headless --force

​

8. Run Your Tests

npx cypress run --browser chrome --headed # Headed mode is required on CI

• Headed Mode on CI: Due to a MetaMask issue, you must run tests in headed mode on CI. Use a virtual display like xvfb-run. See the “Known Issues” page in the Synpress documentation.

​

Detailed API Changes