coveralls-truffle v1.0.1

Coveralls-Truffle

A simple tool to generate and upload code coverage reports for Truffle projects. This tool simplifies the integration of solidity-coverage and Coveralls for Truffle-based smart contract projects, ensuring seamless cross-platform support.

Features

• Automated Coverage Reports: Easily generate code coverage for Solidity smart contracts using solidity-coverage.
• Coveralls Integration: Automatically upload coverage reports to Coveralls.
• Cross-Platform Compatibility: Works on Windows, macOS, and Linux with minimal configuration.
• Truffle Project Detection: Automatically checks if the current directory is a valid Truffle project.
• Error Handling: Provides clear error messages if the environment is not set up correctly.

Why Use Coveralls-Truffle?

Testing is a crucial part of blockchain development. Code coverage helps you understand how much of your smart contract code is tested, and tools like Coveralls provide excellent visualization of this data. However, integrating these tools with Truffle can sometimes be tricky due to compatibility or platform issues. Coveralls-Truffle simplifies this process by:

1. Detecting your Truffle project configuration automatically.
2. Generating a coverage report with one simple command.
3. Uploading the results to Coveralls without requiring additional configuration.

Installation

Install the tool globally using npm:

npm install -g coveralls-truffle

Usage

Prerequisites

Before using this tool, ensure the following:

1. Truffle Project: Your project should be a valid Truffle project with truffle-config.js or truffle.js present in the root directory.
2. Coveralls Token: If you want to upload the coverage report to Coveralls, you need a Coveralls token. Set it in your environment variables:

   export COVERALLS_REPO_TOKEN=your_token_here

Steps to Use

1. Navigate to your Truffle project directory.
2. Run the command:

   coveralls-truffle

3. The tool will:
   • Check if your project is a valid Truffle project.
   • Run solidity-coverage to generate a coverage report.
   • Push the report to Coveralls if a valid token is provided.

Testing the Project

Running Tests Locally

This project includes a robust suite of tests to verify its functionality. Follow these steps to run the tests:

1. Install Dependencies: Make sure all required dependencies are installed:

   npm install

2. Run the Tests: Execute the test suite:

   npm test

   You should see output indicating the results of each test case:

   > coveralls-truffle@1.0.0 test
   > node test/test.js
   
   ✔ should fail if not a Truffle project
   ✔ should generate coverage if in a valid Truffle project
   ✔ should upload coverage report to Coveralls
   ✔ should handle missing dependencies gracefully

Test Cases

The test suite includes the following key scenarios:

1. Non-Truffle Project Detection:

   • Ensures the tool fails gracefully when run in a directory that is not a valid Truffle project.
   • Verifies the error message includes "This does not appear to be a Truffle project."

2. Coverage Generation in a Valid Truffle Project:

   • Simulates a valid Truffle project setup by creating a truffle-config.js file in a mock directory.
   • Verifies that the tool runs solidity-coverage and outputs "Running coverage...".
   • Automatically cleans up mock files after the test.

3. Uploading Coverage Report to Coveralls:

   • Tests the tool's ability to upload coverage data by simulating the upload process.
   • Ensures the output includes "Uploading to Coveralls...".

4. Handling Missing Dependencies:

   • Mocks scenarios where required dependencies are unavailable.
   • Verifies that the error message includes "Error: Required dependencies not found."

Custom Testing Logic

You can extend the test suite by adding your own cases:

1. Add a Test: Create a new test file in the test directory:

   touch test/customTest.js

2. Write Custom Logic: Use Node.js's assert module or a testing framework. For example:

   const assert = require('assert');
   const { isTruffleProject } = require('../lib/checkTruffle');
   
   describe('Custom Test Suite', () => {
     it('should correctly detect Truffle projects', () => {
       require('fs').writeFileSync('truffle-config.js', '');
       assert(isTruffleProject());
       require('fs').unlinkSync('truffle-config.js'); // Cleanup
     });
   });

3. Run the Test: Execute the test file directly:

   node test/customTest.js

CI Integration

Automate testing with CI/CD pipelines to ensure consistent functionality across environments. Example GitHub Actions workflow:

name: Test Coveralls-Truffle

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 16

      - name: Install Dependencies
        run: npm install

      - name: Run Tests
        run: npm test

Roadmap

Planned improvements for future versions:

1. Add support for generating HTML reports for local inspection.
2. Provide compatibility with Hardhat projects.
3. Add options for customizing the upload target (e.g., Codecov).

License

This project is licensed under the MIT License. See the LICENSE file for details.