CI/CD Integration

Automate assertion testing in your CI/CD pipeline

You can set up CI/CD workflows to ensure all assertion tests pass before merging code. The setup is very similar to standard Foundry/Forge workflows, with the addition of installing pcl and running pcl test for testing.

GitHub Actions Example

name: Phylax Assertion Tests

on:
  pull_request:
    branches: [main, develop]
    paths:
      - "assertions/**"
      - "src/**"
  workflow_dispatch:

env:
  FOUNDRY_PROFILE: assertions

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          submodules: recursive

      - name: Setup Foundry
        uses: foundry-rs/foundry-toolchain@v1
        with:
          version: nightly

      - name: Install pcl
        run: |
          LATEST_VERSION=$(curl -fsSL https://api.github.com/repos/phylaxsystems/pcl/releases/latest | jq -r '.tag_name')
          curl -fsSL "https://github.com/phylaxsystems/pcl/releases/download/${LATEST_VERSION}/pcl-${LATEST_VERSION}-linux-x86_64.tar.gz" | tar -xz
          sudo install -m 0755 pcl/pcl /usr/local/bin/pcl

      - name: Run tests
        run: |
          pcl test

This workflow:

• Triggers on pull requests to main/develop branches when assertion or source files change
• Supports manual runs with workflow_dispatch
• Uses the assertions profile via FOUNDRY_PROFILE: assertions
• Installs the latest pcl from GitHub releases
• Runs all assertion tests with pcl test

Use the FOUNDRY_PROFILE: assertions environment variable to ensure the correct Foundry profile is used for testing assertions.

Foundry Profile Configuration

Foundry profiles allow you to configure different compilation and testing settings for different parts of your project. For assertions, you typically want separate profiles for unit and fuzz tests so slower suites do not run every time you want quick local feedback.

This configuration goes in your project’s foundry.toml file, which you should be familiar with if you have used Foundry before.

Recommended Profile Structure

Organize your tests into separate folders and create profiles for each test type:

assertions/
├── src/           # Assertion source code
└── test/
    ├── unit/      # Fast unit tests
    └── fuzz/      # Fuzz tests (slower)

Example foundry.toml

[profile.default]
src = "src"
out = "out"
libs = ["lib"]
solc = "0.8.29"
optimizer = true
optimizer_runs = 200

# General assertions profile (runs all tests)
[profile.assertions]
src = "assertions/src"
test = "assertions/test"
out = "assertions/out"
libs = ["lib"]
solc = "0.8.29"
optimizer = true
optimizer_runs = 200

# Unit tests only (fast, for local development)
[profile.unit-assertions]
src = "assertions/src"
test = "assertions/test/unit"
out = "assertions/out"
libs = ["lib"]
solc = "0.8.29"
optimizer = true
optimizer_runs = 200

# Fuzz testing profile
[profile.fuzz-assertions]
src = "assertions/src"
test = "assertions/test/fuzz"
out = "assertions/out"
libs = ["lib"]
solc = "0.8.29"
optimizer = true
optimizer_runs = 10000

# Fuzz configuration (applies to all profiles)
[fuzz]
runs = 256
max_test_rejects = 65536

Profile Benefits

• Unit tests (unit-assertions) - Fast feedback during development
• Fuzz tests (fuzz-assertions) - Run separately when testing edge cases
• General (assertions) - Runs all tests for comprehensive validation

When using pcl test or setting FOUNDRY_PROFILE=<profile>, Foundry uses that profile’s configuration instead of the default one.

Running Tests Locally with Profiles

You can set the FOUNDRY_PROFILE environment variable to use specific profiles:

# Run only fast unit tests (recommended for local development)
FOUNDRY_PROFILE=unit-assertions pcl test

# Run fuzz tests
FOUNDRY_PROFILE=fuzz-assertions pcl test

# Run all assertion tests
FOUNDRY_PROFILE=assertions pcl test

If nothing is specified, the default profile is used.

Best Practices

1. Run tests on PR - Catch issues before merging
2. Use path filters - Only run tests when relevant files change
3. Cache dependencies - Speed up CI runs (Foundry toolchain action handles this)
4. Separate profiles - Keep assertion compilation separate from main project
5. Pin versions - Consider pinning the pcl version for reproducibility

Learn More:

• Testing Assertions - Basic testing guide
• Fuzz Testing - Test with random inputs
• Review Backtesting Results - Review the automatic backtest attached to a platform release
• Foundry Book - Testing