MuSe - MUtation SEeding tool Plugin for Remix IDE

MuSe is a mutation testing tool for Solidity Smart Contracts. It was designed to run mutation testing on Solidity projects. It can run test using Hardhat, Brownie, Truffle and Forge, hybrid test suites, and custom test scripts.

Table of Contents

• Requirements
• Installation
  • Option 1 – Docker
  • Option 2 – Local Setup
• Connect to Remix IDE
• Usage
• Support

Requirements

• Docker >= v20.0.X (for docker installation)
• Node >= 20.19.0 (for local installation)

🚀 Installation

🔧 Option 1 – Docker (Recommended)

# Pull the image from DockerHub
docker pull danielecarangelo/muse-remix-plugin

# Run the container
docker run --rm -p 3001:3001 danielecarangelo/muse-remix-plugin

💻 Option 2 – Local Setup (Only Linus-Based OS)

# Clone the repository
git clone --recurse-submodules https://github.com/Carmineh/MuSe-Remix-Plugin.git
cd MuSe-Remix-Plugin

# Install dependencies for MuSe
cd MuSe
npm install
# Check the official documentation for framework installation steps.
# Frameworks are required to run tests.

# Install dependencies for the plugin
cd ../MuSe-Remix-Plugin
npm install

# Install dependencies for API Service
cd ../muse-api-service
npm install

# Start the server inside muse-api-service
node server.js

🧩 Connect to Remix IDE (GitHub Pages Version)

1. Open Remix IDE
2. Go to the Plugin Manager
3. Click on Connect to a Local Plugin
4. Enter the following:

   Plugin Name: MuSe
   Display Name: MuSe
   Url: https://carmineh.github.io/MuSe-Remix-Plugin/

5. Activate the plugin

🧩 Connect to Remix IDE (Local Version)

1. Go into the MuSe-Remix-Plugin folder
2. Run npm run dev
3. Open Remix IDE
4. Go to the Plugin Manager
5. Click on Connect to a Local Plugin
6. Enter the following:

   Plugin Name: MuSe
   Display Name: MuSe
   Url: http://localhost:5173/MuSe-Remix-Plugin/

7. Activate the plugin

🛠️ Usage

Once the plugin is installed:

1. Make sure the local server at http://localhost:3001/ is running (view Installation)
2. You will see the MuSe Plugin tab in the Remix sidebar

💻 Interface Overview

The MuSe Plugin UI includes:

1. Contract Selector

   • Lists all compiled contracts in Remix under the contracts/ folder

2. Mutant Selectors

   • Each dropdown shows available mutation operators (mutants)

3. Mutate button

   • Click to run mutation using selected contract and mutants
   • The mutated contract will be automatically added to Remix under the MuSe/

4. Test Button

   • Open the Test Configuration to start the Mutation testing

5. Test Configuration

   • Testing Framework: Choose one of the 4 available frameworks
   • Timeout: A timeout in seconds to stop looped testings

6. Console

   • A console that will show operations results and errors

   

👾 Mutation Operators

This plugin includes the mutation operators defined in Sumo and MuSe

📑 Quick Start

1. Select a Contract
   Use the dropdown menu to select the smart contract you want to test.

2. Choose Mutation Operators
   Pick one or more mutation operators from the provided list.

3. Click “Mutate”
   Press the Mutate button to generate mutated versions of the selected contract.

4. Prepare the Test File
   Make sure the test file is renamed correctly and it's placed inside the /tests folder on Remix. Its name must contain both:

   • The contract name
   • The test framework you're using (e.g., hardhat, truffle, etc.)

   ⚠️ These keywords are not case-sensitive.
   ✅ Example: mycontract-hardhat.js

5. Run the Test
   Run the tests using the button and see the progress inside the plugin's console

6. View the Mutation Report
   Once the test run is complete, open the MuSe/results/report.html file.

📬 Support

If you encounter any bugs, have questions, or want to request new features, please open an Issue in this repository.

When opening an issue, please provide:

• A clear and descriptive title
• Detailed steps to reproduce the problem (if applicable)
• Expected and actual behavior
• Any relevant screenshots or logs
• Your environment details (e.g., OS, Node version, Docker version)