Commit 18f1308

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

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](https://github.com/LavaMoat/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](https://discord.gg/XhZKSRGtWc).

* **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 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](/docs/guides/ci.md) for detailed instructions.

```yaml

# Example (GitHub Actions):

- name: Build cache

run: xvfb-run npx synpress

- name: Run E2E tests (headful)

run: xvfb-run npx playwright test

```