Unit Testing
Relevant source files
The following files were used as context for generating this wiki page:
Unit testing in Canon Guard is designed to ensure the reliability and security of individual components by isolating them from external dependencies. These tests are strictly focused on the core logic of smart contracts, such as SafeEntrypoint, ActionHub, and various Action Builders, ensuring they behave correctly under controlled conditions.
The project utilizes a multi-layered testing strategy where unit tests serve as the foundation, followed by integration tests, invariant (fuzz) testing, and symbolic execution. Unit tests are primarily located in the test/unit/ directory and leverage specialized tools like Bulloak for test specification.
Sources: CLAUDE.md:21-25, README.md:25-27
Testing Framework and Configuration
Canon Guard uses Foundry as its primary development and testing framework. The configuration is optimized for high-performance execution and deep security analysis.
Foundry Configuration Details
The testing environment is configured via foundry.toml with the following parameters:
- Solidity Version: 0.8.30
- EVM Version: Prague
- Optimizer: 10,000 runs, with
via_irenabled for thetestprofile to ensure accurate code representation during testing. - Fuzzing: Default of 1,000 runs, which can be increased to 5,000 for "deep" unit testing.
Sources: foundry.toml:13-28, package.json:28, CLAUDE.md:46-50
Test Execution Commands
| Command | Description |
|---|---|
yarn test:unit | Executes all unit tests using the Unit contract matcher. |
yarn test:unit:deep | Runs unit tests with 5,000 fuzzing runs (5x the default). |
yarn coverage | Generates a summary and LCOV report for files in test/unit/*. |
yarn lint:bulloak | Checks .tree specification files for consistency. |
Sources: package.json:17-28, README.md:32-38
Unit Testing Architecture
The unit testing suite is structured to separate concerns between simple logic validation and complex state transitions.
This diagram illustrates the organization of unit testing components, highlighting the use of Bulloak for formalizing test structures.
Sources: CLAUDE.md:21-25, package.json:20
Bulloak Integration
The project employs bulloak, a tool that uses .tree files to define test trees. This ensures that unit tests follow a strictly defined branching logic, covering all possible state transitions and edge cases for a given function.
Sources: CLAUDE.md:58, package.json:20
Invariant and Fuzz Testing
While traditional unit tests cover specific paths, Canon Guard incorporates invariant testing to ensure certain properties always hold true, regardless of the sequence of actions.
Medusa Fuzzing
Medusa is used for property-based testing. The configuration in medusa.json targets the FuzzTest contract and manages a high-intensity fuzzing environment.
- Workers: 10 parallel workers.
- Call Sequence: Up to 100 transactions per sequence.
- Target:
test/invariants/fuzz/FuzzTest.t.sol.
Sources: medusa.json:3-10, medusa.json:76-80
Core Invariants
Unit tests for invariants focus on four primary areas:
- Cap & Accounting: Ensures epoch boundaries and limits are respected (e.g.,
invariant_capNeverExceeded). - Ghost State: Validates internal tracking consistency.
- Approval & Timing: Checks that
executableAt,expiresAt, andqueuedAtmaintain a logical chronological order. - Queue Consistency: Verifies that the queue array and transaction mappings remain synchronized without duplicates.
Sources: test/invariants/PROPERTIES.md:9-40
Symbolic Execution
In addition to standard Foundry tests, Canon Guard utilizes Halmos for symbolic execution. This allows the team to mathematically prove the correctness of certain unit logic by exploring all possible inputs symbolically rather than just random samples.
Sources: package.json:26, README.md:48-50
Summary of Test Components
The following table summarizes the key modules covered by the testing suite.
| Module | Testing Focus |
|---|---|
SafeEntrypoint | Time-delayed execution and approval validation. |
ActionHub | Management of action builders and hub-level permissions. |
EmergencyModeHook | Logic for pausing operations under stress. |
OnlyEntrypointGuard | Verification that transactions originate from the entrypoint. |
Sources: CLAUDE.md:9-16, test/invariants/PROPERTIES.md:3-8
Unit testing in Canon Guard provides the first line of defense in its security-centric architecture. By combining standard Foundry unit tests with Bulloak specifications and symbolic execution, the project ensures that its core multisig and timelock logic is robust and verified against a wide range of failure modes.