Merge pull request #1107 from Agoric/docs/synpress-commands

docs: added doc for agoric/synpress commands

main/e2e-testing.md

@@ -4,8 +4,6 @@ sidebar: auto
 
 # Testing
 
-## Background
-
 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`](https://github.com/agoric-labs/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`](https://github.com/Synthetixio/synpress), a framework designed for Metamask-based DApps.
@@ -143,3 +141,133 @@ Some examples projects utilizing `@agoric/synpress` for e2e tests:
 
 - [PSM dApp E2E Tests](https://github.com/Agoric/dapp-psm/tree/main/tests/e2e)
 - [Wallet dApp E2E Tests](https://github.com/frazarshad/wallet-app/tree/main/test/e2e)
+
+## @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 is `Test1234`).
+- `newAccount` _(**boolean**)_: Whether to create a new wallet or not. (default is `false`).
+- `walletName` _(**string**)_: The name of the wallet. (default is `My Wallet`).
+- `selectedChains` _(**array**)_: The chains to select. (default is an empty array, `[]`).
+- `createNewWallet` _(**boolean**)_: Whether to create a new wallet (default is `false`).
+
+**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 the `setupWallet` 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 portfolio `false` 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.
+
+<br />
+
+For a full list of commands, you can refer to the [Keplr plugin file](https://github.com/agoric-labs/synpress/blob/dev/plugins/keplr-plugin.js).