Skip to content

docs: update gas statistics page for aggregated deployment stats #232

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kanej merged 1 commit into from
Mar 31, 2026
Merged

docs: update gas statistics page for aggregated deployment stats #232

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 50 additions & 55 deletions src/content/docs/docs/guides/testing/gas-statistics.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,58 +24,53 @@ You can pass the `--gas-stats` flag to either the `test` task or to one of its s
This prints a table like the following:

```
╔═════════════════════════════════════════════════════════════════════════════════════════╗
║ Gas Usage Statistics ║
╚═════════════════════════════════════════════════════════════════════════════════════════╝
╔═════════════════════════════════════════════════════════════════════════════════════════╗
║ contracts/Calculator.sol:Calculator ║
╟───────────────────────────────────┬─────────────────┬─────────┬────────┬───────┬────────╢
║ Function name │ Min │ Average │ Median │ Max │ #calls ║
╟───────────────────────────────────┼─────────────────┼─────────┼────────┼───────┼────────╢
║ divide │ 44316 │ 44316 │ 44316 │ 44316 │ 1 ║
║ multiply(uint256,uint256) │ 44254 │ 44254 │ 44254 │ 44254 │ 2 ║
║ multiply(uint256,uint256,uint256) │ 44875 │ 44875 │ 44875 │ 44875 │ 1 ║
║ reset │ 21485 │ 21485 │ 21485 │ 21485 │ 1 ║
║ result │ 23510 │ 23510 │ 23510 │ 23510 │ 6 ║
║ subtract │ 44213 │ 44213 │ 44213 │ 44213 │ 1 ║
╟───────────────────────────────────┼─────────────────┼─────────┴────────┴───────┴────────╢
║ Deployment Cost │ Deployment Size │ ║
╟───────────────────────────────────┼─────────────────┤ ║
║ 288115 │ 1120 │ ║
╚═══════════════════════════════════╧═════════════════╧═══════════════════════════════════╝
╔═════════════════════════════════════════════════════════════════════════════════════════╗
║ contracts/Counter.sol:Counter ║
╟───────────────────────────────────┬─────────────────┬─────────┬────────┬───────┬────────╢
║ Function name │ Min │ Average │ Median │ Max │ #calls ║
╟───────────────────────────────────┼─────────────────┼─────────┼────────┼───────┼────────╢
║ add(uint256) │ 43915 │ 43915 │ 43915 │ 43915 │ 1 ║
║ add(uint256,bool) │ 44284 │ 44419 │ 44419 │ 44554 │ 2 ║
║ inc │ 43482 │ 43482 │ 43482 │ 43482 │ 1 ║
║ x │ 23466 │ 23466 │ 23466 │ 23466 │ 5 ║
╟───────────────────────────────────┼─────────────────┼─────────┴────────┴───────┴────────╢
║ Deployment Cost │ Deployment Size │ ║
╟───────────────────────────────────┼─────────────────┤ ║
║ 234940 │ 870 │ ║
╚═══════════════════════════════════╧═════════════════╧═══════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════════════════════╗
║ Gas Usage Statistics ║
╚═══════════════════════════════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════════════════════╗
║ contracts/Calculator.sol:Calculator ║
╟───────────────────────────────────┬────────┬─────────┬────────┬────────┬──────────────╢
║ Function name │ Min │ Average │ Median │ Max │ #calls ║
╟───────────────────────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ divide │ 44316 │ 44316 │ 44316 │ 44316 │ 1 ║
║ multiply(uint256,uint256) │ 44254 │ 44254 │ 44254 │ 44254 │ 2 ║
║ multiply(uint256,uint256,uint256) │ 44875 │ 44875 │ 44875 │ 44875 │ 1 ║
║ reset │ 21485 │ 21485 │ 21485 │ 21485 │ 1 ║
║ result │ 23510 │ 23510 │ 23510 │ 23510 │ 6 ║
║ subtract │ 44213 │ 44213 │ 44213 │ 44213 │ 1 ║
╟───────────────────────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ Deployment │ Min │ Average │ Median │ Max │ #deployments ║
╟───────────────────────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ │ 288115 │ 288115 │ 288115 │ 288115 │ 1 ║
╚═══════════════════════════════════╧════════╧═════════╧════════╧════════╧══════════════╝
╔═══════════════════════════════════════════════════════════════════════════════════════╗
║ contracts/Counter.sol:Counter ║
╟───────────────────────────────────┬────────┬─────────┬────────┬────────┬──────────────╢
║ Function name │ Min │ Average │ Median │ Max │ #calls ║
╟───────────────────────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ add(uint256) │ 43915 │ 43915 │ 43915 │ 43915 │ 1 ║
║ add(uint256,bool) │ 44284 │ 44419 │ 44419 │ 44554 │ 2 ║
║ inc │ 43482 │ 43482 │ 43482 │ 43482 │ 1 ║
║ x │ 23466 │ 23466 │ 23466 │ 23466 │ 5 ║
╟───────────────────────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ Deployment │ Min │ Average │ Median │ Max │ #deployments ║
╟───────────────────────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ │ 234940 │ 234940 │ 234940 │ 234940 │ 1 ║
╚═══════════════════════════════════╧════════╧═════════╧════════╧════════╧══════════════╝
```

