Code Coverage
Relevant source files
The following files were used as context for generating this wiki page:
Code coverage in the Canon Guard project is a critical metric used to ensure the security and reliability of the multisig solution's smart contracts. It measures the extent to which the source code is executed during various testing phases, including unit tests, integration tests, and fuzzing campaigns.
The project utilizes the Foundry development framework and Medusa fuzzer to generate coverage reports, helping developers identify untested logic branches and ensure that security invariants—particularly those related to the SafeEntrypoint and Action Builders—are thoroughly validated.
Sources: CLAUDE.md:1-15, README.md:1-10, package.json:15-30
Testing Infrastructure and Coverage Generation
The project implements a multi-layered testing strategy to achieve high code coverage. Each layer contributes to the overall coverage of the src/contracts/ directory, which contains the core logic for the Safe multisig enhancements.
Coverage Tools and Commands
Coverage is primarily generated using forge coverage. The project is configured to target unit tests specifically for standard reports to ensure core logic isolation.
| Command | Purpose | Tools Used |
|---|---|---|
yarn coverage | Generates a summary and LCOV report for unit tests | Foundry (Forge) |
yarn test:fuzz | Runs a Medusa campaign with coverage tracking enabled | Medusa |
yarn test:unit | Executes isolated logic tests defined in .tree files | Bulloak, Forge |
Sources: package.json:15-28, CLAUDE.md:37-50, README.md:46-48
Coverage Flow Architecture
The following diagram illustrates how different testing suites contribute to the code coverage data collected during development.
This diagram shows the flow from different testing methodologies to the final coverage reporting artifacts.
Sources: package.json:17, medusa.json:10-14, CLAUDE.md:40-55
Fuzzing and Invariant Coverage
A significant portion of the "functional coverage" is handled through invariant testing and fuzzing. Unlike standard line coverage, these tests ensure that system properties hold true across a wide range of state transitions.
Medusa Configuration for Coverage
The Medusa fuzzer is explicitly configured to track coverage and output it in multiple formats.
- Coverage Enabled:
true - Formats:
html,lcov - Target:
test/invariants/fuzz/FuzzTest.t.sol
Sources: medusa.json:10-15, medusa.json:65-70
Security Invariants Covered
The following areas are prioritized for invariant-based coverage to ensure no "frozen" states or unauthorized executions occur:
| Category | Invariant Examples | File Context |
|---|---|---|
| Accounting | invariant_capNeverExceeded | Limits never exceeded in hubs |
| Timing | invariant_transactionTimingIsCorrect | expiresAt > executableAt > queuedAt |
| Approvals | invariant_queuedTransactionsHaveValidApprovals | Checks action builder permissions |
| Consistency | invariant_queueMappingConsistency | Sync between queue array and mapping |
Sources: test/invariants/PROPERTIES.md:10-40
Development Environment Configuration
The foundry.toml file defines profiles that impact how code is compiled and instrumented for coverage.
[profile.test]
via_ir = true
out = 'out-via-ir'
[invariant]
timeout = 1000
corpus_dir = 'test/invariants/fuzz/corpus'
The use of via_ir in the test profile ensures that the coverage report reflects the optimized intermediate representation of the contracts, which is crucial for accurate gas and logic branch analysis.
Sources: foundry.toml:15-30
Execution Logic and Transaction Flow
To achieve 100% coverage, the test suites must traverse the entire lifecycle of a Canon Guard transaction, from queueing to execution or expiry.
Testing this sequence across different action builders (SimpleActions, CappedTokenTransfers) is required to fulfill coverage requirements.
Sources: CLAUDE.md:15-25, test/invariants/PROPERTIES.md:42-55
Summary of Coverage Goals
The Canon Guard project aims for comprehensive coverage by combining traditional unit testing with advanced automated bug-finding tools. By utilizing Forge for line coverage and Medusa for state-space coverage, the project ensures that the dynamic timelocks and Actions contracts operate securely under all conditions. Developers can verify the current status of these metrics using the yarn coverage script.
Sources: README.md:50-52, package.json:17