This guide provides a quick setup process for Playwright with Synpress to automate tests for Web3 dapps. Note that this is a basic configuration, and Synpress offers many more advanced functions and features for comprehensive testing.

​
Prerequisites

  • Node.js v18+
  • Playwright and TypeScript knowledge

​
Installation

  1. Install Playwright and its dependencies:

    npm init playwright@latest

    Follow the prompts to complete the installation.

  2. Install Synpress as a dev dependency:

    npm install --save-dev @synthetixio/synpress

​
Setup

  1. Create or update your Playwright configuration file (e.g., playwright.config.ts):

    // Import necessary Playwright and Synpress modules
import { defineConfig, devices } from '@playwright/test'

// Define Playwright configuration
export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    // Set base URL for tests
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
  // Additional Synpress-specific configuration can be added here
})

  2. Create a basic wallet setup file (e.g., wallet-setup/basic.setup.ts):

    // Import necessary Synpress modules
import { defineWalletSetup } from '@synthetixio/synpress'
import { MetaMask } from '@synthetixio/synpress/playwright'

// Define a test seed phrase and password
const SEED_PHRASE = 'test test test test test test test test test test test junk'
const PASSWORD = 'Tester@1234'

// Define the basic wallet setup
export default defineWalletSetup(PASSWORD, async (context, walletPage) => {
  // Create a new MetaMask instance
  const metamask = new MetaMask(context, walletPage, PASSWORD)

  // Import the wallet using the seed phrase
  await metamask.importWallet(SEED_PHRASE)

  // Additional setup steps can be added here, such as:
  // - Adding custom networks
  // - Importing tokens
  // - Setting up specific account states
})

  3. Create a test file (e.g., tests/example.spec.ts):

    // Import necessary Synpress modules and setup
import { testWithSynpress } from '@synthetixio/synpress'
import { MetaMask, metaMaskFixtures } from '@synthetixio/synpress/playwright'
import basicSetup from '../wallet-setup/basic.setup'

// Create a test instance with Synpress and MetaMask fixtures
const test = testWithSynpress(metaMaskFixtures(basicSetup))

// Extract expect function from test
const { expect } = test

// Define a basic test case
test('should connect wallet to the MetaMask Test Dapp', async ({
  context,
  page,
  metamaskPage,
  extensionId,
}) => {
  // Create a new MetaMask instance
  const metamask = new MetaMask(
    context,
    metamaskPage,
    basicSetup.walletPassword,
    extensionId
  )

  // Navigate to the homepage
  await page.goto('/')

  // Click the connect button
  await page.locator('#connectButton').click()

  // Connect MetaMask to the dapp
  await metamask.connectToDapp()

  // Verify the connected account address
  await expect(page.locator('#accounts')).toHaveText(
    '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 Playwright tests with Synpress:

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

  2. Build wallet cache:

    npx synpress

  3. Run the tests:

    npx playwright test

This will execute your tests using Playwright with Synpress integration.

​
Next Steps