# Synpress: end to end testing for web3 dapps with MetaMask

> Synpress is a TypeScript test library built on Cypress and Playwright that automates wallet interactions, caches the browser setup so the wallet is configured once, and can start a local Anvil node. It suits dapp teams whose end to end suite is otherwise stuck on manual wallet steps.

**synpress/synpress** — Synpress is e2e testing framework based on Cypress.io and playwright with support for metamask.

- Repository: https://github.com/synpress/synpress
- Website: https://synpress.io
- Stars: 891 · Forks: 216
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/synpress-synpress

## The wallet is the slow part of a dapp test suite

The problem Synpress addresses is specific to web3 applications. A dapp end to end test has to interact with a wallet, and the wallet is a browser extension, which means every test that needs a connected account has to go through an extension popup, approve a connection, handle a password prompt, and possibly sign a message. None of that is what you are testing, and all of it is slow and flaky. Synpress is a powerful and developer-friendly E2E testing library for Web3 dapps, built on top of Cypress and Playwright, and it simplifies testing interactions with wallets like MetaMask and other blockchain-specific operations. The stated design goal is that the core is wallet and blockchain agnostic, offering flexibility for future integrations and broader dApp support, and the MetaMask integration is described as deep, covering the common dApp interactions. So the scope is not a general browser automation library with a wallet plugin, it is a library whose first class citizen is the wallet, built on top of an existing framework rather than replacing it.

## One-time setup and caching is the feature that changes the runtime

The mechanism that makes Synpress usable at scale is the one-time browser setup and caching. You define your dApps wallet setup once, and Synpress caches the browser state, and the documentation is direct that this dramatically speeds up test execution and makes the full potential of Playwright and Cypress available, including parallel testing. That last clause is the important one. Wallet extension setup is stateful and slow, and a test suite that has to redo it per test, or per worker, is a suite that cannot be parallelised. Caching the browser profile with the wallet already installed, connected and signed in turns that into a fixture. The feature list also claims blazing fast performance, describing Synpress as optimised for speed and rivalling native Web2 testing framework performance, and given the mechanism that claim is at least plausible, since the expensive part is removed rather than optimised. The same idea appears in the repository layout, where the build scripts have separate cache build targets per wallet, one for metamask and one for phantom, which tells you the cache is a per-wallet artefact that has to be produced for the wallet you are testing with.

## Either framework, and the reason to pick one first

The first feature on the list is that you can use either Playwright or Cypress as your testing framework, leveraging all their existing features with Synpress. That is a deliberate choice, and it has a consequence you should confront before writing tests. Synpress is a layer over the framework, not a replacement for it, so the two are not interchangeable in practice. A test written for one uses that framework's runner, its fixtures, its page object model, its reporting. If your project already has a Cypress suite, adding Synpress means your new dapp tests look like your existing ones. If your project has moved to Playwright, the same is true in reverse. The upside of supporting both is that Synpress is not asking you to migrate, and the downside is that the documentation and the examples are per framework, so you should decide which one you are using before you read the API reference rather than after. The debugging story is framed the same way, with detailed error handling combined with the debugging tools of Playwright and Cypress, so the underlying framework's diagnostics are what you will actually be reading in a failure.

## A local chain in one line changes what you can assert

The Anvil support is listed as easily spinning up a local Anvil node with just one line of code for fast and isolated testing, and it is the feature that most changes what a dapp test can assert. Most dapp tests against a public test network are slow and non-deterministic, because the state of the chain is whatever it happens to be, and a test that depends on a token balance or a position existing is a test that fails for reasons that have nothing to do with your code. Against a local Anvil node you control the state, so you can set up exactly the condition the test needs and then assert on the result without waiting for a network. The example directory in the repository reflects this split, with a metamask example and an ethereum-wallet-mock example, which suggests two levels of setup, a real wallet extension driving a real browser and a mock wallet for faster tests. The wallet mock is presumably how the suite stays fast, since a real extension is the slow part, and the build scripts run separate headful and headless Playwright runs per wallet, so the same suite is exercised both ways.

## A monorepo with a release process and per-wallet packages

