eth-gas-reporter

library0.2.27jsnpmunverified

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.

testing

npm install eth-gas-reporter

github ↗package ↗

INSTALL

IMPORT

SIG · ETH-GAS-REPORTER

eth-gas-reporter

testingjavascriptv0.2.27

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

reporter configuration string

✓ mocha: { reporter: 'eth-gas-reporter' }

✗ import EthGasReporter from 'eth-gas-reporter'

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.

reporterOptions object

✓ mocha: { reporterOptions: { currency: 'USD', token: 'ETH' } }

✗ import { reporterOptions } from 'eth-gas-reporter'

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.

Hardhat/Buidler Plugin

✓ require('hardhat-gas-reporter'); // in hardhat.config.js or buidler.config.js

✗ require('eth-gas-reporter'); // directly in hardhat.config.js

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.

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.

/* truffle-config.js */ const HDWalletProvider = require('@truffle/hdwallet-provider'); // Example dependency for network config module.exports = { networks: { development: { host: '127.0.0.1', port: 8545, network_id: '*', }, goerli: { provider: () => new HDWalletProvider( process.env.MNEMONIC ?? 'your_mnemonic_here', `https://goerli.infura.io/v3/${process.env.INFURA_PROJECT_ID ?? ''}` ), network_id: 5, gasPrice: 10000000000, // 10 Gwei confirmations: 2, timeoutBlocks: 200, skipDryRun: true }, }, mocha: { reporter: 'eth-gas-reporter', reporterOptions : { currency: 'USD', token: 'ETH', gasPrice: 20, // Example fixed gas price in Gwei coinmarketcap: process.env.COINMARKETCAP_API_KEY ?? '', // Required for currency conversions outputFile: 'gas-report.txt', noColors: false, rst: true, // Use ReStructuredText format for output rstTitle: 'Gas Usage Report' } }, compilers: { solc: { version: '0.8.0', // Specify your Solidity compiler version }, }, };

Debug

Known issues

breakingStarting 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.

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`).

affects: >=0.2.2

breakingThe 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.

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.

affects: >=0.2.26

gotchaWhen 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.

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';`.

affects: all

breakingInternal 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.

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.

affects: >=0.2.27

gotchaThe 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.

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.

affects: all

Errors

Common errors & fixes

CoinMarketCap API Key is not set or invalid.

The reporter attempted to fetch cryptocurrency prices but found a missing or invalid CoinMarketCap API key.

fix

Obtain a valid API key from CoinMarketCap and set it using the `coinmarketcap` option in your `reporterOptions` configuration or as an environment variable.

Error: Reporter 'eth-gas-reporter' not found.

Mocha could not locate the `eth-gas-reporter` package, often due to incorrect installation or an improper path.

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'`.

Error: Cannot find module 'hardhat-gas-reporter'

When using Hardhat/Buidler, the dedicated plugin `hardhat-gas-reporter` is missing, not `eth-gas-reporter` directly.

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');`.

Upgrade

Version history

0.2.27latest on npm

Audit

Dependencies

@codechecks/clientoptionalFor CI integration with Codechecks to display gas consumption changes in Github UI.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/cgewecke/eth-gas-reporter ↗

packagehttps://www.npmjs.com/package/eth-gas-reporter ↗