4.0.0-alpha.53 โ€ข Published 2 months ago

@phantom/synpress v4.0.0-alpha.53

Weekly downloads
-
License
MIT
Repository
github
Last release
2 months ago

npm version Synpress CI CodeQL Release CI synpress Discord Twitter Follow

We're Hiring ๐ŸŽ‰ โ€” Think you have what it takes? We're looking for Software Engineer, find out more.

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.

Table of content

๐Ÿง‘โ€๐Ÿคโ€๐Ÿง‘ Community

  • Discord => for live support and direct chat with devs.
  • Twitter => for updates and announcements.

๐Ÿ–ฅ๏ธ Install

# with pnpm
pnpm add --save-dev @synthetixio/synpress
# with npm
npm install --save-dev @synthetixio/synpress
# with yarn
yarn add -D @synthetixio/synpress

โš™๏ธ Supported frameworks

๐Ÿ‘ 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 ๐Ÿณ
    • Recommended for CI
    • Includes VNC and noVNC
    • Integrated video recording ๐ŸŽฅ (full screen)
    • Exposes noVNC with ngrok (optional)
  • 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)
  • 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
  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 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..

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

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:

  1. NETWORK_NAME => ex: synthetix
  2. RPC_URL => ex: https://synthetix-node.io
  3. CHAIN_ID => ex: 123
  4. SYMBOL => ex: SNX
  5. BLOCK_EXPLORER (optional) => ex: https://synthetix-explorer.io
  6. 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:

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 run e2e tests for Synpress using Docker

  1. git clone git@github.com:Synthetixio/synpress.git
  2. cd synpress
  3. (optional) Fill env vars inside .env file
  4. (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
  5. (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

๐Ÿงช Usage & commands

  • synpress run to run tests
  • synpress 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

๐Ÿ‘จโ€โš•๏ธ Known problems with MetaMask

If your MetaMask is stuck on the loading screen, check what's happening under the hood in the console. You can find vital information about why it's stuck on this step.

โญ Sentry.io HTTP error 499 (Request has been forbidden by antivirus)

  • Kaspersky antivirus sometimes blocks encrypted requests to Sentry.io. You can disable this feature in Kaspersky advanced settings by toggling on "Do not scan encrypted connections".

๐Ÿ“ƒ Environmental variables

VariableDescription
SECRET_WORDSSpace separated words for the test wallet recovery phrase (mnemonic; 12 words)
PRIVATE_KEYTest wallet private key
NETWORK_NAMENetwork name (eg NETWORK_NAME=Optimism)
RPC_URLNetwork RPC (egRPC_URL=https://mainnet.optimism.io)
CHAIN_IDNetwork ID (egCHAIN_ID=10)
SYMBOLNative chain token ticker (eg SYMBOL=OP)
IS_TESTNETboolean indicates that the added network is testnet
BLOCK_EXPLORERBlockchain explorer (eg BLOCK_EXPLORER=https://optimistic.etherscan.io/)
SYNDEBUGSet debugging mode to be on
STABLE_MODEIntroduce delay between main actions, 300ms by default (eg STABLE_MODE=300ms, STABLE_MODE=true)
SLOW_MODEIntroduce delay between every action, 50ms by default (eg SLOW_MODE=true, SLOW_MODE=200ms)
METAMASK_VERSIONMetamask version to be installed
SKIP_METAMASK_INSTALLWill skip MetaMask installation
SKIP_METAMASK_SETUPWill skip MetaMask initial setup
GH_USERNAMEGitHub username (used to avoid rate-limit issues while downloading Metamask)
GH_PATGitHub personal access token (used to avoid rate-limit issue while downloading metamask)
ETHERSCAN_KEYEtherscan key (used only for etherscan-related commands)
FAIL_ON_ERRORFail a test if there are any browser console errors
CYPRESS_GROUPGroup tests
CIBoolean value indicates that tests are running from CI/CD pipeline

๐Ÿšข Release process

  1. Create PR from dev branch to master branch
  2. Merge it (new -beta version is automatically released)
  3. 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:

  1. Switch to master branch and pull latest changes
  2. Run pnpm release:patch/minor/major command
  3. 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

๐Ÿ“ More resources

4.0.0-alpha.53

2 months ago

4.0.0-alpha.52

2 months ago

4.0.0-alpha.51

3 months ago

4.0.0-alpha.50

3 months ago

4.0.0-alpha.49

3 months ago

4.0.0-alpha.48

3 months ago

4.0.0-alpha.47

3 months ago

4.0.0-alpha.42

4 months ago

4.0.0-alpha.41

4 months ago

4.0.0-alpha.40

4 months ago

4.0.0-alpha.46

3 months ago

4.0.0-alpha.45

4 months ago

4.0.0-alpha.44

4 months ago

4.0.0-alpha.43

4 months ago

4.0.0-alpha.39

5 months ago

4.0.0-alpha.38

5 months ago

4.0.0-alpha.37

5 months ago

4.0.0-alpha.36

5 months ago

4.0.0-alpha.35

7 months ago

4.0.0-alpha.34

9 months ago

4.0.0-alpha.33

9 months ago

4.0.0-alpha.32

10 months ago

4.0.0-alpha.31

11 months ago

4.0.0-alpha.30

11 months ago

4.0.0-alpha.28

1 year ago

4.0.0-alpha.27

1 year ago

4.0.0-alpha.26

1 year ago

4.0.0-alpha.29

1 year ago

4.0.0-alpha.19

2 years ago

4.0.0-alpha.25

2 years ago

4.0.0-alpha.20

2 years ago

4.0.0-alpha.24

2 years ago

4.0.0-alpha.23

2 years ago

4.0.0-alpha.22

2 years ago

4.0.0-alpha.21

2 years ago

4.0.0-alpha.18

2 years ago

4.0.0-alpha.17

2 years ago

4.0.0-alpha.16

2 years ago

4.0.0-alpha.15

2 years ago

4.0.0-alpha.14

2 years ago

4.0.0-alpha.13

2 years ago

4.0.0-alpha.12

2 years ago

4.0.0-alpha.11

2 years ago

4.0.0-alpha.10

2 years ago

4.0.0-alpha.9

2 years ago

4.0.0-alpha.8

2 years ago

4.0.0-alpha.7

2 years ago

4.0.0-alpha.6

2 years ago

4.0.0-alpha.5

2 years ago

4.0.0-alpha.4

2 years ago

4.0.0-alpha.3

2 years ago

4.0.0-alpha.2

2 years ago

4.0.0-alpha.1

2 years ago

4.0.0-alpha.0

2 years ago

3.6.0-rc.1

2 years ago

3.6.0-rc.0

2 years ago

3.0.6-rc.1

2 years ago

3.0.6-rc.0

2 years ago

3.0.6

2 years ago

3.0.5

2 years ago