The repository is a pnpm workspace with turbo driving the builds, and the structure tells you how the project is organised. There is a packages directory, a wallets directory, an examples directory, a release directory, a docs directory, a support-bot directory and a shared turbo.json, and the root package.json is private with the build and test scripts delegating to turbo. Two details in the scripts are worth noticing. There is a preinstall script that runs only-allow for pnpm, which fails the install if you use npm or yarn, and that is a common source of confusion for a contributor who clones the repository and reaches for the wrong package manager. And the test scripts filter by package, so you can run the Playwright tests for a single wallet, headful or headless, without running the whole matrix. The wallet specific build scripts are the clearest signal that the wallet is a plugin point rather than a hardcoded dependency, and the repository also carries a pnpm workspace file, a biome configuration for formatting and linting, husky for git hooks, a changesets directory for the release notes, a vercel.json for the documentation site, a DEPLOYMENT.md and a funding.json. The licence is MIT with the terms in a LICENSE.md file.

## The namespace, the branch and the release gap

Installing it is a single pnpm command, and the package scope is the part to note:

```bash
pnpm add -D @synthetixio/synpress@latest
```

Two naming details will confuse you if you follow a link. The npm package is published under the synthetixio scope, and the installation instruction reflects that, while the repository itself is under the synpress organisation, and the badges in the readme still point at the synthetixio repository path. The homepage is synpress.io and the documentation lives at docs.synpress.io, and the sponsor mentioned in the readme is the ethereum-optimism organisation. That history is worth knowing because it explains the shape of the project, a testing library built by a team that runs a production dapp and needed the wallet problem solved for their own suite. The default branch is dev, and the release history shows 3.7.3 from 2024-05-30, 3.7.2 from 2024-05-28 and a 3.7.2 beta from 2024-01-25, with the last push on 2026-10-06. So the source is being worked on well after the last tag, which means the tagged release on npm is not the current state of the branch, and the changesets directory plus the release directory indicate that releases are cut from the dev branch rather than from master, where the CI badges point.

## Conclusion

Synpress is a good fit for a dapp team whose end to end suite spends its time clicking through a browser extension, because the wallet state is set up once and cached, which turns the slowest and most brittle part of the suite into a setup step. It is the wrong tool for a project with no wallet interaction to test, since the whole library exists for that case, and it is the wrong tool if your CI cannot run a browser with an extension at all. It is also the wrong tool if you need the framework to be one or the other, because Synpress deliberately supports both Cypress and Playwright, which means you get the features of whichever you already have rather than a reason to switch. Before adopting it, read the docs site, because the API surface differs enough between the two frameworks that you should pick one before you start, and note the package namespace is still the synthetixio one even though the repository lives under synpress. The project is MIT licensed, the last push was on 2026-10-06, and the most recent tagged release is 3.7.3 from 2024-05-30.

## FAQ

### What is Synpress and what does it automate?

It is an E2E testing library for Web3 dapps built on top of Cypress and Playwright, and it simplifies testing interactions with wallets like MetaMask and other blockchain-specific operations. The core is designed to be wallet and blockchain agnostic, with a deep integration for MetaMask.

### How do I install Synpress?

With pnpm add -D @synthetixio/synpress@latest. The package is published under the synthetixio scope even though the repository is under the synpress organisation, and the project requires pnpm, with a preinstall script that rejects npm and yarn in its own repository.

### How does Synpress speed up wallet testing?

You define your dApps wallet setup once and Synpress caches the browser state, which the documentation says dramatically speeds up test execution and makes the full potential of Playwright and Cypress available, including parallel testing. The repository has separate cache build targets per wallet, one for metamask and one for phantom.

### Does Synpress work with both Cypress and Playwright?

Yes, that is the first feature on the list, and you use either framework as your testing framework while leveraging its existing features. The same tests are not interchangeable between the two, so pick one before reading the API reference, and the debugging output comes from the framework you chose.

### Can Synpress run against a local blockchain?

Yes, there is Anvil support for spinning up a local Anvil node with one line of code for fast and isolated testing, which means you control the chain state the test depends on. The repository also carries an ethereum-wallet-mock example alongside the metamask example for faster runs.

## Sources

- [License: MIT](https://github.com/synpress/synpress/blob/dev/LICENSE)
- [Project website](https://synpress.io)
- [README](https://github.com/synpress/synpress/blob/dev/README.md)
- [Releases](https://github.com/synpress/synpress/releases)
- [synpress/synpress on GitHub](https://github.com/synpress/synpress)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/synpress-synpress