Gas Cost Regression Checker in CI

WHAT IT DOES

The Gas Cost Regression Checker in CI is a developer tool that analyzes gas report data to detect gas cost regressions in CI environments. It parses gas reporter JSON files from Hardhat gas reporter, Foundry, or other EVM testing frameworks, extracts function names and their gas costs, and compares against a baseline report. The tool identifies functions where gas costs have increased beyond a configurable threshold, helping teams catch performance regressions early in the development cycle and prevent costly gas inefficiencies from reaching production.

HOW TO USE

Paste your current gas report JSON into the first text area and your baseline gas report into the second text area. Click "parse current" and "parse baseline" to extract gas data from each report. Click "check regressions" to compare gas costs. The tool displays a detailed report showing each function's current gas cost, baseline gas cost, absolute and percentage differences, and status. Functions with gas increases exceeding the 10% threshold are flagged as regressions. The report also indicates whether the CI check would pass or fail, making it easy to integrate into automated workflows.

TECHNICAL MECHANISM

The tool parses gas report JSON using format detection that supports multiple common structures. It handles hardhat-gas-reporter format with nested objects containing gasUsed fields, Foundry's test suite format with gas objects for each test, and flat array formats with name and gas fields. For each detected function, it extracts the function name, gas cost, and call count. The comparison algorithm calculates the absolute gas difference and percentage change relative to the baseline. A function is flagged as a regression if the gas cost increased by more than 10% of the baseline value, preventing noise from minor fluctuations. The tool also identifies improvements (decreased gas costs) and new functions without baselines. Results are displayed in a sortable table with color-coded status indicators, and the tool provides a summary of total regressions detected and a CI exit code recommendation.

WHAT IT CANNOT SEE

The tool cannot run tests or generate gas measurements—it only analyzes already-collected data. It cannot detect gas cost increases caused by changes in test coverage or test conditions that affect the gas measured. The tool cannot automatically update baseline gas costs. It cannot determine if a gas increase is acceptable without manual review or analyze why gas cost changed, only that it did. The tool cannot differentiate between changes in contract code and changes in the test environment or test setup. It cannot validate that gas measurements are accurate or reproducible across different runs. The tool cannot account for gas price fluctuations or network conditions, as it only measures gas usage, not gas cost in fiat or ETH.

PLEASE NOTE

This tool is designed for Ethereum Virtual Machine (EVM) compatible chains only. The 10% regression threshold is configurable within the tool's logic but is set as a reasonable default—users may want to adjust this based on their project's sensitivity to gas changes. The tool requires gas reports in JSON format—ensure your testing framework is configured to output JSON reports. The tool is intended for CI/CD pipelines and local development testing. Always run gas reports under consistent conditions (same test suite, same environment) to ensure accurate comparisons. The tool provides recommendations only and should be used as part of a comprehensive quality assurance process.