@skunal8197/synpress-flask v3.5.0
Synpress is e2e testing framework based on Cypress and Playwright with support for MetaMask and MetaMask Flask.
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.
๐ฅ Synpress works out-of-the-box with other frameworks! There is no need to use it directly. Check usage examples for more details.
Supported frameworks
- synpress
- Playwright (as a plugin)
- Cypress (as a plugin)
Supported wallets
Usage examples:
For full Synpress commands and their examples, check here.
To see in which direction Synpress is headed to, take a look at planning board.
Features
- Added support for metamask ๐ฆ
- Supports headless mode ๐ค (
synpress run --headless
)- Recommended for local development (but not for CI yet as it's new and experimental)
- Integrated with docker ๐ณ
- Easy to debug ๐
- Improved error handling
- Supports cypress and playwright debuggers
- noVNC allows for interactions through browser ๐
- Debug remote machines on CI with ngrok
- Blazingly-fast โก
- Extensible โ๏ธ (add own custom commands and plugins)
- Can be used in existing cypress setup
- Supports dotenv
- Loads all env vars from your
.env
file automatically (from project root folder)
- Loads all env vars from your
- Ability to use latest metamask or lock it's version to avoid unexpected failures related to metamask updates
- Supports multi-lang of metamask, it doesn't depend on any labels
- Synpress is fully tested
- Waits for XHR requests, navigations and animations automatically
- Ability to fail test run if there are any browser console errors found
- Types support for all additional custom commands
- The best possible options set up in place to avoid flakiness
- Etherscan API helpers in place which for ex. allows to compare your transaction results with etherscan and check tx status
- Synthetix helpers in place which allows to interact with synthetix protocol programmatically
- Supports codespaces
- Run your tests in docker
- Get your feedback remotely thanks to ngrok
- Use mpeg-4 preview plugin to watch videos from inside codespaces :) ...
๐ท Example setup for eslint and tsconfig
Project structure:
project_dir
โโโ src
โโโ tests
โโโ e2e
โโโ .eslintrc.js
โโโ support.js
โโโ tsconfig.json
โโโ specs
โโโ example-spec.js
โโโ pages
โโโ example-page.js
- Create
.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`,
};
- Create
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..
- Create
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": ["**/*.*"]
}
- You're done! ๐
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
โก Important
Synpress doesn't seem to communicate with metamask properly if
"chromeWebSecurity": false
flag is set. More about it
here.
Thanks to
new headless mode in Chrome,
tests are now working in headless mode ๐ค (synpress run --headless
). However,
I recommend to use it only for local development as this feature is new and
experimental and may cause issues on CI (UNIX). So please, stick to non-headless
mode on CI.
In the past, tests worked only in non-headless mode because extensions were not supported in headless mode by playwright and Cypress. As a workaround, we've provided docker ๐ณ containers. They solved this issue and it's an alternative.
You have to setup xvfb
and window manager (like fluxbox
or xfce4
) to run
tests without issues on CI (together with DISPLAY
env var). Take a look at
CI tips & tricks
for working examples.
There is a global
before()
which runs metamask setup before all tests:
- passes welcome page
- imports wallet
- changes network (defaults to
goerli
) or creates custom network and changes to it (depending on your setup) - switches back to Cypress window and starts testing
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:synthetix
RPC_URL
=> ex:https://synthetix-node.io
CHAIN_ID
=> ex:123
SYMBOL
=> ex:SNX
BLOCK_EXPLORER
(optional) => ex:https://synthetix-explorer.io
IS_TESTNET
(optional) => ex:false
Metamask 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:
- improved logging
- cypress debugger
- playwright debugger
- slow down tests
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.
๐ณ Using with Docker
Docker is awesome for CI. Give it a try.
Requirements
Some neat features
- based on docker-e2e โค
- full screen video recording ๐ฅ (together with metamask extension)
- VNC & noVNC support ๐ฅ๏ธ (very easy to debug with browser)
- ngrok ๐ integration (exposes noVNC for everyone)
- remote: https://.ngrok.io/vnc.html?autoconnect=true (check logs for url)
How to use
git clone git@github.com:Synthetixio/synpress.git
cd synpress
- (optional) Fill env vars inside
.env
file - (with foundry; preferred)
docker-compose --profile synpress --profile foundry up --build --exit-code-from synpress
or./start-tests.sh
- (without foundry)
docker-compose up --profile synpress --build --exit-code-from synpress
- (without foundry)
- (with foundry and ngrok)
docker-compose --profile synpress --profile foundry --profile ngrok up --build --exit-code-from synpress
All examples of setup are present in this repository. Just take a look around.
CI tips & tricks
- check out many different
examples in this repository:
- e2e_headful.yml
=> runs on
ubuntu-latest
. - e2e_debug.yml
=> runs on
ubuntu-latest
, has configured VNC, noVNC and ngrok for easy debugging. - e2e_docker.yml
=> runs on
ubuntu-latest
withdocker compose
stack. - e2e_cypress-action.yml
=> runs on
ubuntu-latest
, using official cypress-io/github-action.
- e2e_headful.yml
=> runs on
- use docker-e2e
- synpress is tested and should work on all resolutions, starting from 800x600
๐งช Usage
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 usesynpress 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
Environmental variables
Variable | Description |
---|---|
SECRET_WORDS | Space separated words for the test wallet recovery phrase (mnemonic; 12 words) |
PRIVATE_KEY | Test wallet private key |
NETWORK_NAME | Network name (eg NETWORK_NAME=Optimism ) |
RPC_URL | Network RPC (egRPC_URL=https://mainnet.optimism.io ) |
CHAIN_ID | Network ID (egCHAIN_ID=10 ) |
SYMBOL | Native chain token ticker (eg SYMBOL=OP ) |
IS_TESTNET | boolean indicates that the added network is testnet |
BLOCK_EXPLORER | Blockchain explorer (eg BLOCK_EXPLORER=https://optimistic.etherscan.io/ ) |
SYNDEBUG | Set debugging mode to be on |
STABLE_MODE | Introduce delay between main actions, 300ms by default (eg STABLE_MODE=300ms , STABLE_MODE=true ) |
SLOW_MODE | Introduce delay between every action, 50ms by default (eg SLOW_MODE=true , SLOW_MODE=200ms ) |
METAMASK_VERSION | Metamask version to be installed |
SKIP_METAMASK_INSTALL | Will skip MetaMask installation |
SKIP_METAMASK_SETUP | Will skip MetaMask initial setup |
GH_USERNAME | GitHub username (used to avoid rate-limit issue while downloading metamask) |
GH_PAT | GitHub personal access token (used to avoid rate-limit issue while downloading metamask) |
ETHERSCAN_KEY | Etherscan key (used only for etherscan-related commands) |
FAIL_ON_ERROR | Fail a test if there are any browser console errors |
CYPRESS_GROUP | Group tests |
CI | boolean value indicate that tests are runing from CI/CD pipeline |
๐ข Release process
- Create PR from
dev
branch tomaster
branch - Merge it (new
-beta
version is automatically released) - Run GitHub Action workflow named
Release CI
with
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:
- Switch to
master
branch and pull latest changes - Run
yarn release:patch/minor/major
command - Keep
dev
branch up to date withmaster
Above actions will lead to:
- New npm node module release
- New GitHub packages node module release
- New GitHub release (tagged) created with changelog from commit messages
๐ More resources
- Synpress - web3-enabled e2e testing tool
- How to set up Synpress for Web3 dApp Frontend Test Automation with MetaMask
- Extending Synpress with additional MetaMask commands
- Test e2e login to dApp with Metamask with Synpress
Running Locally
nvm use 16
yarn install
yarn test:e2e
2 years ago