{"id":14563,"library":"eth-gas-reporter","title":"eth-gas-reporter: Gas Usage for Ethereum Tests","description":"eth-gas-reporter is a Mocha reporter designed to provide detailed gas usage metrics for Ethereum smart contract unit tests. It helps developers optimize contract efficiency by displaying gas consumption per test, method calls, and deployments. The current stable version is 0.2.27 as of April 2026. While an explicit release cadence isn't stated, the changelog shows consistent updates over time, indicating active maintenance. Key differentiators include its integration with popular Ethereum development environments like Truffle and Hardhat (via a plugin), the ability to calculate real-world national currency costs, and CI integration via Codechecks for tracking gas changes across pull requests. It supports various tokens for price calculation like ETH, BNB, MATIC, AVAX, HT, or MOVR.","status":"active","version":"0.2.27","language":"javascript","source_language":"en","source_url":"https://github.com/cgewecke/eth-gas-reporter","tags":["javascript","Ethereum","solidity","unit-testing","truffle","gas."],"install":[{"cmd":"npm install eth-gas-reporter","lang":"bash","label":"npm"},{"cmd":"yarn add eth-gas-reporter","lang":"bash","label":"yarn"},{"cmd":"pnpm add eth-gas-reporter","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"For CI integration with Codechecks to display gas consumption changes in Github UI.","package":"@codechecks/client","optional":true}],"imports":[{"note":"The `eth-gas-reporter` library is primarily consumed as a string identifier within a Mocha test runner's configuration, not directly imported as a JavaScript/TypeScript module into user code for its core functionality. It is loaded by Mocha itself.","wrong":"import EthGasReporter from 'eth-gas-reporter'","symbol":"reporter configuration string","correct":"mocha: { reporter: 'eth-gas-reporter' }"},{"note":"Configuration options are passed as a plain JavaScript object within the Mocha configuration. These options are not exported symbols for direct import but rather properties of a configuration object.","wrong":"import { reporterOptions } from 'eth-gas-reporter'","symbol":"reporterOptions object","correct":"mocha: { reporterOptions: { currency: 'USD', token: 'ETH' } }"},{"note":"For Hardhat and Buidler projects, a separate plugin (`hardhat-gas-reporter`, formerly `buidler-gas-reporter`) is required and imported to integrate this reporter. The core `eth-gas-reporter` package is then used by that plugin.","wrong":"require('eth-gas-reporter'); // directly in hardhat.config.js","symbol":"Hardhat/Buidler Plugin","correct":"require('hardhat-gas-reporter'); // in hardhat.config.js or buidler.config.js"}],"quickstart":{"code":"/* truffle-config.js */\nconst HDWalletProvider = require('@truffle/hdwallet-provider'); // Example dependency for network config\n\nmodule.exports = {\n  networks: {\n    development: {\n      host: '127.0.0.1',\n      port: 8545,\n      network_id: '*',\n    },\n    goerli: {\n      provider: () => new HDWalletProvider(\n        process.env.MNEMONIC ?? 'your_mnemonic_here',\n        `https://goerli.infura.io/v3/${process.env.INFURA_PROJECT_ID ?? ''}`\n      ),\n      network_id: 5,\n      gasPrice: 10000000000, // 10 Gwei\n      confirmations: 2,\n      timeoutBlocks: 200,\n      skipDryRun: true\n    },\n  },\n  mocha: {\n    reporter: 'eth-gas-reporter',\n    reporterOptions : {\n      currency: 'USD',\n      token: 'ETH',\n      gasPrice: 20, // Example fixed gas price in Gwei\n      coinmarketcap: process.env.COINMARKETCAP_API_KEY ?? '', // Required for currency conversions\n      outputFile: 'gas-report.txt',\n      noColors: false,\n      rst: true, // Use ReStructuredText format for output\n      rstTitle: 'Gas Usage Report'\n    }\n  },\n  compilers: {\n    solc: {\n      version: '0.8.0', // Specify your Solidity compiler version\n    },\n  },\n};","lang":"javascript","description":"Demonstrates how to configure `eth-gas-reporter` within a `truffle-config.js` file, including example network setup and various reporter options for currency, token, and output format."},"warnings":[{"fix":"Obtain a free API key from CoinMarketCap and set it via the `coinmarketcap` option in `reporterOptions` or as an environment variable (e.g., `process.env.COINMARKETCAP_API_KEY`).","message":"Starting March 2020, the CoinMarketCap API requires a valid API key for fetching cryptocurrency market price data. Using the reporter for national currency conversions without this key will result in failures.","severity":"breaking","affected_versions":">=0.2.2"},{"fix":"Ensure your project's Mocha version is compatible with v10. Refer to Mocha's official migration guide for potential breaking changes and necessary adjustments.","message":"The underlying Mocha dependency was updated to v10. This update may introduce compatibility issues with older Mocha test suites or custom Mocha configurations if not managed correctly.","severity":"breaking","affected_versions":">=0.2.26"},{"fix":"Install `hardhat-gas-reporter` (`npm install --save-dev hardhat-gas-reporter`) and configure it in your `hardhat.config.js` using `require('hardhat-gas-reporter');` or `import 'hardhat-gas-reporter';`.","message":"When integrating with Hardhat (formerly Buidler), the `eth-gas-reporter` package is not configured directly. Instead, you must install and utilize the separate `hardhat-gas-reporter` plugin.","severity":"gotcha","affected_versions":"all"},{"fix":"No direct user action is required for typical usage. If you were extending or deeply integrating with internal `ethers` utilities, review your code for compatibility with `ethers` v5 or newer's `utils` module.","message":"Internal changes in v0.2.27 removed `@ethersproject/abi` in favor of `ethers.utils`. This primarily affects maintainers or developers who might have been interacting with the reporter's internal `ethers` dependencies directly.","severity":"breaking","affected_versions":">=0.2.27"},{"fix":"Launch your Ethereum client (e.g., Ganache, Hardhat Network) as a separate process and connect to it over RPC. Avoid in-process providers for test execution with this reporter.","message":"The reporter makes synchronous RPC calls during data collection. Running your test suite with an in-process provider like `ganache-core` can cause tests to hang.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Obtain a valid API key from CoinMarketCap and set it using the `coinmarketcap` option in your `reporterOptions` configuration or as an environment variable.","cause":"The reporter attempted to fetch cryptocurrency prices but found a missing or invalid CoinMarketCap API key.","error":"CoinMarketCap API Key is not set or invalid."},{"fix":"Ensure `eth-gas-reporter` is installed as a dev dependency (`npm install --save-dev eth-gas-reporter`) and that your Mocha configuration correctly specifies its name: `reporter: 'eth-gas-reporter'`.","cause":"Mocha could not locate the `eth-gas-reporter` package, often due to incorrect installation or an improper path.","error":"Error: Reporter 'eth-gas-reporter' not found."},{"fix":"Install the specific plugin for Hardhat/Buidler: `npm install --save-dev hardhat-gas-reporter` and include it in your configuration file using `require('hardhat-gas-reporter');`.","cause":"When using Hardhat/Buidler, the dedicated plugin `hardhat-gas-reporter` is missing, not `eth-gas-reporter` directly.","error":"Error: Cannot find module 'hardhat-gas-reporter'"}],"ecosystem":"npm"}