Synpress is an wrapper around Cypress.io with metamask support thanks to puppeteer.
Synpress makes sure to always use latest version of metamask before tests are ran.
It also provides an easy way to use metamask straight from your e2e tests.
Feel free to take a look at kwenta repository for examples of usage.
For additional custom commands and their examples, check here.
Project structure:
project_dir
└── src
└── tests
└── e2e
└── .eslintrc.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
tsconfig.json
inside your tests folder (/project_dir/tests/e2e
):
{
"compilerOptions": {
"allowJs": true,
"baseUrl": "../../node_modules",
"types": ["cypress", "@types/puppeteer-core", "@synthetixio/synpress/support", "cypress-wait-until", "@testing-library/cypress"],
"outDir": "./output"
},
"include": ["**/*.*"]
}
- You're done! 🎉
If you would like to use custom paths for your tests and configs, feel free to mirror default synpress config and modify it for your needs. Then you can direct synpress to use it with --configFile
flag.
For example: synpress run --configFile __tests__/e2e/customConfig.json
Synpress doesn't seem to communicate with metamask properly if "chromeWebSecurity": false
flag is set. More about it here.
Tests work only in headed mode because extensions are not supported in headless mode in puppeteer and Cypress. It's intended to be used in conjunction with xvfb
on CI.
There is a global before()
which runs metamask setup before all tests:
- passes welcome page
- imports wallet
- changes network (defaults to
kovan
) 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, etc..'
.
To change default network (kovan
), you can use NETWORK_NAME
environmental variable, for example: NETWORK_NAME=rinkeby
.
Available choices are: mainnet
, ropsten
, kovan
, rinkeby
, goerli
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
(optional) => 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=9.3.0
or METAMASK_VERSION=latest
.
If you don't want to use environmental variables, you can modify setupMetamask()
to following:
setupMetamask(secretWords, network, password)
, for example: setupMetamask('word1, word2, etc..', 'mainnet', 'password')
.
You can also add and switch to custom network by passing an object
instead of string
inside setupMetamask(secretWords, 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
enironmental variable.
If you want to fail a test if there are any browser console errors, set FAIL_ON_ERROR
to 1
or true
.
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 a JSON 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 a JSON file where configuration values are set
-h, --help display help for command
- Create PR from
dev
branch tomaster
branch - Merge it
- Run GitHub Action workflow named Release CI with
patch|minor|major
depending on your needs.
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
npm run 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