Skip to content

docs: add a gas profiles guide for Solidity tests - #317

Open
aelmanaa wants to merge 1 commit into
NomicFoundation:mainfrom
aelmanaa:docs/gas-profile
Open

aelmanaa wants to merge 1 commit into
NomicFoundation:mainfrom
aelmanaa:docs/gas-profile

Conversation

@aelmanaa

@aelmanaa aelmanaa commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Docs for NomicFoundation/hardhat#8738, which adds --gas-profile to hardhat test solidity. Proposal: NomicFoundation/hardhat#8737.

  • New page docs/guides/testing/gas-profiles.mdx. It covers:
    • when to use a gas profile instead of --gas-stats or -vvvv traces;
    • how to run a profile and narrow it;
    • how to read the terminal summary, self gas and total gas, and refunds;
    • what a profile leaves out;
    • opening the folded-stack files in speedscope or inferno;
    • the limits, and where the files are written.
  • Short links to the new page from gas-statistics.mdx, the testing guides index, using-solidity.mdx (next to --grep), and execution-traces.mdx.
  • cspell-dictionary.txt: adds speedscope and flamegraph.

pnpm lint passes (prettier, astro check, cspell).

Merge this only after the hardhat PR is released. The HTML report from the follow-up PR will get its own docs PR.

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings October 19, 2026 19:17
@vercel

vercel Bot commented Oct 19, 2026

Copy link
Copy Markdown

@aelmanaa is attempting to deploy a commit to the Nomic Foundation Team on Vercel.

A member of the Team first needs to authorize it.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The guide needs a documentation correction, and upstream behavior and release availability require confirmation before merging.

1 open issue
What changed in this PR

Adds a guide to Solidity test gas profiling and connects it to existing testing documentation.

Changes:

  • Documents profiling commands, output, gas accounting, visualization, and limitations.
  • Adds links from related guides.
  • Adds visualization terms to the spelling dictionary.
File Description
src/​content/​docs/​docs/​guides/​testing/​using-solidity.mdx Links test filters to gas profiling.
src/​content/​docs/​docs/​guides/​testing/​index.mdx Adds the guide to further reading.
src/​content/​docs/​docs/​guides/​testing/​gas-statistics.mdx Links statistics readers to profiling.
src/​content/​docs/​docs/​guides/​testing/​gas-profiles.mdx Introduces the gas profiling guide.
src/​content/​docs/​docs/​guides/​execution-traces.mdx Links execution traces to profiling.
cspell-dictionary.txt Adds speedscope and flamegraph.

Review effort: Balanced


Hardhat has three ways to look at gas, and each one answers a different question:

- [Gas statistics](/docs/guides/testing/gas-statistics) (`--gas-stats`) sum the gas of each public function across all your tests. Use them to track what your functions cost your users.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants