​
Playwright

Synpress and Playwright generally work well together. However, there are a couple of known limitations:

​
Blank MetaMask Previews in Traces

When using Playwright’s UI mode or the HTML reporter, previews of MetaMask tabs and popups within the traces will appear blank. This is a consequence of MetaMask’s LavaMoat security policy, which restricts access to the extension’s content in these contexts. Unfortunately, there’s no direct workaround within Synpress itself. Workarounds (if previews are essential for debugging):
  • Use Pre-built MetaMask without LavaMoat: We have prepared a build of MetaMask without LavaMoat that you can use: https://github.com/synpress-io/metamask-extension/releases
  • Build MetaMask from Source: You can build a custom version of the MetaMask extension with LavaMoat disabled. This is not recommended for general use or production, only for local debugging. If you need assistance with this, reach out to the Synpress community on Discord.
  • Use Headful Mode on CI and locally: While not ideal for CI, running tests in headed mode (playwright test or HEADLESS=false playwright test) will allow you to observe the MetaMask UI directly during test execution, which can help with debugging.

​
MetaMask

​
Headless Mode Limitations on CI

MetaMask has known compatibility issues with running in headless mode on certain CI providers, including GitHub Actions. This is due to a bug within MetaMask itself, not within Synpress. Workaround:
  • Run in Headful Mode on CI: The recommended solution is to run your Synpress tests in headed mode on CI. This typically requires configuring your CI environment to use a virtual display (e.g., xvfb-run on Linux). See the CI documentation for detailed instructions. 
    # Example (GitHub Actions):
- name: Build cache
  run: xvfb-run npx synpress

- name: Run E2E tests (headful)
  run: xvfb-run npx playwright test
Note: We are actively monitoring for updates from MetaMask that might resolve this headless mode limitation.

​
Windows

Currently, Synpress does not officially support Windows. We recommend using WSL (Windows Subsystem for Linux) as a workaround.