dappress 0.5.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +8 -1
- package/README.md +155 -166
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,12 @@ What changes for the users of Dappress, version by version. The format follows [
|
|
|
4
4
|
|
|
5
5
|
## [Unreleased]
|
|
6
6
|
|
|
7
|
+
## [0.5.1] - 2026-10-05
|
|
8
|
+
|
|
9
|
+
### Changed
|
|
10
|
+
|
|
11
|
+
- The README is shorter and keeps to what using Dappress needs. What contributors need moves to `CONTRIBUTING.md`.
|
|
12
|
+
|
|
7
13
|
## [0.5.0] - 2026-10-03
|
|
8
14
|
|
|
9
15
|
### Changed
|
|
@@ -79,7 +85,8 @@ What changes for the users of Dappress, version by version. The format follows [
|
|
|
79
85
|
- The wallet setup file, `cypress/wallet.setup.ts`, and the opt-in profile cache.
|
|
80
86
|
- TypeScript declarations.
|
|
81
87
|
|
|
82
|
-
[Unreleased]: https://github.com/blassaut/dappress/compare/v0.5.
|
|
88
|
+
[Unreleased]: https://github.com/blassaut/dappress/compare/v0.5.1...HEAD
|
|
89
|
+
[0.5.1]: https://github.com/blassaut/dappress/compare/v0.5.0...v0.5.1
|
|
83
90
|
[0.5.0]: https://github.com/blassaut/dappress/compare/v0.4.0...v0.5.0
|
|
84
91
|
[0.4.0]: https://github.com/blassaut/dappress/compare/v0.3.3...v0.4.0
|
|
85
92
|
[0.3.3]: https://github.com/blassaut/dappress/compare/v0.3.2...v0.3.3
|
package/README.md
CHANGED
|
@@ -4,27 +4,41 @@
|
|
|
4
4
|
|
|
5
5
|
[](https://github.com/blassaut/dappress/blob/conformance-reports/MATRIX.md)
|
|
6
6
|
|
|
7
|
-
Dappress loads the MetaMask
|
|
7
|
+
Your dapp asks MetaMask to connect, sign or send a transaction, and a real user clicks a button in the wallet. Dappress clicks it for you. It loads the real MetaMask extension into the browser Cypress launches, imports a test wallet, and gives you `cy.*` commands such as `cy.connectToDapp()` or `cy.confirmTransaction()`.
|
|
8
8
|
|
|
9
|
-
- **
|
|
10
|
-
- **Cypress
|
|
11
|
-
- **
|
|
9
|
+
- **The latest MetaMask.** You choose the extension version. Every MetaMask release is tested daily, one test per command: see the [conformance matrix](https://github.com/blassaut/dappress/blob/conformance-reports/MATRIX.md).
|
|
10
|
+
- **Plain Cypress.** No second browser, no proxy. Commands are typed for TypeScript.
|
|
11
|
+
- **Stable selectors.** They come from MetaMask's own end-to-end tests, each with a fallback.
|
|
12
|
+
|
|
13
|
+
## Contents
|
|
14
|
+
|
|
15
|
+
- [Requirements](#requirements)
|
|
16
|
+
- [Quick start](#quick-start)
|
|
17
|
+
- [Commands](#commands)
|
|
18
|
+
- [Configuration](#configuration)
|
|
19
|
+
- [Security](#security)
|
|
20
|
+
- [Troubleshooting](#troubleshooting)
|
|
21
|
+
- [Contributing](#contributing)
|
|
12
22
|
|
|
13
23
|
## Requirements
|
|
14
24
|
|
|
15
|
-
| Dependency | Version
|
|
16
|
-
|
|
17
|
-
| Cypress
|
|
18
|
-
| Node.js
|
|
19
|
-
| Browser
|
|
25
|
+
| Dependency | Version |
|
|
26
|
+
| ---------- | ----------------------------------------------------------------------------- |
|
|
27
|
+
| Cypress | 15.10 or later |
|
|
28
|
+
| Node.js | 20 or later |
|
|
29
|
+
| Browser | Chrome for Testing, Chromium or Electron. Not Google Chrome: since version 137 it no longer loads extensions. |
|
|
30
|
+
|
|
31
|
+
Tested on macOS and on GitHub's Linux runners.
|
|
20
32
|
|
|
21
|
-
##
|
|
33
|
+
## Quick start
|
|
22
34
|
|
|
23
|
-
|
|
35
|
+
### 1. Install
|
|
36
|
+
|
|
37
|
+
```sh
|
|
24
38
|
npm install --save-dev dappress
|
|
25
39
|
```
|
|
26
40
|
|
|
27
|
-
Register the plugin
|
|
41
|
+
### 2. Register the plugin
|
|
28
42
|
|
|
29
43
|
```ts
|
|
30
44
|
// cypress.config.ts
|
|
@@ -34,7 +48,7 @@ import { configureDappress } from 'dappress';
|
|
|
34
48
|
export default defineConfig({
|
|
35
49
|
e2e: {
|
|
36
50
|
baseUrl: 'http://localhost:3000',
|
|
37
|
-
testIsolation: false,
|
|
51
|
+
testIsolation: false,
|
|
38
52
|
setupNodeEvents(on, config) {
|
|
39
53
|
return configureDappress(on, config);
|
|
40
54
|
},
|
|
@@ -42,21 +56,36 @@ export default defineConfig({
|
|
|
42
56
|
});
|
|
43
57
|
```
|
|
44
58
|
|
|
45
|
-
|
|
59
|
+
`testIsolation: false` is required. The tests of a spec share one wallet, and Cypress must not reset the page between them. Each test starts where the previous one ended, so write the tests of a spec to run in order.
|
|
60
|
+
|
|
61
|
+
### 3. Load the commands
|
|
46
62
|
|
|
47
63
|
```ts
|
|
48
64
|
// cypress/support/e2e.ts
|
|
49
65
|
import 'dappress/support';
|
|
50
66
|
```
|
|
51
67
|
|
|
52
|
-
|
|
68
|
+
```json
|
|
69
|
+
// tsconfig.json
|
|
70
|
+
{
|
|
71
|
+
"compilerOptions": {
|
|
72
|
+
"types": ["cypress", "dappress/support"]
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
JavaScript projects use the same files with a `.js` extension and `module.exports`, and skip `tsconfig.json`.
|
|
78
|
+
|
|
79
|
+
### 4. Choose the network
|
|
80
|
+
|
|
81
|
+
Dappress reads `cypress/wallet.setup.ts` (or `.js`) by itself. It holds no secret, so commit it.
|
|
53
82
|
|
|
54
83
|
```ts
|
|
55
84
|
// cypress/wallet.setup.ts
|
|
56
85
|
import type { WalletSetup } from 'dappress';
|
|
57
86
|
|
|
58
87
|
const wallet: WalletSetup = {
|
|
59
|
-
// The network the dapp
|
|
88
|
+
// The network cy.connectToDapp() moves the dapp onto
|
|
60
89
|
network: {
|
|
61
90
|
chainId: '0x88bb0',
|
|
62
91
|
chainName: 'Hoodi',
|
|
@@ -68,46 +97,20 @@ const wallet: WalletSetup = {
|
|
|
68
97
|
export default wallet;
|
|
69
98
|
```
|
|
70
99
|
|
|
71
|
-
|
|
100
|
+
This step is optional. Without a network, the dapp stays on Ethereum mainnet, where MetaMask starts.
|
|
72
101
|
|
|
73
|
-
|
|
74
|
-
{
|
|
75
|
-
"DAPPRESS_SEED_PHRASE": "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
|
|
76
|
-
}
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
In CI, provide it as an encrypted secret of the repository, exposed to the job as an environment variable:
|
|
80
|
-
|
|
81
|
-
```yaml
|
|
82
|
-
# GitHub Actions
|
|
83
|
-
env:
|
|
84
|
-
DAPPRESS_SEED_PHRASE: ${{ secrets.DAPPRESS_SEED_PHRASE }}
|
|
85
|
-
```
|
|
102
|
+
### 5. Get a browser that loads extensions
|
|
86
103
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
```json
|
|
91
|
-
{
|
|
92
|
-
"compilerOptions": {
|
|
93
|
-
"types": ["cypress", "dappress/support"]
|
|
94
|
-
}
|
|
95
|
-
}
|
|
104
|
+
```sh
|
|
105
|
+
npx @puppeteer/browsers install chrome@stable
|
|
96
106
|
```
|
|
97
107
|
|
|
98
|
-
|
|
108
|
+
The command downloads Chrome for Testing and prints the path of its executable. `npx cypress info` lists the browsers Cypress finds by itself.
|
|
99
109
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
```bash
|
|
103
|
-
npx cypress run --browser chrome-for-testing --headed
|
|
104
|
-
```
|
|
105
|
-
|
|
106
|
-
Without `--headed`, the run is headless and works the same, except for the wallet cache, which needs a headed browser.
|
|
107
|
-
|
|
108
|
-
## Usage
|
|
110
|
+
### 6. Write a test and run it
|
|
109
111
|
|
|
110
112
|
```ts
|
|
113
|
+
// cypress/e2e/wallet.cy.ts
|
|
111
114
|
it('connects the wallet and signs in', () => {
|
|
112
115
|
cy.visit('/');
|
|
113
116
|
cy.contains('button', 'Connect wallet').click();
|
|
@@ -119,161 +122,147 @@ it('connects the wallet and signs in', () => {
|
|
|
119
122
|
});
|
|
120
123
|
```
|
|
121
124
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
| Command | What it does |
|
|
127
|
-
|---|---|
|
|
128
|
-
| `cy.connectToDapp()` | Accepts the connection request, then moves the dapp onto the network of the wallet setup |
|
|
129
|
-
| `cy.connectToDapp({ accounts })` | The same, with the accounts named in `accounts` and no other, such as `['Account 1', 'Account 2']`, in place of the wallet's selected account |
|
|
130
|
-
| `cy.rejectConnection()` | Rejects the connection request |
|
|
131
|
-
| `cy.disconnectFromDapp()` | Disconnects the dapp from MetaMask's permissions screen. The dapp receives an empty `accountsChanged`. |
|
|
132
|
-
| `cy.confirmSignature()` | Signs the message (`personal_sign`, `eth_signTypedData_*`) |
|
|
133
|
-
| `cy.rejectSignature()` | Rejects the signature request |
|
|
134
|
-
| `cy.confirmTransaction(options?)` | Sends the transaction, including ERC-20 approvals. With options, sets its spending cap or its network fee first: see [Transaction options](#transaction-options). |
|
|
135
|
-
| `cy.rejectTransaction()` | Rejects the transaction |
|
|
136
|
-
| `cy.approveNewNetwork()` | Adds the network requested by `wallet_addEthereumChain` |
|
|
137
|
-
| `cy.rejectNewNetwork()` | Rejects the network |
|
|
138
|
-
| `cy.approveSwitchNetwork()` | Grants the permission asked by `wallet_switchEthereumChain` for a network the dapp is not yet allowed on |
|
|
139
|
-
| `cy.rejectSwitchNetwork()` | Denies that permission |
|
|
140
|
-
| `cy.approveAddToken()` | Adds the token requested by `wallet_watchAsset` |
|
|
141
|
-
| `cy.rejectAddToken()` | Rejects the token |
|
|
142
|
-
| `cy.addAccount()` | Adds an account to the wallet and selects it. Yields its name, such as `Account 2`. |
|
|
143
|
-
| `cy.importAccount(privateKey)` | Imports an account from its private key and selects it. Yields its name. The key stays out of the command log. |
|
|
144
|
-
| `cy.switchAccount(name)` | Selects an account of the wallet by its name |
|
|
145
|
-
| `cy.lockWallet()` | Locks the wallet from MetaMask's menu. Requests wait behind its unlock screen until it is unlocked. |
|
|
146
|
-
| `cy.unlockWallet()` | Unlocks the wallet with the configured password. Yields how it was found: `locked`, or `unlocked` when there was nothing to do. |
|
|
147
|
-
| `cy.useNetwork(network?)` | Moves the dapp onto a network, adding it to MetaMask when needed. Defaults to the network of the wallet setup. |
|
|
148
|
-
| `cy.getAccountAddress()` | Yields the address the dapp is connected with |
|
|
149
|
-
| `cy.setupMetaMask()` | Imports the wallet, or unlocks it. Called automatically before each spec. |
|
|
125
|
+
```sh
|
|
126
|
+
npx cypress run --browser /path/to/chrome-for-testing
|
|
127
|
+
```
|
|
150
128
|
|
|
151
|
-
|
|
129
|
+
Pass `--browser chrome-for-testing` instead when `npx cypress info` lists it. Add `--headed` to watch MetaMask at work.
|
|
152
130
|
|
|
153
|
-
|
|
131
|
+
Before the first test of each spec, Dappress imports the wallet. Each command then waits for MetaMask to show the request, answers it, and waits for the request to close.
|
|
154
132
|
|
|
155
|
-
|
|
156
|
-
// An ERC-20 approval: let the spender use 2.5 tokens, whatever the dapp asked for
|
|
157
|
-
cy.confirmTransaction({ spendingCap: '2.5' });
|
|
133
|
+
### Testing with funds
|
|
158
134
|
|
|
159
|
-
|
|
160
|
-
cy.confirmTransaction({ gas: { maxBaseFee: 30, priorityFee: 2, gasLimit: 100000 } });
|
|
135
|
+
By default, Dappress creates a new, empty wallet for each run. That is enough to connect and sign. To send transactions, use a wallet of yours that holds test funds, and give its seed phrase outside the repository.
|
|
161
136
|
|
|
162
|
-
|
|
163
|
-
cy.confirmTransaction({ gas: 'aggressive' });
|
|
164
|
-
```
|
|
137
|
+
On your machine, in `cypress.env.json` (add it to `.gitignore`):
|
|
165
138
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
Both options can be given together. MetaMask remembers the fee chosen for an account on a network, and starts the next transactions from it.
|
|
139
|
+
```json
|
|
140
|
+
{
|
|
141
|
+
"DAPPRESS_SEED_PHRASE": "word1 word2 word3 word4 word5 word6 word7 word8 word9 word10 word11 word12"
|
|
142
|
+
}
|
|
143
|
+
```
|
|
173
144
|
|
|
174
|
-
|
|
145
|
+
In CI, as an encrypted secret:
|
|
175
146
|
|
|
176
|
-
|
|
147
|
+
```yaml
|
|
148
|
+
# GitHub Actions
|
|
149
|
+
env:
|
|
150
|
+
DAPPRESS_SEED_PHRASE: ${{ secrets.DAPPRESS_SEED_PHRASE }}
|
|
151
|
+
```
|
|
177
152
|
|
|
178
|
-
|
|
179
|
-
2. `cypress.env.json`, for secrets on a development machine, such as the seed phrase.
|
|
180
|
-
3. `cypress/wallet.setup.ts`, for everything else.
|
|
181
|
-
4. The third argument of `configureDappress(on, config, options)`.
|
|
153
|
+
Read [Security](#security) before you pick that seed phrase.
|
|
182
154
|
|
|
183
|
-
|
|
184
|
-
|---|---|---|
|
|
185
|
-
| `metamaskVersion` | `DAPPRESS_METAMASK_VERSION` | `13.50.0`. The build is downloaded from MetaMask's GitHub releases on first run and cached in `~/.cache/dappress`. |
|
|
186
|
-
| `seedPhrase` | `DAPPRESS_SEED_PHRASE` | None. Dappress makes a new wallet for each run, which nobody else knows and which is never written anywhere. |
|
|
187
|
-
| `password` | `DAPPRESS_PASSWORD` | `Tester@1234`. It only protects the throwaway browser profile Cypress creates for each run. |
|
|
188
|
-
| `network` | | None. The dapp stays on the network MetaMask starts on, Ethereum mainnet. |
|
|
189
|
-
| `backupAndSync` | | `false`. Dappress turns off MetaMask's backup and sync while importing the wallet, so that an account a test adds is not restored by the next import of the same seed phrase. With `true`, MetaMask keeps saving and restoring the accounts and contacts of that phrase. |
|
|
190
|
-
| `autoSetup` | | `true`. Dappress imports or unlocks the wallet before the first test of each spec. Set to `false` to call `cy.setupMetaMask()` yourself. |
|
|
191
|
-
| `cache` | | `false`. The wallet is imported in every run, about fifteen seconds. With `true`, and a seed phrase of your own, it is imported once, in a browser Dappress opens before the run, and the resulting profile is reused by later runs, which then start by unlocking the wallet. Headed runs only: a headless run imports the wallet as usual. |
|
|
192
|
-
| `timeout` | | `20000` ms. The time allowed for MetaMask to display a request before a command fails. |
|
|
155
|
+
## Commands
|
|
193
156
|
|
|
194
|
-
###
|
|
157
|
+
### Connection
|
|
195
158
|
|
|
196
|
-
|
|
159
|
+
| Command | What it does |
|
|
160
|
+
| -------------------------------- | -------------------------------------------------------------------------------------------- |
|
|
161
|
+
| `cy.connectToDapp()` | Accepts the connection request, then switches the dapp to the network of your wallet setup. |
|
|
162
|
+
| `cy.connectToDapp({ accounts })` | Same, but connects only the listed accounts, for example `['Account 1', 'Account 2']`. |
|
|
163
|
+
| `cy.rejectConnection()` | Rejects the connection request. |
|
|
164
|
+
| `cy.disconnectFromDapp()` | Disconnects the dapp in MetaMask. The dapp receives an empty `accountsChanged`. |
|
|
165
|
+
| `cy.getAccountAddress()` | Yields the address the dapp is connected with. |
|
|
197
166
|
|
|
198
|
-
|
|
167
|
+
### Signatures and transactions
|
|
199
168
|
|
|
200
|
-
|
|
169
|
+
| Command | What it does |
|
|
170
|
+
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
171
|
+
| `cy.confirmSignature()` | Signs the message (`personal_sign`, `eth_signTypedData_*`). |
|
|
172
|
+
| `cy.rejectSignature()` | Rejects the signature request. |
|
|
173
|
+
| `cy.confirmTransaction(options?)` | Confirms the transaction, ERC-20 approvals included. Options set the spending cap or the gas fee first: see below. |
|
|
174
|
+
| `cy.rejectTransaction()` | Rejects the transaction. |
|
|
201
175
|
|
|
202
|
-
|
|
176
|
+
### Networks and tokens
|
|
203
177
|
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
178
|
+
| Command | What it does |
|
|
179
|
+
| --------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
180
|
+
| `cy.useNetwork(network?)` | Switches the dapp to a network, and adds it to MetaMask if needed. Defaults to your wallet setup. |
|
|
181
|
+
| `cy.approveNewNetwork()` | Accepts a `wallet_addEthereumChain` request. |
|
|
182
|
+
| `cy.rejectNewNetwork()` | Rejects it. |
|
|
183
|
+
| `cy.approveSwitchNetwork()` | Accepts a `wallet_switchEthereumChain` request to a network the dapp has no permission on yet. |
|
|
184
|
+
| `cy.rejectSwitchNetwork()` | Rejects it. |
|
|
185
|
+
| `cy.approveAddToken()` | Accepts a `wallet_watchAsset` request. |
|
|
186
|
+
| `cy.rejectAddToken()` | Rejects it. |
|
|
210
187
|
|
|
211
|
-
|
|
188
|
+
### Accounts and wallet
|
|
212
189
|
|
|
213
|
-
|
|
190
|
+
| Command | What it does |
|
|
191
|
+
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
|
192
|
+
| `cy.addAccount()` | Creates an account and selects it. Yields its name, for example `Account 2`. |
|
|
193
|
+
| `cy.importAccount(privateKey)` | Imports an account from a private key and selects it. Yields its name. The key stays out of the log. |
|
|
194
|
+
| `cy.switchAccount(name)` | Selects an account by its name. |
|
|
195
|
+
| `cy.lockWallet()` | Locks the wallet. Requests then wait until it is unlocked. |
|
|
196
|
+
| `cy.unlockWallet()` | Unlocks the wallet. Yields `locked` if it was locked, `unlocked` if there was nothing to do. |
|
|
197
|
+
| `cy.setupMetaMask()` | Imports or unlocks the wallet. Runs by itself before each spec, unless `autoSetup` is `false`. |
|
|
214
198
|
|
|
215
|
-
###
|
|
199
|
+
### Transaction options
|
|
216
200
|
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
201
|
+
```ts
|
|
202
|
+
// ERC-20 approval: allow the spender 2.5 tokens, whatever the dapp asked for
|
|
203
|
+
cy.confirmTransaction({ spendingCap: '2.5' });
|
|
220
204
|
|
|
221
|
-
|
|
205
|
+
// One of the fee levels MetaMask offers
|
|
206
|
+
cy.confirmTransaction({ gas: 'aggressive' });
|
|
222
207
|
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
npm run format # Prettier, on everything but the Markdown files
|
|
226
|
-
npm run check-types # TypeScript, on the sources, the scripts and the suite
|
|
227
|
-
npm test # unit tests
|
|
228
|
-
npm run build # the package, compiled into dist
|
|
208
|
+
// Custom fees, in GWEI, as in MetaMask's advanced fee form
|
|
209
|
+
cy.confirmTransaction({ gas: { maxBaseFee: 30, priorityFee: 2, gasLimit: 100000 } });
|
|
229
210
|
```
|
|
230
211
|
|
|
231
|
-
|
|
212
|
+
| Option | Value |
|
|
213
|
+
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
214
|
+
| `spendingCap` | The amount the spender may use, in tokens: `5` or `'2.5'`. Use a string to avoid rounding. Fails if the transaction is not an ERC-20 approval. |
|
|
215
|
+
| `gas` | A fee level: `'low'`, `'market'` or `'aggressive'`. On a network with no fee estimates, such as a local node, use `'networkSuggested'`. Fails if MetaMask does not offer that level. |
|
|
216
|
+
| `gas` | Or custom values: `maxBaseFee` and `priorityFee` in GWEI, and `gasLimit`. A missing field keeps MetaMask's value. EIP-1559 transactions only. |
|
|
232
217
|
|
|
233
|
-
|
|
218
|
+
Both options can be combined. MetaMask remembers the fee chosen for an account on a network and starts the next transaction from it.
|
|
234
219
|
|
|
235
|
-
|
|
236
|
-
2. Commit, then tag the commit `v<version>` and push the tag.
|
|
220
|
+
## Configuration
|
|
237
221
|
|
|
238
|
-
|
|
222
|
+
Settings come from three places:
|
|
239
223
|
|
|
240
|
-
|
|
224
|
+
- **`cypress/wallet.setup.ts`** for the network. It accepts `network` and `seedPhrase` only, and any other key is an error. Keep the seed phrase out of it, since this file is committed.
|
|
225
|
+
- **Environment variables or `cypress.env.json`** for secrets and the MetaMask version.
|
|
226
|
+
- **The third argument of `configureDappress()`** for everything else:
|
|
241
227
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
228
|
+
```ts
|
|
229
|
+
setupNodeEvents(on, config) {
|
|
230
|
+
return configureDappress(on, config, { cache: true, timeout: 30000 });
|
|
231
|
+
}
|
|
232
|
+
```
|
|
245
233
|
|
|
246
|
-
|
|
234
|
+
When a setting appears in several places, the first one found wins: environment variable, then `cypress.env.json`, then `wallet.setup.ts`, then `configureDappress()`.
|
|
247
235
|
|
|
248
|
-
|
|
236
|
+
| Option | Environment variable | Default and meaning |
|
|
237
|
+
| ----------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
238
|
+
| `network` | | None. The network `cy.connectToDapp()` and `cy.useNetwork()` switch to. |
|
|
239
|
+
| `seedPhrase` | `DAPPRESS_SEED_PHRASE` | None. A new wallet is created for each run. It is never written to disk. |
|
|
240
|
+
| `password` | `DAPPRESS_PASSWORD` | `Tester@1234`. It only protects the throwaway browser profile of the run. |
|
|
241
|
+
| `metamaskVersion` | `DAPPRESS_METAMASK_VERSION` | `13.50.0`. Downloaded from MetaMask's GitHub releases on first use, then cached. |
|
|
242
|
+
| `timeout` | | `20000` ms. How long a command waits for MetaMask to show the request. |
|
|
243
|
+
| `autoSetup` | | `true`. Set to `false` to call `cy.setupMetaMask()` yourself. |
|
|
244
|
+
| `cache` | | `false`. Importing the wallet takes about fifteen seconds per run. With `true`, Dappress imports it once and reuses the browser profile. Needs your own seed phrase and a headed run. |
|
|
245
|
+
| `backupAndSync` | | `false`. Dappress turns off MetaMask's backup and sync, so accounts added by a test do not come back on the next run. |
|
|
246
|
+
| `cacheDir` | | `~/.cache/dappress`. Where MetaMask builds and cached profiles are kept. |
|
|
249
247
|
|
|
250
|
-
|
|
251
|
-
src/index.ts configureDappress(): plugin entry point
|
|
252
|
-
src/config.ts options and wallet setup file
|
|
253
|
-
src/download.ts download and cache of MetaMask builds
|
|
254
|
-
src/browser.ts Puppeteer connection to the Cypress browser
|
|
255
|
-
src/profile.ts wallet profile built once and reused across runs
|
|
256
|
-
src/metamask-pages.ts discovery of MetaMask's pages
|
|
257
|
-
src/metamask.ts MetaMask screens: selectors and flows
|
|
258
|
-
src/page-helpers.ts wait, click and fill primitives with fallback selectors
|
|
259
|
-
src/actions.ts Cypress tasks behind the commands
|
|
260
|
-
src/support.ts cy.* commands
|
|
261
|
-
src/types.ts types of the public API
|
|
262
|
-
conformance/ conformance suite
|
|
263
|
-
```
|
|
248
|
+
## Security
|
|
264
249
|
|
|
265
|
-
|
|
250
|
+
- **Use a seed phrase made for testing**, funded on test networks only.
|
|
251
|
+
- **Avoid well-known phrases**, such as the Hardhat or Anvil development mnemonic. MetaMask restores the accounts other people saved for them, and your wallet will not be the one you expect.
|
|
252
|
+
- **Secrets stay in Node.js.** The seed phrase and the password never reach the browser or the Cypress log.
|
|
253
|
+
- **With `cache: true`**, `~/.cache/dappress/profiles` holds the wallet's encrypted vault. Treat it like the seed phrase: keep it on the machine, and keep it out of any CI cache that other people or workflows can restore.
|
|
266
254
|
|
|
267
255
|
## Troubleshooting
|
|
268
256
|
|
|
269
|
-
- **Cypress exits immediately with `MODULE_NOT_FOUND`.**
|
|
270
|
-
- **"MetaMask showed no confirmation".** The dapp sent no request, or
|
|
271
|
-
- **Adding or importing an account never finishes.** `chromeWebSecurity: false` is set in
|
|
272
|
-
- **The wallet shows accounts you did not create.** The seed phrase is used elsewhere, and MetaMask restored what
|
|
257
|
+
- **Cypress exits immediately with `MODULE_NOT_FOUND`.** Your terminal sets `ELECTRON_RUN_AS_NODE=1`, as some IDEs do. Run `env -u ELECTRON_RUN_AS_NODE npx cypress run …`.
|
|
258
|
+
- **"MetaMask showed no confirmation".** The dapp sent no request, or the network's RPC endpoint is unreachable.
|
|
259
|
+
- **Adding or importing an account never finishes.** `chromeWebSecurity: false` is set in your Cypress config. MetaMask then cannot start the snaps its account screens wait for. Remove that setting.
|
|
260
|
+
- **The wallet shows accounts you did not create.** The seed phrase is used elsewhere, and MetaMask restored what it saved for it. Use a phrase made for your tests, or none.
|
|
261
|
+
- **"MetaMask extension not found in the browser".** The browser did not load the extension. Most often it is Google Chrome 137 or later, which no longer can. Use Chrome for Testing: see [step 5](#5-get-a-browser-that-loads-extensions).
|
|
273
262
|
|
|
274
|
-
##
|
|
263
|
+
## Contributing
|
|
275
264
|
|
|
276
|
-
|
|
265
|
+
How Dappress works, how to run the conformance suite, update to a new MetaMask release and publish a version: see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
277
266
|
|
|
278
267
|
## License
|
|
279
268
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dappress",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.1",
|
|
4
4
|
"description": "MetaMask automation for Cypress: load the real extension, import a test wallet, answer dapp requests with cy.* commands. Tracks the latest MetaMask release.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Benjamin Lassaut",
|