> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/circlefin/evm-cctp-contracts/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Guide

> Test EVM CCTP Contracts with unit tests, integration tests, and static analysis

## Overview

This guide covers testing strategies for EVM CCTP Contracts, including unit tests, integration tests, linting, and static analysis.

## Prerequisites

* Foundry CLI installed (forge 0.2.0)
* Git submodules initialized: `git submodule update --init --recursive`
* Yarn installed: `yarn install`

## Unit Tests

### Running Tests

Run unit tests using the Foundry forge CLI:

```bash theme={null}
forge test
```

Alternatively, run tests in a Docker container:

```bash theme={null}
make test
```

### Test Output

Successful test output:

```bash theme={null}
[PASS] testDepositForBurn() (gas: 123456)
[PASS] testReceiveMessage() (gas: 234567)
Test result: ok. 42 passed; 0 failed; finished in 2.34s
```

## Debug Logs

Control test verbosity using the `-v` flag to display logs and traces:

### Verbosity Levels

| Flag     | Output Level | Description                       |
| -------- | ------------ | --------------------------------- |
| `-v`     | Basic        | Shows test results                |
| `-vv`    | Detailed     | Shows console.log() statements    |
| `-vvv`   | Verbose      | Shows execution traces            |
| `-vvvv`  | Very Verbose | Shows execution traces with stack |
| `-vvvvv` | Maximum      | Shows all execution details       |

### Examples

**Display console.log statements:**

```bash theme={null}
forge test -vv
```

**Show full execution traces:**

```bash theme={null}
forge test -vvvv
```

**Test specific contract:**

```bash theme={null}
forge test --match-contract MessageTransmitterTest -vv
```

**Test specific function:**

```bash theme={null}
forge test --match-test testDepositForBurn -vvv
```

### Adding Debug Logs

To use `console.log()` in your contracts, import the console library:

```solidity theme={null}
import "lib/forge-std/src/console.sol";

contract MyContract {
    function myFunction() public {
        console.log("Debug value:", someValue);
    }
}
```

## Integration Tests

Integration tests run against a local Anvil test node and simulate full cross-chain scenarios.

### Running Integration Tests

```bash theme={null}
make anvil-test
```

This command:

1. Starts an Anvil test node in a Docker container
2. Deploys all contracts
3. Runs integration test suite
4. Cleans up resources

### Example Integration Test

An example integration test is available in the `anvil/` folder that demonstrates:

* Deploying contracts to local testnet
* Configuring cross-chain messaging
* Executing full deposit and burn flow
* Simulating attestation
* Receiving messages on destination chain

### Manual Integration Testing

Start Anvil manually for interactive testing:

```bash theme={null}
# Start Anvil node
anvil

# In another terminal, deploy contracts
forge script scripts/v1/deploy.s.sol --rpc-url http://localhost:8545 --broadcast

# Run your tests
forge test --fork-url http://localhost:8545
```

## Linting

Lint Solidity code to enforce style guidelines and catch common issues:

```bash theme={null}
yarn lint
```

This checks all `.sol` files in the `src/` and `test/` directories.

### Linting Configuration

Linting rules are defined in `.solhint.json`. Common checks include:

* Code style and formatting
* Best practice violations
* Security anti-patterns
* Gas optimization opportunities

### Fixing Linting Issues

Some linting issues can be auto-fixed:

```bash theme={null}
yarn lint:fix
```

### Common Linting Rules

**Naming Conventions:**

```solidity theme={null}
// Bad
function MyFunction() public {}

// Good
function myFunction() public {}
```

**Visibility Modifiers:**

```solidity theme={null}
// Bad
function transfer() {}

// Good
function transfer() external {}
```

**Import Organization:**

```solidity theme={null}
// Good - imports at top, organized
import "./interfaces/IReceiver.sol";
import "./libraries/Message.sol";
```

## Static Analysis

Run static analysis using Mythril to detect security vulnerabilities:

### Analyzing Contracts

**MessageTransmitter:**

```bash theme={null}
make analyze-message-transmitter
```

**MessageTransmitterV2:**

