@synthetixio/synpress
Advanced tools
Synpress is e2e testing framework based around Cypress.io & playwright with included MetaMask support. Test your dapps with ease.
Synpress is e2e testing framework based on Cypress.io and playwright with support for metamask.
Synpress makes sure to always use latest version of metamask and puts a lot of effort to make sure that dapp tests are stable and trustful.
It also provides an easy way to use and access metamask straight from your e2e tests with all features of cypress and playwright.
Usage examples:
For additional custom commands and their examples, check here.
To see in which direction Synpress is headed to, take a look at planning board.
.env file automatically (from project root
folder)Project structure:
project_dir
└── src
└── tests
└── e2e
└── .eslintrc.js
└── support.js
└── tsconfig.json
└── specs
└── example-spec.js
└── pages
└── example-page.js
.eslintrc.js inside your tests folder (/project_dir/tests/e2e):const path = require('path');
const synpressPath = path.join(
process.cwd(),
'/node_modules/@synthetixio/synpress',
);
module.exports = {
extends: `${synpressPath}/.eslintrc.js`,
};
support.js inside your tests folder (/project_dir/tests/e2e):import '@synthetixio/synpress/support/index';
^ hint: you can also use this file to extend synpress - add custom commands, and more..
tsconfig.json inside your tests folder (/project_dir/tests/e2e):{
"compilerOptions": {
"allowJs": true,
"baseUrl": "../../node_modules",
"types": [
"cypress",
"@synthetixio/synpress/support",
"cypress-wait-until",
"@testing-library/cypress"
],
"outDir": "./output"
},
"include": ["**/*.*"]
}
To change specific values in default config, you can use --config flag. For
example, to change path for support.js file, you can use
synpress run --config "supportFile=__tests__/e2e/supportFile.js"
If you would like to use custom paths for your tests and configs, you should
mirror (full) default synpress config
and then modify it for your needs. Then you can direct synpress to use it with
--configFile flag.
For example: synpress run --configFile __tests__/e2e/customConfig.config.js
Synpress doesn't seem to communicate with metamask properly if
"chromeWebSecurity": false flag is set. More about it
here.
Tests work only in non-headless mode because extensions are not supported in headless mode in playwright and Cypress. As a workaround, use provided docker 🐳 containers. They solve this issue.
There is a global
before()
which runs metamask setup before all tests:
goerli) or creates custom network and changes
to it (depending on your setup)It requires environmental variable called SECRET_WORDS to be present in
following format => 'word1 word2 word3 ..' (delimited with spaces) or private
key in an environmental variable called PRIVATE_KEY.
To change default network (goerli), you can use NETWORK_NAME environmental
variable, for example: NETWORK_NAME=sepolia.
Available choices are: mainnet, goerli, sepolia and localhost.
To create and switch to custom network at metamask setup phase, use these:
NETWORK_NAME => ex: synthetixRPC_URL => ex: https://synthetix-node.ioCHAIN_ID => ex: 123SYMBOL => ex: SNXBLOCK_EXPLORER (optional) => ex: https://synthetix-explorer.ioIS_TESTNET (optional) => ex: falseMetamask version is hardcoded and frequently updated under supervision to avoid
a case when e2e tests break because of CSS classes changes in new version, so
all you need is to keep synpress updated in your project. However, you can still
override metamask with METAMASK_VERSION environmental variable, for example:
METAMASK_VERSION=10.21.0 or METAMASK_VERSION=latest.
If you don't want to use environmental variables, you can modify
setupMetamask()
to following:
setupMetamask(secretWordsOrPrivateKey, network, password), for example:
setupMetamask('word1 word2 word3 ..', 'mainnet', 'password') (delimited with
spaces).
You can also add and switch to custom network by passing an object instead of
string inside setupMetamask(secretWordsOrPrivateKey, network, password)
function for network parameter.
If you want to use Etherscan API helpers, you will have to provide Etherscan API
key using ETHERSCAN_KEY environmental variable.
To fail a test if there are any browser console errors, set FAIL_ON_ERROR to
1 or true.
Automatic waiting for XHR requests to finish before tests start can be turned on
with CYPRESS_RESOURCES_WAIT environmental variable, set it to 1 or true.
If you want to skip metamask extension installation or metamask setup, you can
use SKIP_METAMASK_INSTALL and SKIP_METAMASK_SETUP separately. Both variables
accept 1 or true.
Synpress is blazingly-fast ⚡ by default! If you want to change that, you can
use STABLE_MODE=true (which will introduce delays only between main actions,
300ms by default) / STABLE_MODE=<value> or SLOW_MODE=true (which will
introduce delay between every action, 50ms by default) / SLOW_MODE=<value>.
DEBUG=synpress:* is very useful while debugging your tests. It enables
following features:
You may encounter 403 errors (on shared IPs & CI) related to rate limiting while
fetching metamask releases from GitHub REST API. This should never happen at
all, but it's good to mention. To prevent it from happening, you can create new
private access token on GitHub (without any additional access) and specify
GH_USERNAME & GH_PAT environmental variables.
Dreaming about "headless" mode? Here comes a rescue 🚑!
Docker is awesome for CI and local development. Give it a try.
git clone git@github.com:Synthetixio/synpress.gitcd synpress.env filedocker-compose --profile foundry up --build --exit-code-from synpress or
./start-tests.sh
docker-compose up --build --exit-code-from synpressdocker-compose --profile foundry --profile ngrok up --build --exit-code-from synpressAll examples of setup are present in this repository. Just take a look around.
Warning: M2 is not supported with docker. As a workaround - you can use codespaces, they're fully supported! :)
synpress run to run testssynpress open to open Cypress UI (may be bugged in some cases because it
doesn't clear metamask state before each e2e test, please use synpress run)Command line interface (synpress help):
Usage: synpress run [options]
launch tests
Options:
-b, --browser <name> run on specified browser (default: "chrome")
-c, --config <config> set configuration values, separate multiple values with a comma
-cf, --configFile <path> specify a path to *.js file where configuration values are set
-e, --env <env=val> set environment variables, separate multiple values with comma
-s, --spec <path or glob> run only provided spec files
-ne, --noExit keep runner open after tests finish
-pr, --project <path> run with specific project path
-q, --quiet only test runner output in console
-r, --reporter <reporter> specify mocha reporter
-ro, --reporterOptions <options> specify mocha reporter options, separate multiple values with comma
-r, --record [dashboard] record video of tests running after setting up your project to record
-k, --key <key> [dashboard] set record key
-p, --parallel [dashboard] run recorded specs in parallel across multiple machines
-g, --group [name] [dashboard] group recorded tests together under a single run
-t, --tag <name> [dashboard] add tags to dashboard for test run
-h, --help display help for command
Usage: synpress open [options]
launch test runner UI
Options:
-cf, --configFile <path> specify a path to *.js file where configuration values are set
-h, --help display help for command
dev branch to master branch-beta version is automatically released)patch|minor|major depending on your needs to promote your build.Alternatively, instead of running GitHub Action for release, you can move on with manual release process:
master branch and pull latest changesyarn release:patch/minor/major commanddev branch up to date with masterAbove actions will lead to:
FAQs
[](https://badge.fury.io/js/%40synthetixio%2Fsynpress) [
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team uncovered a malicious Python package typosquatting the popular 'fabric' SSH library, silently exfiltrating AWS credentials from unsuspecting developers.
Security News
At its inaugural meeting, the JSR Working Group outlined plans for an open governance model and a roadmap to enhance JavaScript package management.
Security News
Research
An advanced npm supply chain attack is leveraging Ethereum smart contracts for decentralized, persistent malware control, evading traditional defenses.