gas-snapshot-testing

Gas Snapshot Testing

Overview

Gas snapshots capture the gas cost of every test function and store them in .gas-snapshot. This file is committed to the repo and used in CI to detect gas regressions.

Creating Snapshots

# Generate gas snapshot
forge snapshot

# Output stored in .gas-snapshot:
# MyContractTest:test_deposit() (gas: 45231)
# MyContractTest:test_withdraw() (gas: 38912)
# MyContractTest:test_transfer() (gas: 21453)

Checking for Regressions in CI

# Compare current gas against committed snapshot
# Fails if any test uses more gas than recorded
forge snapshot --check

# Allow up to 5% increase
forge snapshot --tolerance 5

Gas Report

# Detailed per-function gas breakdown
forge test --gas-report

# Output:
# | src/Vault.sol:Vault |                 |       |        |       |         |
# |---------------------|-----------------|-------|--------|-------|---------|
# | Function Name       | min             | avg   | median | max   | # calls |
# | deposit             | 45231           | 47892 | 45231  | 53214 | 12      |
# | withdraw            | 38912           | 40123 | 38912  | 42345 | 8       |

# Filter to specific contracts
forge test --gas-report --match-contract Vault

CI Integration

GitHub Actions

name: Gas Check
on: [pull_request]

jobs:
  gas:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: foundry-rs/foundry-toolchain@v1

      - name: Install dependencies
        run: forge install

      - name: Check gas snapshots
        run: forge snapshot --check --tolerance 3

      - name: Gas report
        run: forge test --gas-report | tee gas-report.txt

      - name: Comment gas report on PR
        uses: actions/github-script@v7
        if: github.event_name == 'pull_request'
        with:
          script: |
            const fs = require('fs');
            const report = fs.readFileSync('gas-report.txt', 'utf8');
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Gas Report\n\`\`\`\n${report}\n\`\`\``
            });