mirror of
https://github.com/kremalicious/metamask-extension.git
synced 2024-11-23 02:10:12 +01:00
26f6ae4c7c
* Add testing documentation * Implement diff filtering by regex * change to relative import
152 lines
12 KiB
Markdown
152 lines
12 KiB
Markdown
# MetaMask Browser Extension
|
|
|
|
You can find the latest version of MetaMask on [our official website](https://metamask.io/). For help using MetaMask, visit our [User Support Site](https://metamask.zendesk.com/hc/en-us).
|
|
|
|
For [general questions](https://community.metamask.io/c/learn/26), [feature requests](https://community.metamask.io/c/feature-requests-ideas/13), or [developer questions](https://community.metamask.io/c/developer-questions/11), visit our [Community Forum](https://community.metamask.io/).
|
|
|
|
MetaMask supports Firefox, Google Chrome, and Chromium-based browsers. We recommend using the latest available browser version.
|
|
|
|
For up to the minute news, follow our [Twitter](https://twitter.com/metamask) or [Medium](https://medium.com/metamask) pages.
|
|
|
|
To learn how to develop MetaMask-compatible applications, visit our [Developer Docs](https://metamask.github.io/metamask-docs/).
|
|
|
|
To learn how to contribute to the MetaMask project itself, visit our [Internal Docs](https://github.com/MetaMask/metamask-extension/tree/develop/docs).
|
|
|
|
## Building locally
|
|
|
|
- Install [Node.js](https://nodejs.org) version 16
|
|
- If you are using [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) (recommended) running `nvm use` will automatically choose the right node version for you.
|
|
- Install [Yarn v3](https://yarnpkg.com/getting-started/install)
|
|
- Install dependencies: `yarn`
|
|
- Copy the `.metamaskrc.dist` file to `.metamaskrc`
|
|
- Replace the `INFURA_PROJECT_ID` value with your own personal [Infura Project ID](https://infura.io/docs).
|
|
- If debugging MetaMetrics, you'll need to add a value for `SEGMENT_WRITE_KEY` [Segment write key](https://segment.com/docs/connections/find-writekey/), see [Developing on MetaMask - Segment](./development/README.md#segment).
|
|
- If debugging unhandled exceptions, you'll need to add a value for `SENTRY_DSN` [Sentry Dsn](https://docs.sentry.io/product/sentry-basics/dsn-explainer/), see [Developing on MetaMask - Sentry](./development/README.md#sentry).
|
|
- Optionally, replace the `PASSWORD` value with your development wallet password to avoid entering it each time you open the app.
|
|
- Build the project to the `./dist/` folder with `yarn dist`.
|
|
- Optionally, you may run `yarn start` to run dev mode.
|
|
|
|
Uncompressed builds can be found in `/dist`, compressed builds can be found in `/builds` once they're built.
|
|
|
|
See the [build system readme](./development/build/README.md) for build system usage information.
|
|
|
|
## Git Hooks
|
|
|
|
To get quick feedback from our shared code quality fitness functions before committing the code, you can install our git hooks with Husky.
|
|
|
|
`$ yarn githooks:install`
|
|
|
|
You can read more about them in our [testing documentation](./docs/testing.md#fitness-functions-measuring-progress-in-code-quality-and-preventing-regressions-using-custom-git-hooks).
|
|
|
|
## Contributing
|
|
|
|
### Development builds
|
|
|
|
To start a development build (e.g. with logging and file watching) run `yarn start`.
|
|
|
|
#### React and Redux DevTools
|
|
|
|
To start the [React DevTools](https://github.com/facebook/react-devtools), run `yarn devtools:react` with a development build installed in a browser. This will open in a separate window; no browser extension is required.
|
|
|
|
To start the [Redux DevTools Extension](https://github.com/reduxjs/redux-devtools/tree/main/extension):
|
|
|
|
- Install the package `remotedev-server` globally (e.g. `yarn global add remotedev-server`)
|
|
- Install the Redux Devtools extension.
|
|
- Open the Redux DevTools extension and check the "Use custom (local) server" checkbox in the Remote DevTools Settings, using the default server configuration (host `localhost`, port `8000`, secure connection checkbox unchecked).
|
|
|
|
Then run the command `yarn devtools:redux` with a development build installed in a browser. This will enable you to use the Redux DevTools extension to inspect MetaMask.
|
|
|
|
To create a development build and run both of these tools simultaneously, run `yarn start:dev`.
|
|
|
|
#### Test Dapp
|
|
|
|
[This test site](https://metamask.github.io/test-dapp/) can be used to execute different user flows.
|
|
|
|
### Running Unit Tests and Linting
|
|
|
|
Run unit tests and the linter with `yarn test`. To run just unit tests, run `yarn test:unit`.
|
|
|
|
You can run the linter by itself with `yarn lint`, and you can automatically fix some lint problems with `yarn lint:fix`. You can also run these two commands just on your local changes to save time with `yarn lint:changed` and `yarn lint:changed:fix` respectively.
|
|
|
|
For Jest debugging guide using Node.js, see [docs/tests/jest.md](docs/tests/jest.md).
|
|
|
|
### Running E2E Tests
|
|
|
|
Our e2e test suite can be run on either Firefox or Chrome.
|
|
|
|
1. **required** `yarn build:test` to create a test build.
|
|
2. run tests, targetting the browser:
|
|
|
|
- Firefox e2e tests can be run with `yarn test:e2e:firefox`.
|
|
- Chrome e2e tests can be run with `yarn test:e2e:chrome`. The `chromedriver` package major version must match the major version of your local Chrome installation. If they don't match, update whichever is behind before running Chrome e2e tests.
|
|
|
|
These test scripts all support additional options, which might be helpful for debugging. Run the script with the flag `--help` to see all options.
|
|
|
|
#### Running a single e2e test
|
|
|
|
Single e2e tests can be run with `yarn test:e2e:single test/e2e/tests/TEST_NAME.spec.js` along with the options below.
|
|
|
|
```console
|
|
--browser Set the browser used; either 'chrome' or 'firefox'.
|
|
[string] [choices: "chrome", "firefox"]
|
|
--debug Run tests in debug mode, logging each driver interaction
|
|
[boolean] [default: false]
|
|
--retries Set how many times the test should be retried upon failure.
|
|
[number] [default: 0]
|
|
--leave-running Leaves the browser running after a test fails, along with
|
|
anything else that the test used (ganache, the test dapp,
|
|
etc.) [boolean] [default: false]
|
|
```
|
|
|
|
For example, to run the `account-details` tests using Chrome, with debug logging and with the browser set to remain open upon failure, you would use:
|
|
`yarn test:e2e:single test/e2e/tests/account-details.spec.js --browser=chrome --debug --leave-running`
|
|
|
|
### Changing dependencies
|
|
|
|
Whenever you change dependencies (adding, removing, or updating, either in `package.json` or `yarn.lock`), there are various files that must be kept up-to-date.
|
|
|
|
- `yarn.lock`:
|
|
- Run `yarn` again after your changes to ensure `yarn.lock` has been properly updated.
|
|
- Run `yarn lint:lockfile:dedupe:fix` to remove duplicate dependencies from the lockfile.
|
|
- The `allow-scripts` configuration in `package.json`
|
|
- Run `yarn allow-scripts auto` to update the `allow-scripts` configuration automatically. This config determines whether the package's install/postinstall scripts are allowed to run. Review each new package to determine whether the install script needs to run or not, testing if necessary.
|
|
- Unfortunately, `yarn allow-scripts auto` will behave inconsistently on different platforms. macOS and Windows users may see extraneous changes relating to optional dependencies.
|
|
- The LavaMoat policy files. The _tl;dr_ is to run `yarn lavamoat:auto` to update these files, but there can be devils in the details:
|
|
- There are two sets of LavaMoat policy files:
|
|
- The production LavaMoat policy files (`lavamoat/browserify/*/policy.json`), which are re-generated using `yarn lavamoat:background:auto`. Add `--help` for usage.
|
|
- These should be regenerated whenever the production dependencies for the background change.
|
|
- The build system LavaMoat policy file (`lavamoat/build-system/policy.json`), which is re-generated using `yarn lavamoat:build:auto`.
|
|
- This should be regenerated whenever the dependencies used by the build system itself change.
|
|
- Whenever you regenerate a policy file, review the changes to determine whether the access granted to each package seems appropriate.
|
|
- Unfortunately, `yarn lavamoat:auto` will behave inconsistently on different platforms.
|
|
macOS and Windows users may see extraneous changes relating to optional dependencies.
|
|
- If you keep getting policy failures even after regenerating the policy files, try regenerating the policies after a clean install by doing:
|
|
- `rm -rf node_modules/ && yarn && yarn lavamoat:auto`
|
|
- Keep in mind that any kind of dynamic import or dynamic use of globals may elude LavaMoat's static analysis.
|
|
Refer to the LavaMoat documentation or ask for help if you run into any issues.
|
|
|
|
## Architecture
|
|
|
|
- [Visual of the controller hierarchy and dependencies as of summer 2022.](https://gist.github.com/rekmarks/8dba6306695dcd44967cce4b6a94ae33)
|
|
- [Visual of the entire codebase.](https://mango-dune-07a8b7110.1.azurestaticapps.net/?repo=metamask%2Fmetamask-extension)
|
|
|
|
[][1]
|
|
|
|
## Other Docs
|
|
|
|
- [How to add custom build to Chrome](./docs/add-to-chrome.md)
|
|
- [How to add custom build to Firefox](./docs/add-to-firefox.md)
|
|
- [How to add a new translation to MetaMask](./docs/translating-guide.md)
|
|
- [Publishing Guide](./docs/publishing.md)
|
|
- [How to use the TREZOR emulator](./docs/trezor-emulator.md)
|
|
- [Developing on MetaMask](./development/README.md)
|
|
- [How to generate a visualization of this repository's development](./development/gource-viz.sh)
|
|
|
|
## Dapp Developer Resources
|
|
|
|
- [Extend MetaMask's features w/ MetaMask Snaps.](https://docs.metamask.io/guide/snaps.html)
|
|
- [Prompt your users to add and switch to a new network.](https://medium.com/metamask/connect-users-to-layer-2-networks-with-the-metamask-custom-networks-api-d0873fac51e5)
|
|
- [Change the logo that appears when your dapp connects to MetaMask.](https://docs.metamask.io/guide/defining-your-icon.html)
|
|
|
|
[1]: http://www.nomnoml.com/#view/%5B%3Cactor%3Euser%5D%0A%0A%5Bmetamask-ui%7C%0A%20%20%20%5Btools%7C%0A%20%20%20%20%20react%0A%20%20%20%20%20redux%0A%20%20%20%20%20thunk%0A%20%20%20%20%20ethUtils%0A%20%20%20%20%20jazzicon%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20account-detail%0A%20%20%20%20%20accounts%0A%20%20%20%20%20locked-screen%0A%20%20%20%20%20restore-vault%0A%20%20%20%20%20identicon%0A%20%20%20%20%20config%0A%20%20%20%20%20info%0A%20%20%20%5D%0A%20%20%20%5Breducers%7C%0A%20%20%20%20%20app%0A%20%20%20%20%20metamask%0A%20%20%20%20%20identities%0A%20%20%20%5D%0A%20%20%20%5Bactions%7C%0A%20%20%20%20%20%5BbackgroundConnection%5D%0A%20%20%20%5D%0A%20%20%20%5Bcomponents%5D%3A-%3E%5Bactions%5D%0A%20%20%20%5Bactions%5D%3A-%3E%5Breducers%5D%0A%20%20%20%5Breducers%5D%3A-%3E%5Bcomponents%5D%0A%5D%0A%0A%5Bweb%20dapp%7C%0A%20%20%5Bui%20code%5D%0A%20%20%5Bweb3%5D%0A%20%20%5Bmetamask-inpage%5D%0A%20%20%0A%20%20%5B%3Cactor%3Eui%20developer%5D%0A%20%20%5Bui%20developer%5D-%3E%5Bui%20code%5D%0A%20%20%5Bui%20code%5D%3C-%3E%5Bweb3%5D%0A%20%20%5Bweb3%5D%3C-%3E%5Bmetamask-inpage%5D%0A%5D%0A%0A%5Bmetamask-background%7C%0A%20%20%5Bprovider-engine%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bid%20store%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%3E%5Bhooked%20wallet%20subprovider%5D%0A%20%20%5Bhooked%20wallet%20subprovider%5D%3C-%3E%5Bid%20store%5D%0A%20%20%5Bconfig%20manager%7C%0A%20%20%20%20%5Brpc%20configuration%5D%0A%20%20%20%20%5Bencrypted%20keys%5D%0A%20%20%20%20%5Bwallet%20nicknames%5D%0A%20%20%5D%0A%20%20%0A%20%20%5Bprovider-engine%5D%3C-%5Bconfig%20manager%5D%0A%20%20%5Bid%20store%5D%3C-%3E%5Bconfig%20manager%5D%0A%5D%0A%0A%5Buser%5D%3C-%3E%5Bmetamask-ui%5D%0A%0A%5Buser%5D%3C%3A--%3A%3E%5Bweb%20dapp%5D%0A%0A%5Bmetamask-contentscript%7C%0A%20%20%5Bplugin%20restart%20detector%5D%0A%20%20%5Brpc%20passthrough%5D%0A%5D%0A%0A%5Brpc%20%7C%0A%20%20%5Bethereum%20blockchain%20%7C%0A%20%20%20%20%5Bcontracts%5D%0A%20%20%20%20%5Baccounts%5D%0A%20%20%5D%0A%5D%0A%0A%5Bweb%20dapp%5D%3C%3A--%3A%3E%5Bmetamask-contentscript%5D%0A%5Bmetamask-contentscript%5D%3C-%3E%5Bmetamask-background%5D%0A%5Bmetamask-background%5D%3C-%3E%5Bmetamask-ui%5D%0A%5Bmetamask-background%5D%3C-%3E%5Brpc%5D%0A
|