You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
289 lines
10 KiB
289 lines
10 KiB
<p align="center">
|
|
<img src="./apps/remix-ide/src/assets/img/icon.png" alt="Remix Logo" width="200"/>
|
|
</p>
|
|
<h3 align="center">Remix Project</h3>
|
|
|
|
<div align="center">
|
|
|
|
|
|
[](https://circleci.com/gh/ethereum/remix-project)
|
|
[](https://remix-ide.readthedocs.io/en/latest/index.html)
|
|
[](https://github.com/ethereum/remix-project/blob/master/CONTRIBUTING.md)
|
|
[](https://github.com/ethereum/remix-project/blob/master/CONTRIBUTING.md)
|
|
[](https://github.com/ethereum/awesome-remix)
|
|
|
|
[](https://discord.gg/q4vS2GVn)
|
|
[](https://twitter.com/ethereumremix)
|
|
|
|
</div>
|
|
|
|
## Remix Project
|
|
|
|
**Remix Project** is a rich toolset including Remix IDE, a comprehensive smart contract development tool. The Remix Project also includes Remix Plugin Engine and Remix Libraries which are low-level tools for wider use.
|
|
|
|
## Remix IDE
|
|
**Remix IDE** is used for the entire journey of contract development by users of any knowledge level. It fosters a fast development cycle and has a rich set of plugins with intuitive GUIs. The IDE comes in 2 flavors and a VSCode extension:
|
|
|
|
**Remix Online IDE**, see: [https://remix.ethereum.org](https://remix.ethereum.org)
|
|
|
|
:point_right: Supported browsers: Firefox v100.0.1 & Chrome v101.0.4951.64. No support for Remix's use on tablets or smartphones or telephones.
|
|
|
|
**Remix Desktop IDE**, see releases: [https://github.com/ethereum/remix-desktop/releases](https://github.com/ethereum/remix-desktop/releases)
|
|
|
|
|
|
|
|
**VSCode extension**, see: [Ethereum-Remix](https://marketplace.visualstudio.com/items?itemName=RemixProject.ethereum-remix)
|
|
|
|
## Remix libraries
|
|
Remix libraries are essential for Remix IDE's native plugins. Read more about libraries [here](libs/README.md)
|
|
|
|
## Offline Usage
|
|
|
|
The `gh-pages` branch of [remix-live](https://github.com/ethereum/remix-live) always has the latest stable build of Remix. It contains a ZIP file with the entire build. Download it to use offline.
|
|
|
|
Note: It contains the latest supported version of Solidity available at the time of the packaging. Other compiler versions can be used online only.
|
|
|
|
|
|
## Setup
|
|
|
|
* Install **Yarn** and **Node.js**. See [Guide for NodeJs](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and [Yarn install](https://classic.yarnpkg.com/lang/en/docs/install)<br/>
|
|
*Supported versions:*
|
|
```bash
|
|
"engines": {
|
|
"node": "^20.0.0",
|
|
"npm": "^6.14.15"
|
|
}
|
|
```
|
|
* Install [Nx CLI](https://nx.dev/using-nx/nx-cli) globally to enable running **nx executable commands**.
|
|
```bash
|
|
yarn global add nx
|
|
```
|
|
* Clone the GitHub repository (`wget` need to be installed first):
|
|
|
|
```bash
|
|
git clone https://github.com/ethereum/remix-project.git
|
|
```
|
|
* Build and Run `remix-project`:
|
|
|
|
1. Move to project directory: `cd remix-project`
|
|
2. Install dependencies: `yarn install` or simply run `yarn`
|
|
3. Build Remix libraries: `yarn run build:libs`
|
|
4. Build Remix project: `yarn build`
|
|
5. Build and run project server: `yarn serve`. Optionally, run `yarn serve:hot` to enable hot module reload for frontend updates.
|
|
|
|
Open `http://127.0.0.1:8080` in your browser to load Remix IDE locally.
|
|
|
|
Go to your `text editor` and start developing. The browser will automatically refresh when files are saved.
|
|
|
|
## Production Build
|
|
To generate react production builds for remix-project.
|
|
```bash
|
|
yarn run build:production
|
|
```
|
|
Build can be found in `remix-project/dist/apps/remix-ide` directory.
|
|
|
|
```bash
|
|
yarn run serve:production
|
|
```
|
|
Production build will be served by default to `http://localhost:8080/` or `http://127.0.0.1:8080/`
|
|
|
|
## Docker:
|
|
|
|
Prerequisites:
|
|
* Docker (https://docs.docker.com/desktop/)
|
|
* Docker Compose (https://docs.docker.com/compose/install/)
|
|
|
|
### Run with docker
|
|
|
|
If you want to run the latest changes that are merged into the master branch then run:
|
|
|
|
```
|
|
docker pull remixproject/remix-ide:latest
|
|
docker run -p 8080:80 remixproject/remix-ide:latest
|
|
```
|
|
|
|
If you want to run the latest remix-live release run.
|
|
```
|
|
docker pull remixproject/remix-ide:remix_live
|
|
docker run -p 8080:80 remixproject/remix-ide:remix_live
|
|
```
|
|
|
|
### Run with docker-compose:
|
|
|
|
To run locally without building you only need docker-compose.yaml file and you can run:
|
|
|
|
```
|
|
docker-compose pull
|
|
docker-compose up -d
|
|
```
|
|
|
|
Then go to http://localhost:8080 and you can use your Remix instance.
|
|
|
|
To fetch the docker-compose file without cloning this repo run:
|
|
```
|
|
curl https://raw.githubusercontent.com/ethereum/remix-project/master/docker-compose.yaml > docker-compose.yaml
|
|
```
|
|
|
|
### Troubleshooting
|
|
|
|
If you have trouble building the project, make sure that you have the correct version of `node`, `npm` and `nvm`. Also, ensure [Nx CLI](https://nx.dev/using-nx/nx-cli) is installed globally.
|
|
|
|
Run:
|
|
|
|
```bash
|
|
node --version
|
|
npm --version
|
|
nvm --version
|
|
```
|
|
|
|
In Debian-based OS such as Ubuntu 14.04LTS, you may need to run `apt-get install build-essential`. After installing `build-essential`, run `npm rebuild`.
|
|
|
|
## Unit Testing
|
|
|
|
Run the unit tests using library name like: `nx test <project-name>`
|
|
|
|
For example, to run unit tests of `remix-analyzer`, use `nx test remix-analyzer`
|
|
|
|
## Browser Testing
|
|
|
|
To run the Selenium tests via Nightwatch:
|
|
|
|
- Install Selenium for the first time: `yarn run selenium-install`
|
|
- Run a selenium server: `yarn run selenium`
|
|
- Build & Serve Remix: `yarn serve`
|
|
- Run all the end-to-end tests:
|
|
|
|
for Firefox: `yarn run nightwatch_local_firefox`, or
|
|
|
|
for Google Chrome: `yarn run nightwatch_local_chrome`
|
|
- Run a specific test case instead, use a command like this:
|
|
|
|
- yarn run nightwatch_local_ballot
|
|
|
|
The package.json file contains a list of all the tests you can run.
|
|
|
|
**NOTE:**
|
|
|
|
- **The `ballot` tests suite** requires running `ganache-cli` locally.
|
|
|
|
- **The `remixd` tests suite** requires running `remixd` locally.
|
|
|
|
- **The `gist` tests suite** requires specifying a GitHub access token in **.env file**.
|
|
```
|
|
gist_token = <token> // token should have permission to create a gist
|
|
```
|
|
|
|
### Using 'select_test' for locally running specific tests
|
|
|
|
There is a script to allow selecting the browser and a specific test to run:
|
|
|
|
```
|
|
yarn run select_test
|
|
```
|
|
|
|
You need to have
|
|
|
|
- selenium running
|
|
|
|
- the IDE running
|
|
|
|
- optionally have remixd or ganache running
|
|
|
|
### Splitting tests with groups
|
|
|
|
Groups can be used to group tests in a test file together. The advantage is you can avoid running long test files when you want to focus on a specific set of tests within a test file.x
|
|
|
|
These groups only apply to the test file, not across all test files. So for example group1 in the ballot is not related to a group1 in another test file.
|
|
|
|
Running a group only runs the tests marked as belonging to the group + all the tests in the test file that do not have a group tag. This way you can have tests that run for all groups, for example, to perform common actions.
|
|
|
|
There is no need to number the groups in a certain order. The number of the group is arbitrary.
|
|
|
|
A test can have multiple group tags, this means that this test will run in different groups.
|
|
|
|
You should write your tests so they can be executed in groups and not depend on other groups.
|
|
|
|
To do this you need to:
|
|
|
|
- Add a group to tag to a test, they are formatted as #group followed by a number: so it becomes #group1, #group220, #group4. Any number will do. You don't have to do it in a specific order.
|
|
|
|
```
|
|
'Should generate test file #group1': function (browser: NightwatchBrowser) {
|
|
browser.waitForElementPresent('*[data-id="verticalIconsKindfilePanel"]')
|
|
```
|
|
|
|
- add '@disabled': true to the test file you want to split:
|
|
|
|
```
|
|
module.exports = {
|
|
'@disabled': true,
|
|
before: function (browser: NightwatchBrowser, done: VoidFunction) {
|
|
init(browser, done) // , 'http://localhost:8080', false)
|
|
},
|
|
```
|
|
- change package JSON to locally run all group tests:
|
|
|
|
```
|
|
"nightwatch_local_debugger": "yarn run build:e2e && nightwatch --config dist/apps/remix-ide-e2e/nightwatch.js dist/apps/remix-ide-e2e/src/tests/debugger_*.spec.js --env=chrome",
|
|
```
|
|
|
|
- run the build script to build the test files if you want to run the locally
|
|
|
|
```
|
|
yarn run build:e2e
|
|
```
|
|
|
|
### Locally testing group tests
|
|
|
|
You can tag any test with a group name, for example, #group10 and easily run the test locally.
|
|
|
|
- make sure you have nx installed globally
|
|
- group tests are run like any other test, just specify the correct group number
|
|
|
|
#### method 1
|
|
|
|
This script will give you an options menu, just select the test you want
|
|
```
|
|
yarn run select_test
|
|
```
|
|
#### method 2
|
|
|
|
```
|
|
yarn run group_test --test=debugger --group=10 --env=chromeDesktop
|
|
```
|
|
- specify chromeDesktop to see the browser action, use 'chrome' to run it headless
|
|
|
|
### Run the same (flaky) test across all instances in CircleCI
|
|
|
|
In CircleCI all tests are divided across instances to run in parallel.
|
|
You can also run 1 or more tests simultaneously across all instances.
|
|
This way the pipeline can easily be restarted to check if a test is flaky.
|
|
|
|
For example:
|
|
|
|
```
|
|
'Static Analysis run with remixd #group3 #flaky': function (browser) {
|
|
```
|
|
|
|
Now, the group3 of this test will be executed in firefox and chrome 80 times.
|
|
If you mark more groups in other tests they will also be executed.
|
|
|
|
**CONFIGURATION**
|
|
|
|
It's important to set a parameter in the .circleci/config.yml, set it to false then the normal tests will run.
|
|
Set it to true to run only tests marked with flaky.
|
|
```
|
|
parameters:
|
|
run_flaky_tests:
|
|
type: boolean
|
|
default: true
|
|
```
|
|
|
|
## Important Links
|
|
|
|
- Official website: https://remix-project.org
|
|
- Official documentation: https://remix-ide.readthedocs.io/en/latest/
|
|
- Curated list of Remix resources: https://github.com/ethereum/awesome-remix
|
|
- Medium: https://medium.com/remix-ide
|
|
- Twitter: https://twitter.com/ethereumremix
|
|
- Join Discord: https://discord.gg/q4vS2GVn
|
|
|