```bash theme={null}
make analyze-message-transmitter-v2
```

**TokenMessengerMinter:**

```bash theme={null}
make analyze-token-messenger-minter
```

### Analyzing Individual Files

If Mythril is already installed:

```bash theme={null}
myth -v4 analyze $FILE_PATH \
  --solc-json mythril.config.json \
  --solv 0.7.6
```

Example:

```bash theme={null}
myth -v4 analyze src/MessageTransmitter.sol \
  --solc-json mythril.config.json \
  --solv 0.7.6
```

<Warning>
  Static analysis can take several minutes to complete, especially for complex contracts.
</Warning>

### Understanding Results

Mythril reports potential issues with severity levels:

* **High**: Critical security vulnerabilities
* **Medium**: Significant issues that should be addressed
* **Low**: Minor issues or informational warnings

## Continuous Integration

GitHub Actions automatically runs tests on every push and pull request.

### CI Workflow

The workflow configuration is in `.github/workflows/ci.yml` and includes:

1. Linting checks
2. Unit tests
3. Integration tests
4. Code coverage reports

### Viewing CI Results

Check CI status:

1. Navigate to the repository on GitHub
2. Click the "Actions" tab
3. Select the workflow run to view details

### Local CI Simulation

Run the same checks locally before pushing:

```bash theme={null}
# Run all checks
yarn lint && forge test && make anvil-test
```

## Security Scanning

### Olympix AI Scanning

Manually trigger Olympix.ai security scanning:

<Steps>
  <Step title="Navigate to Actions">
    Click on the "Actions" tab in your GitHub repository
  </Step>

  <Step title="Select Olympix Scan">
    In the left sidebar, select "Olympix Scan"
  </Step>

  <Step title="Run Workflow">
    Select the branch and click "Run workflow"
  </Step>

  <Step title="Review Results">
    Wait for the scan to complete and review security alerts
  </Step>
</Steps>

## Test Coverage

Generate test coverage reports:

```bash theme={null}
forge coverage
```

View detailed coverage:

```bash theme={null}
forge coverage --report lcov
```

### Coverage Goals

* **Critical paths**: 100% coverage
* **Core contracts**: >95% coverage
* **Utility functions**: >90% coverage
* **Overall project**: >90% coverage

## Testing Best Practices

### Write Comprehensive Tests

```solidity theme={null}
function testDepositForBurn() public {
    // Setup
    uint256 amount = 1000e6;
    
    // Execute
    uint64 nonce = tokenMessenger.depositForBurn(
        amount,
        destinationDomain,
        recipient,
        token
    );
    
    // Assert
    assertEq(nonce, 1);
    assertEq(usdc.balanceOf(address(this)), 0);
}
```

### Test Edge Cases

* Zero amounts
* Maximum values
* Invalid addresses
* Unauthorized callers
* Paused state
* Reentrancy scenarios

### Use Fuzz Testing

```solidity theme={null}
function testFuzz_depositForBurn(uint256 amount) public {
    vm.assume(amount > 0 && amount <= maxAmount);
    
    tokenMessenger.depositForBurn(
        amount,
        destinationDomain,
        recipient,
        token
    );
    
    // Assertions
}
```

### Mock External Dependencies

```solidity theme={null}
function setUp() public {
    // Deploy mocks
    mockAttester = new MockAttester();
    
    // Deploy contracts with mocks
    messageTransmitter = new MessageTransmitter(
        address(mockAttester)
    );
}
```

## Troubleshooting

### Tests Fail to Compile

* Check Solidity version (should be 0.7.6)
* Verify all dependencies are installed
* Run `git submodule update --init --recursive`

### Tests Timeout

* Increase timeout in foundry.toml
* Check for infinite loops in contracts
* Verify RPC connection is stable

### Coverage Reports Empty

* Ensure tests are passing first
* Check that test files are in `test/` directory
* Verify forge coverage is configured correctly

## Next Steps

* [Deploy to testnet](/guides/deployment)
* [Integrate CCTP](/guides/integration)
* [Test cross-chain transfers](/guides/cross-chain-transfer)