The statistics are collected from the functions called by the tests you executed. This means that running `test solidity --gas-stats` will produce a different result than running `test nodejs --gas-stats`, because different tests will have been run.

## Understanding the Gas Statistics Table

The gas statistics table shows the following information for each function:
The gas statistics table shows the following information for each function and deployment:

- **count**: Number of times the function was called
- **count**: Number of times the function was called or the contract was deployed
- **min**: Minimum gas consumed in a single call
- **max**: Maximum gas consumed in a single call
- **avg**: Average gas consumed across all calls
- **median**: Median gas consumed across all calls
Comment on lines +68 to 72
Copy link

Copilot AI Mar 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The metric definitions still describe only function calls (e.g., “in a single call” / “across all calls”), but this section now says the table includes deployments too. Please update these bullets to describe both (e.g., call or deployment) and align the naming with the table headers (#calls vs #deployments) so readers aren’t confused about what “count” refers to for deployments.

Suggested change
- **count**: Number of times the function was called or the contract was deployed
- **min**: Minimum gas consumed in a single call
- **max**: Maximum gas consumed in a single call
- **avg**: Average gas consumed across all calls
- **median**: Median gas consumed across all calls
- **count**: For functions, the number of calls (`#calls`); for deployments, the number of times the contract was deployed (`#deployments`)
- **min**: Minimum gas consumed in a single call or deployment
- **max**: Maximum gas consumed in a single call or deployment
- **avg**: Average gas consumed across all calls or deployments
- **median**: Median gas consumed across all calls or deployments

Copilot uses AI. Check for mistakes.

For deployments, the table shows:

- **gas**: Gas cost of executing the deployment
- **size**: Size of the deployed bytecode in bytes

### Functions included in gas statistics

Gas statistics only include public functions that are called directly by your tests. If a public function is called by another function but not directly by a test, it won't be included in the statistics.
Expand Down Expand Up @@ -135,21 +130,21 @@ contract CounterTest {
The output will be:

```
╔═══════════════════════════════════════════════════════════════════════╗
║ Gas Usage Statistics ║
╚═══════════════════════════════════════════════════════════════════════╝
╔═══════════════════════════════════════════════════════════════════════╗
║ contracts/Counter.sol:Counter ║
╟─────────────────┬─────────────────┬─────────┬────────┬───────┬────────╢
║ Function name │ Min │ Average │ Median │ Max │ #calls ║
╟─────────────────┼─────────────────┼─────────┼────────┼───────┼────────╢
║ inc │ 43484 │ 43484 │ 43484 │ 43484 │ 1 ║
║ incBy │ 43937 │ 43937 │ 43937 │ 43937 │ 1 ║
╟─────────────────┼─────────────────┼─────────┴────────┴───────┴────────╢
║ Deployment Cost │ Deployment Size │ ║
╟─────────────────┼─────────────────┤ ║
║ 179915 │ 616 │ ║
╚═════════════════╧═════════════════╧═══════════════════════════════════╝
╔═════════════════════════════════════════════════════════════════════╗
║ Gas Usage Statistics ║
╚═════════════════════════════════════════════════════════════════════╝
╔═════════════════════════════════════════════════════════════════════╗
║ contracts/Counter.sol:Counter ║
╟─────────────────┬────────┬─────────┬────────┬────────┬──────────────╢
║ Function name │ Min │ Average │ Median │ Max │ #calls ║
╟─────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ inc │ 43484 │ 43484 │ 43484 │ 43484 │ 1 ║
║ incBy │ 43937 │ 43937 │ 43937 │ 43937 │ 1 ║
╟─────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ Deployment │ Min │ Average │ Median │ Max │ #deployments ║
╟─────────────────┼────────┼─────────┼────────┼────────┼──────────────╢
║ │ 179915 │ 179915 │ 179915 │ 179915 │ 1 ║
╚═════════════════╧════════╧═════════╧════════╧════════╧══════════════╝
```

The statistics include `inc` and `incBy` because they're called directly by the tests. The `reset()` function doesn't appear because it's never called by the tests. The `_incInternal()` function doesn't appear because it's private and only called by `inc()`, not directly by the tests.