agoric-labs/synpress

Synpress is e2e testing framework based on Cypress.io and playwright with support for metamask.

@agoric/synpress is a testing framework designed to test DApps that use the Keplr Wallet.

For full commands and their examples, check here.

🖥️ Install

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

👝 Supported wallets

• Keplr
• MetaMask (Currently in alpha)

👷 Example setup

Project structure:

project_dir
└── src
└── tests
    └── e2e
        └── support.js
        └── specs
            └── example-spec.js

1. Create support.js inside your tests folder (/project_dir/tests/e2e):

import '@agoric/synpress/support/index';

^ hint: you can also use this file to extend synpress - add custom commands, and more..

2. Add a command to your package.json file

{
  ...
  "scripts": {
    ...
    "test:e2e": "EXTENSION=keplr synpress run"
  }
}

3. (Optional) Create a custom config file. @agoric/synpress aleardy has some configurations set up in this file. To override this and add your custom config, you can create your own config file synpress.config.js in /project_dir/tests/e2e

const baseConfig = require('@agoric/synpress/synpress.config');
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  ...baseConfig,
  e2e: {
    ...baseConfig.e2e,
    baseUrl: 'http://localhost:5173',
  },
});

        use this config by passing the --configFile flag to synpress

{
  ...
  "scripts": {
    ...
    "test:e2e": "EXTENSION=keplr synpress run --configFile=test/e2e/synpress.config.js"
  }
}

4. You're done! 🎉

For an example project, you can take a look at how we've set up tests in this repository

📃 Environmental variables

Variable	Description
EXTENSION (Required)	Picks which extension to use during tests. keplr and metamask are the only possible values
SECRET_WORDS	Space separated words for the test wallet recovery phrase (mnemonic; 24 words)
PRIVATE_KEY	Test wallet private key
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)
KEPLR_VERSION	Keplr version to be installed
SKIP_KEPLR_INSTALL	Will skip installation of keplr wallet
SKIP_EXTENSION_SETUP	Will skip initial setup of wallet

These is a basic list of environment variables to be used. A more in depth list can be found here

📝 More resources

@agoric/synpress uses Synpress as its base and therefore supports most of its functionality. To learn more about command line options, usage examples, and CI/CD setup, you can use the original README file