Testing
Developing Decentralized Applications (DApps) on the Cosmos network often involves integrating with the Keplr wallet. Testing is key for ensuring users can flawlessly interact with your DApp through the Keplr wallet.
@agoric/synpress
is an end-to-end (e2e) testing framework that simplifies the testing process for Keplr-based DApps. This framework automates testing how your DApp interacts with the Keplr wallet, simulating real user experiences. @agoric/synpress
is built upon synthetixio/synpress
, a framework designed for Metamask-based DApps.
Since @agoric/synpress
is based on Cypress, the official Cypress documentation has a lot of information that you can use with @agoric/synpress
.
Installation
Before you start testing your DApp with Keplr, you'll need to install the @agoric/synpress
in your project using the following command:
yarn add -D @agoric/synpress
Project structure
We recommend the following project structure for keeping your e2e tests clean and manageable:
project_dir
└── src
└── tests
└── e2e
└── synpress.config.js
└── support.js
└── specs
└── test.spec.js
Configure synpress.config.js
Before you start writing your E2E tests, you'll need to create a configuration file named synpress.config.js
in the tests/e2e
directory of your project.
Inside synpress.config.js
, you'll set the baseUrl
property within the e2e configuration. This tells Cypress where to find your DApp during testing. Here's an example configuration:
const baseConfig = require('@agoric/synpress/synpress.config');
const { defineConfig } = require('cypress');
module.exports = defineConfig({
...baseConfig,
e2e: {
...baseConfig.e2e,
baseUrl: 'http://localhost:5173',
},
});
In this example, baseUrl
is set to http://localhost:5173
. Make sure to replace this with the actual URL where your DApp is running.
By default, if you don't create a synpress.config.js
file, @agoric/synpress
assumes your DApp runs on port 3000 of your local machine (http://localhost:3000
). Specifying the correct baseUrl
ensures your tests interact with the right instance of your DApp.
Since you have a separate synpress.config.js
in the tests/e2e
folder, you need to specify its location when running your tests. Use the --configFile
flag with the synpress run
command:
EXTENSION=keplr synpress run --configFile=tests/e2e/synpress.config.js
Creating a Support File
Navigate to your project's tests/e2e
directory and create a new file named support.js
. This file can be used to create reusable commands that encapsulate common testing actions. For example, you can create a custom command to navigate to a specific page within your application. You can read more about it over here.
After creating your support.js
file, make sure to include the following import statement:
import '@agoric/synpress/support/index';
This import is essential because it brings in the necessary functionalities from @agoric/synpress
to interact with the Keplr wallet within your e2e tests. Without it, your tests won't be able to leverage the features provided by @agoric/synpress
for Keplr integration.
Example Tests
With the environment set up, let's write end-to-end (e2e) tests to test your DApp's functionality. In the tests/e2e/specs
folder, create a new file with a descriptive name that reflects what it tests (e.g., user_login.spec.js
or token_transfer.spec.js
).
Test Structure
You use describe
blocks to group related tests together, and it
blocks to define individual test cases within those groups.
describe('User Login', () => {
it('should login with valid credentials', () => {
// Test steps for login functionality
});
});
Test 1: Setting Up Keplr Wallet
it('should setup a Keplr wallet', () => {
cy.setupWallet({
secretWords: 'KEPLR_MNEMONIC',
});
cy.visit('/');
});
This test case simulates setting up a Keplr wallet for your tests, using the cy.setupWallet
method. Make sure to replace KEPLR_MNEMONIC
with a 24-word mnemonic phrase. The setupWallet
method creates a wallet based on the provided mnemonic phrase, which can then be used throughout your test suite.
After setting up the wallet, we visit the root path (/
) of the DApp using cy.visit('/')
.
Test 2: Connecting Keplr Wallet
it('should accept connection with wallet', () => {
cy.contains('Connect Wallet').click();
cy.acceptAccess();
});
This test simulates a user connecting their Keplr wallet to your DApp. cy.contains('Connect Wallet')
searches for an element containing the text Connect Wallet
on the webpage and triggers a click event. cy.acceptAccess
simulates accepting Keplr wallet access for your DApp.
Test 3: Signing a Transaction
it('should confirm make an offer transaction', () => {
cy.contains('Make an Offer').click();
cy.confirmTransaction();
});
This test simulates transaction Signing on your DApp. cy.contains('Make an Offer')
searches for an element containing the text Make an Offer
and triggers a click event. cy.confirmTransaction
simulates confirming a transaction.
Running the Tests
You can now trigger the tests by running this command:
EXTENSION=keplr synpress run --configFile=tests/e2e/synpress.config.js
Projects Using @agoric/synpress
Some examples projects utilizing @agoric/synpress
for e2e tests:
@agoric/synpress Commands
The @agoric/synpress
commands are custom Cypress commands designed for use with Keplr. They provide ready-made functions to interact with Keplr-specific elements and workflows.
setupWallet
Initializes a Keplr wallet for testing. You can either create a new one or import an existing one using the provided options.
Arguments:
(All arguments are optional)
The command takes a single object as an argument with the following keys:
secretWords
(string): The secret words for the wallet. (default is a predefined mnemonic phrase that represents a wallet address on the Agoric chain)privateKey
(string): The private key for the wallet.password
(string): The password for the wallet. (default isTest1234
).walletName
(string): The name of the wallet. (default isMy Wallet
).selectedChains
(array): The chains to select. (default is an empty array,[]
).createNewWallet
(boolean): Whether to create a new wallet (default isfalse
).
Returns:
- (boolean):
true
if the wallet was set up successfully,false
otherwise.
acceptAccess
Handles the authorization process for connecting the Keplr wallet to a DApp. DApps provide a Connect Wallet
option to initiate this process.
Returns:
- (boolean):
true
if access was accepted successfully,false
otherwise.
confirmTransaction
Handles signing transactions within a DApp using the Keplr wallet. This occurs when a user initiates a transaction, such as sending tokens or interacting with a smart contract.
Returns:
- (boolean):
true
if transaction was approved successfully,false
otherwise.
disconnectWalletFromDapp
Disconnects the Keplr wallet from all previously connected DApps.
Returns:
- (boolean):
true
if the disconnection was successful,false
otherwise.
getWalletAddress
Retrieves the wallet address of the currently active wallet associated with a specified blockchain.
Arguments:
chainName
(string): The name of the blockchain for which you want to obtain the wallet address.
Returns:
- (string): The wallet address for the specified blockchain.
switchWallet
Switches the active wallet to the specified wallet by name.
Arguments:
walletName
(string): The name of the wallet you want to switch to. This should match the name used when the wallet was created using thesetupWallet
command.
Returns:
- (boolean):
true
if the wallet switch was successful,false
otherwise.
addNewTokensFound
Adds all the new tokens discovered by the Keplr extension to the user's token portfolio when it connects to a new blockchain network.
Returns:
- (boolean):
true
if the tokens were successfully added to the user's token portfoliofalse
otherwise.
getTokenAmount
Retrieves the balance of a specified token in the wallet.
Arguments:
tokenName
(string): The name of the token for which you want to retrieve the balance.
Returns:
- (number): The amount of the specified token currently held in the wallet.
isExtensionWindowActive
Determines whether the Keplr extension window is the currently active tab.
Returns:
- (boolean):
true
if the Keplr extension window is active,false
otherwise.
switchToExtensionWindow
Switches the focus to the Keplr extension window tab. Keplr window is used for managing wallet related operations.
Returns:
- (boolean):
true
if the focus change was successful,false
otherwise.
isCypressWindowActive
Determines whether the Cypress window, where the DApp is running, is the currently active tab.
Returns:
- (boolean):
true
if the Cypress window is active,false
otherwise.
switchToCypressWindow
Switches the focus to the Cypress window tab.
Returns:
- (boolean):
true
if the focus change was successful,false
otherwise.
For a full list of commands, you can refer to the Keplr plugin file.