Integrating Synpress into Playwright is quite straightforward.

Let’s digest a simple test step by step:

example.spec.ts
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))

const { expect } = test

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

​
Import

First, you need to import the necessary modules and setup:

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

const test = testWithSynpress(metaMaskFixtures(basicSetup))

The testWithSynpress function takes the MetaMask fixtures as an argument, which includes your wallet setup configuration. This setup defines how your wallet should be configured before each test.

​
Define your test

Now that you have your test instance configured, you can write your test:

const { expect } = test

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

The test uses several fixtures provided by Synpress:

  • context: Playwright browser context
  • page: The page where your dApp is running
  • metamaskPage: The MetaMask extension page
  • extensionId: The ID of the MetaMask extension

You can learn more about them in the Built-in Fixtures section.

To interact with MetaMask, create an instance of the MetaMask class. For detailed information about the constructor and available methods, see the MetaMask API reference.

If you’re using the same wallet setup in multiple test files, you can speed up the process of writing your tests by defining a custom fixture that will create the MetaMask instance for you.

​
Running Tests

To run your tests:

npx playwright test

Currently, Synpress runs tests in headed mode by default (like playwright test --headed). To run in headless mode, set the HEADLESS environment variable:

HEADLESS=true npx playwright test

This default behavior will be changed in a future release to match Playwright’s standard behavior.

Synpress supports all Playwright features, including: