+
๐ Remix Project
+
+
-[](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://github.com/ethereum/remix-project/blob/master/LICENSE)
-[](https://discord.gg/mh9hFCKkEq)
-[](https://x.com/ethereumremix)
+[](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://github.com/ethereum/remix-project/blob/master/LICENSE)
+[](https://discord.gg/mh9hFCKkEq)
+[](https://x.com/ethereumremix)
-## Remix Project
+---
+
+## ๐ Remix Project
+
+**Remix Project** is a powerful toolset that includes Remix IDE, a comprehensive smart contract development environment. It also includes Remix Plugin Engine and Remix Libraries, which are essential tools for broader usage.
+
+---
-**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
-**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 IDE** is designed for the entire smart contract development lifecycle, catering to users of all skill levels. It promotes a fast development cycle and provides a rich set of plugins with intuitive GUIs. The IDE comes in two versions and a VSCode extension:
-**Remix Online IDE**, see: [https://remix.ethereum.org](https://remix.ethereum.org)
+๐ **Remix Online IDE**: [๐ Open in browser](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.
+๐ **Supported browsers**:
+โ
Firefox `v100.0.1+`
+โ
Chrome `v101.0.4951.64+`
+โ ๏ธ *Not supported on tablets, smartphones, or telephones.*
-**Remix Desktop IDE**, see releases: [https://github.com/ethereum/remix-desktop/releases](https://github.com/ethereum/remix-desktop/releases)
+๐ฅ๏ธ **Remix Desktop IDE**: [๐ Download here](https://github.com/ethereum/remix-desktop/releases)
+๐ธ **Screenshot of Remix IDE**
+---
-## Remix libraries
-Remix libraries are essential for Remix IDE's native plugins. Read more about libraries [here](libs/README.md)
+## ๐ Remix Libraries
-## Offline Usage
+Remix libraries are essential for Remix IDE's native plugins. Read more about libraries [here](libs/README.md).
-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.
+## ๐ Offline Usage
+The `gh-pages` branch of [remix-live](https://github.com/ethereum/remix-live) always contains the **latest stable build** of Remix.
+It includes a **ZIP file** with the entire build, allowing you to use Remix IDE offline.
-## Setup
+โ ๏ธ **Note**:
+- The ZIP file contains the **latest supported Solidity version** available at the time of packaging.
+- Other Solidity compiler versions can only be used **online**.
-* 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)
-*Supported versions:*
-```bash
+---
+
+## โ๏ธ Setup
+
+๐ **Install Dependencies**
+- Install **Yarn** and **Node.js**:
+ ๐ [Guide for NodeJs](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
+ ๐ [Guide for Yarn](https://classic.yarnpkg.com/lang/en/docs/install)
+
+โ
**Supported versions**:
+```json
"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**.
+
+๐ **Install Nx CLI globally** to enable running `nx` commands:
```bash
yarn global add nx
```
-* Clone the GitHub repository (`wget` need to be installed first):
+๐ฝ **Clone the GitHub repository**:
```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 to reload for frontend updates.
+---
+
+## ๐ Build and Run Remix Project
+
+1๏ธโฃ **Move to the project directory**:
+```bash
+cd remix-project
+```
+
+2๏ธโฃ **Install dependencies**:
+```bash
+yarn install # or simply run "yarn"
+```
+
+3๏ธโฃ **Build Remix libraries**:
+```bash
+yarn run build:libs
+```
+
+4๏ธโฃ **Build the Remix project**:
+```bash
+yarn build
+```
+
+5๏ธโฃ **Run the project server**:
+```bash
+yarn serve
+```
+๐ก *For hot module reload support, use:*
+```bash
+yarn serve:hot
+```
+
+๐ **Open Remix IDE in your browser**:
+```bash
+http://127.0.0.1:8080
+```
+
+๐ **Start developing in your text editor** โ changes will be applied automatically in the browser.
-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
-## Production Build
-To generate react production builds for remix-project.
+To generate a **production build** for Remix IDE:
```bash
yarn run build:production
```
-Build can be found in `remix-project/dist/apps/remix-ide` directory.
+The build will be available in:
+```bash
+remix-project/dist/apps/remix-ide
+```
+To **serve the production build**, run:
```bash
yarn run serve:production
```
-Production build will be served by default to `http://localhost:8080/` or `http://127.0.0.1:8080/`
-## Docker:
+๐ **Production build will be available at**:
+- ๐ `http://localhost:8080/`
+- ๐ `http://127.0.0.1:8080/`
-Prerequisites:
-* Docker (https://docs.docker.com/desktop/)
-* Docker Compose (https://docs.docker.com/compose/install/)
+---
-### Run with docker
+## ๐ณ Docker Setup
-If you want to run the latest changes that are merged into the master branch then run:
+### โ
Prerequisites
-```
+Before running Remix with Docker, install:
+- ๐๏ธ **Docker** โ [Installation Guide](https://docs.docker.com/desktop/)
+- ๐ **Docker Compose** โ [Installation Guide](https://docs.docker.com/compose/install/)
+
+---
+
+### ๐ Run with Docker
+
+To run the latest **master branch build**, use:
+```bash
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.
-```
+To run the **latest remix-live release**, use:
+```bash
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:
+### ๐๏ธ Run with Docker-Compose
-```
+To run Remix **locally without building**, just download `docker-compose.yaml` and execute:
+```bash
docker-compose pull
docker-compose up -d
```
-Then go to http://localhost:8080 and you can use your Remix instance.
+๐ **Access Remix IDE at:**
+๐ [http://localhost:8080](http://localhost:8080)
-To fetch the docker-compose file without cloning this repo run:
-```
+To fetch the `docker-compose.yaml` file **without cloning** the repo:
+```bash
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.
+## ๐ ๏ธ Troubleshooting
-Run:
+If you experience build issues, check that you have the **correct versions** of:
+- Node.js
+- npm
+- nvm
+- Nx CLI
+๐ **Check versions with:**
```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
`
-
-For example, to run unit tests of `remix-analyzer`, use `nx test remix-analyzer`
+For **Debian-based systems (Ubuntu 14.04LTS+):**
+```bash
+sudo apt-get install build-essential
+npm rebuild
+```
-## Browser Testing
+---
-To run the tests via Nightwatch:
+## ๐งช Unit Testing
- - Install webdrivers for the first time: `yarn install_webdriver`
- - Build & Serve Remix: `yarn serve`
+Run **unit tests** for a specific library:
+```bash
+nx test
+```
+๐ Example:
+```bash
+nx test remix-analyzer
+```
-
-**NOTE:**
+---
-- **The `ballot` tests suite** requires running `ganache` locally.
+## ๐ Browser Testing
-- **The `remixd` tests suite** requires running `remixd` locally.
+To run **browser-based tests** using Nightwatch:
-- **The `gist` tests suite** requires specifying a GitHub access token in **.env file**.
-```
- gist_token = // token should have permission to create a gist
+1๏ธโฃ **Install WebDrivers** (for the first time):
+```bash
+yarn install_webdriver
```
-There is a script to allow selecting the browser and a specific test to run:
-
-```
-yarn run select_test
+2๏ธโฃ **Build & Serve Remix:**
+```bash
+yarn serve
```
-You need to have
+---
-- selenium running
+## โ ๏ธ Important Notes
-- the IDE running
+- ๐๏ธ **The `ballot` test suite** requires running **Ganache** locally.
+- ๐ **The `remixd` test suite** requires running **remixd** locally.
+- ๐ **The `gist` test suite** requires a **GitHub access token** in the `.env` file:
-- optionally have remixd or ganache running
-
-### Splitting tests with groups
+```bash
+gist_token = # Token must have permission to create a gist
+```
-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.
+### ๐ฏ Select a Specific Test
-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.
+To select a specific browser and test, use:
+```bash
+yarn run select_test
+```
-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.
+๐ **Prerequisites:**
+โ๏ธ Selenium must be running
+โ๏ธ The IDE must be running
+โ๏ธ (Optional) `remixd` or `ganache` should be running
-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.
+## ๐ Splitting Tests with Groups
-You should write your tests so they can be executed in groups and not depend on other groups.
+You can group tests within a test file to **run only a specific set of tests**.
-To do this you need to:
+๐ **Key points:**
+- Group numbers are **file-specific** (e.g., `group1` in `ballot` โ `group1` in another test file).
+- Running a group executes **only the marked tests** + ungrouped tests from the file.
+- You **don't need sequential numbering** (`#group1`, `#group220`, `#group4` are all valid).
+- A test can belong to **multiple groups**.
+- Tests should be **independent** of each other.
-- 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.
+๐ **How to tag a test with a group:**
-```
+```javascript
'Should generate test file #group1': function (browser: NightwatchBrowser) {
browser.waitForElementPresent('*[data-id="verticalIconsKindfilePanel"]')
```
-- add '@disabled': true to the test file you want to split:
+---
-```
+## ๐ Enable Group Testing
+
+To **split tests into groups**, follow these steps:
+
+1๏ธโฃ **Disable the entire test file** by adding this to the test module:
+```javascript
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",
+2๏ธโฃ **Modify the `package.json` file** to run all group tests:
+```json
+"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
-
-```
+3๏ธโฃ **Build test files** before running locally:
+```bash
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.
+## ๐ Locally Testing Grouped Tests
-- make sure you have nx installed globally
-- group tests are run like any other test, just specify the correct group number
+To **run a specific test group locally**, use:
-#### method 1
-
-This script will give you an options menu, just select the test you want
-```
+```bash
yarn run select_test
```
-### Run the same (flaky) test across all instances in CircleCI
+๐ **Ensure you have:**
+โ๏ธ `nx` installed globally
+โ๏ธ The correct group number specified
-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:
+## ๐ Running Flaky Tests in CircleCI
-```
+In **CircleCI**, tests are split across instances to run in parallel.
+You can also **run a single flaky test multiple times** across all instances.
+
+๐ **Mark a test as flaky by adding `#flaky` to the group:**
+
+```javascript
'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.
+Now, **group3** of this test will run **80 times in Firefox and Chrome**.
+If other tests are tagged with `#group3`, they will also run.
-**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.
-```
+## โ๏ธ CircleCI Configuration
+
+To **enable flaky tests in CircleCI**, modify `.circleci/config.yml`:
+```yaml
parameters:
run_flaky_tests:
type: boolean
default: true
```
+๐ **Set `false`** to run normal tests.
+๐ **Set `true`** to run only flaky tests.
+
+---
+
+## ๐ Important Links
+
+[](https://remix-project.org)
+[](https://remix-ide.readthedocs.io/en/latest/)
+[](https://medium.com/remix-ide)
+[](https://x.com/ethereumremix)
+[](https://discord.gg/zUNteAzJs3)
+
+
-## 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
-- X: https://x.com/ethereumremix
-- Join Discord: https://discord.gg/mh9hFCKkEq
