@synthetixio/synpress

⚙️ Synpress

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.

👷 Example setup for eslint and tsconfig

Project structure:

project_dir
└── src
└── tests
    └── e2e
        └── .eslintrc.js
        └── tsconfig.json
        └── specs
            └── example-spec.js
        └── pages
            └── example-page.js

1. 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`,
};

1. 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": ["**/*.*"]
}

1. You're done! 🎉

⚡ Important

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)
• switches back to Cypress window and starts testing

It requires environmental variable called SECRET_WORDS to be present in following format => 'word1, word2, etc..'.

If you want to customize it, instead of using environmental variable, you can modify setupMetamask() to following:

setupMetamask(secretWords, network, password), for example: setupMetamask('word1, word2, etc..', 'mainnet', 'password').

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. You can override metamask with METAMASK_VERSION environmental variable, for example: METAMASK_VERSION=9.1.1.

🧪 Usage

• synpress run to run tests
• synpress open to open Cypress UI

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

🚢 Release process

1. Create PR from dev branch to master branch
2. Merge it
3. Switch to master branch and pull latest changes
4. Run npm run release:patch/minor/major command
5. Keep dev branch up to date with master

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