Mastering Solidity Lifecycle Testing with Foundry Anvil Testcontainers
Smart contracts are unique software entities that, once deployed, often control significant financial assets and execute critical business logic autonomously. Unlike traditional software that can be patched or updated easily, smart contracts require careful verification of their entire operational lifespan. This article explores lifecycle testing—a comprehensive approach to ensuring smart contracts behave correctly throughout their existence—and how Foundry Anvil Testcontainers dramatically simplifies this process.
What Are Lifecycle Tests?
Lifecycle tests are advanced forms of end-to-end tests designed to validate the behavior of a smart contract throughout its entire lifecycle. They ensure that contracts behave correctly over time, especially as they move through different states and handle sequences of operations that might occur during their lifespan. The main goal is to verify that the contract maintains integrity and correctness throughout all possible state changes.
In smart contracts, this “life story” includes several critical phases:
- Deployment and initialization - The contract is deployed to the blockchain and initial configuration is set
- Configuration and setup - Parameters are set, roles are assigned, and the contract is prepared for operation
- Active operation period - Users interact with the contract, state evolves, and business logic executes
- State transitions and upgrades - The contract moves through different operational states or is upgraded
- Emergency scenarios - Circuit breakers, pauses, or liquidations occur in response to critical events
For example, consider a token vesting contract. Its lifecycle begins when deployed, progresses through initialization where beneficiaries and schedules are set, enters an active phase where tokens gradually vest, handles claims throughout its life, and eventually completes when all tokens are distributed. Each of these phases must be thoroughly tested to ensure the contract behaves correctly throughout its existence.
Why Not Just Unit or Integration Tests?
While unit tests focus on individual functions and integration tests verify component interactions, lifecycle tests examine the evolution of a contract’s state and behavior during every stage. Think of it this way:
- Unit Tests are like checking individual car parts—the engine, wheels, brakes—in isolation
- Integration Tests verify these parts work together—the engine powers the wheels, brakes stop the car
- Lifecycle Tests ensure the car performs correctly throughout its entire lifespan—from factory assembly to years of operation on the road
Lifecycle tests catch issues that only emerge through the complex interplay of multiple operations over time, such as:
- State corruption after a sequence of transactions
- Reentrancy vulnerabilities in multi-step workflows
- Timing-dependent bugs that surface only after specific event sequences
- Edge cases in state transitions that unit tests miss
Common Contract Lifecycle Patterns
Smart contracts often follow predictable lifecycle patterns based on their purpose:
Time-Based Progression
Contracts that mature or evolve based on time, like vesting schedules, escrow services, or time-locked governance. These contracts transition through states based on temporal triggers. Testing requires simulating block timestamps and verifying behavior at key time points.
User-Driven Evolution
Contracts that progress based on user actions, like governance systems where proposal submission, voting, and execution drive state changes. Testing involves simulating multiple users and complex interaction sequences.
Event-Triggered Changes
Contracts that respond to external events or oracle data, transitioning states based on market conditions, price feeds, or external protocol interactions. Testing requires simulating external events and verifying appropriate state transitions.
Example: Lending Contract Lifecycle
Let’s examine a lending contract that allows users to deposit collateral, borrow against it, repay loans, and face liquidation if collateral value drops. This is a perfect example of an event-triggered lifecycle where the contract’s state changes based on user actions and market conditions.
Key Lifecycle Stages:
- Initialization - Contract deployed with price feeds and configuration
- Collateral Deposit - Users deposit assets to establish borrowing capacity
- Borrowing Phase - Users borrow against their collateral up to a safe threshold
- Health Monitoring - Continuous monitoring of collateral ratio vs. debt
- Market Volatility - Price changes affect health factors
- Liquidation Event - Undercollateralized positions trigger liquidation
- Recovery - Borrowers repay debt or liquidators recover collateral
A comprehensive lifecycle test would validate:
- Initial deposit and borrow operations work correctly
- Health factors are calculated accurately throughout the lifecycle
- Price changes trigger appropriate liquidation conditions
- Multiple users can operate simultaneously without interference
- Edge cases like full liquidation vs. partial liquidation
- State consistency after complex operation sequences
The Challenge: Complex Test Environment Setup
Traditional lifecycle testing for Solidity smart contracts involves significant complexity:
Environment Preparation Overhead
Setting up a test environment requires:
- Running a local Ethereum node (like Anvil or Ganache)
- Managing node lifecycle (start, stop, restart)
- Ensuring clean state between test runs
- Handling port conflicts and resource management
- Managing process cleanup and zombie processes
Time Simulation Challenges
Lifecycle tests often need to simulate:
- Block timestamp progression for time-based logic
- Block number advancement for block-dependent features
- Consistent mining intervals
- Realistic block production timing
State Management Complexity
Tests must handle:
- Setting up initial contract states
- Forking from mainnet for realistic conditions
- Snapshotting and reverting to previous states
- Managing multiple test environments in parallel
Multi-User Scenario Complexity
Realistic lifecycle tests require:
- Multiple accounts with different roles
- Coordinated sequences of transactions
- Proper nonce management
- Balance management across accounts
This is where Foundry Anvil Testcontainers transforms the landscape.
Simplifying Lifecycle Tests with Foundry Anvil Testcontainers
The Foundry Anvil Testcontainers NodeJS Module brings enterprise-grade test automation to Web3 development by eliminating the environmental complexity that plagues smart contract testing.
What Problem Does It Solve?
Foundry Anvil Testcontainers solves the core challenge of lifecycle testing: environmental consistency and ease of setup. By leveraging Docker containers and the battle-tested Testcontainers framework, it provides:
Zero Configuration Setup
Spin up isolated Anvil instances with a single line of code—no manual node management, no port conflicts, no cleanup scripts:
import { FoundryAnvilContainer } from '@hellaweb3/foundryanvil-testcontainers-nodejs';
// Start an Anvil container with a pristine blockchain state
const container = await new FoundryAnvilContainer().start();
// Get the RPC endpoint ready for your tests
const rpcUrl = container.getRpcUrl();
// Use with your favorite Web3 library
const provider = new ethers.JsonRpcProvider(rpcUrl);
Parallel Test Execution
Run multiple test suites simultaneously with completely isolated blockchain states. Each test gets its own Anvil instance, eliminating flaky tests caused by shared state:
describe('Lending Lifecycle - Happy Path', () => {
let container;
let provider;
beforeEach(async () => {
container = await new FoundryAnvilContainer().start();
provider = new ethers.JsonRpcProvider(container.getRpcUrl());
});
afterEach(async () => {
await container.stop();
});
it('completes full borrow and repay cycle', async () => {
// Test runs in complete isolation
});
});
describe('Lending Lifecycle - Liquidation Path', () => {
let container;
let provider;
beforeEach(async () => {
// Another isolated Anvil instance for this test suite
container = await new FoundryAnvilContainer().start();
provider = new ethers.JsonRpcProvider(container.getRpcUrl());
});
afterEach(async () => {
await container.stop();
});
it('handles liquidation correctly', async () => {
// Completely independent from other tests
});
});
Snapshot & Forking Support
Test against mainnet forks or custom blockchain snapshots, essential for lifecycle tests that need realistic initial conditions:
// Fork from mainnet to test against real protocol state
const container = await new FoundryAnvilContainer()
.withFork('https://eth-mainnet.alchemyapi.io/v2/YOUR_KEY')
.start();
// Or use a snapshot for consistent test conditions
const container = await new FoundryAnvilContainer()
.withSnapshot('/path/to/snapshot.json')
.start();
Custom Network Configuration
Configure block time, chain ID, and mining behavior to match your lifecycle test requirements:
// Instant mining for fast tests
const fastContainer = await new FoundryAnvilContainer()
.withBlockTime(0)
.start();
// Or realistic block times for time-sensitive lifecycle tests
const realisticContainer = await new FoundryAnvilContainer()
.withBlockTime(12) // 12 second blocks like mainnet
.start();
CI/CD Ready
Works seamlessly in GitHub Actions, GitLab CI, and other automation pipelines. The container-based approach means your tests run identically locally and in CI:
# GitHub Actions example
name: Smart Contract Lifecycle Tests
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm install
- run: npm test
# Testcontainers automatically handles Docker in CI
Real-World Impact: Before and After
Before Foundry Anvil Testcontainers
// Complex manual setup
const { spawn } = require('child_process');
let anvilProcess;
beforeAll(async () => {
// Manually start Anvil process
anvilProcess = spawn('anvil', ['--port', '8545']);
// Wait for Anvil to be ready (unreliable)
await new Promise(resolve => setTimeout(resolve, 2000));
// Hope the port is available
provider = new ethers.JsonRpcProvider('http://localhost:8545');
}, 30000);
afterAll(async () => {
// Manual cleanup (often leaves zombie processes)
if (anvilProcess) {
anvilProcess.kill();
}
});
// Tests share state and can interfere with each other
it('test 1', async () => { /* ... */ });
it('test 2', async () => { /* ... might fail due to test 1 state */ });
Problems:
- 80+ lines of boilerplate setup code
- Flaky tests due to timing issues
- Port conflicts when running multiple suites
- Zombie processes requiring manual cleanup
- Shared state causing test interference
- Difficult to run tests in parallel
- CI/CD environment differences
After Foundry Anvil Testcontainers
import { FoundryAnvilContainer } from '@hellaweb3/foundryanvil-testcontainers-nodejs';
let container;
let provider;
beforeEach(async () => {
container = await new FoundryAnvilContainer().start();
provider = new ethers.JsonRpcProvider(container.getRpcUrl());
});
afterEach(async () => {
await container.stop();
});
// Each test gets a fresh blockchain state
it('test 1', async () => { /* ... */ });
it('test 2', async () => { /* ... runs in complete isolation */ });
Benefits:
- 10 lines of clean, maintainable code
- Zero flaky tests from environment issues
- Automatic port management
- Guaranteed cleanup
- Complete test isolation
- Parallel execution by default
- Identical behavior locally and in CI
Development teams report:
- 80% reduction in test environment setup time
- Near-zero flaky tests due to environment inconsistencies
- Seamless onboarding for new developers joining Web3 projects
- Faster CI/CD pipelines with parallel test execution
Implementing a Complete Lifecycle Test
Here’s how to implement a comprehensive lifecycle test for a lending protocol using Foundry Anvil Testcontainers:
import { FoundryAnvilContainer } from '@hellaweb3/foundryanvil-testcontainers-nodejs';
import { ethers } from 'ethers';
describe('Lending Protocol - Full Lifecycle', () => {
let container;
let provider;
let lendingContract;
let collateralToken;
let borrower;
let liquidator;
beforeEach(async () => {
// Fresh blockchain for each test
container = await new FoundryAnvilContainer()
.withBlockTime(1) // 1 second blocks for time progression
.start();
provider = new ethers.JsonRpcProvider(container.getRpcUrl());
// Setup accounts
const accounts = await provider.listAccounts();
borrower = await provider.getSigner(accounts[0]);
liquidator = await provider.getSigner(accounts[1]);
// Deploy contracts
const CollateralToken = await ethers.getContractFactory('MockERC20', borrower);
collateralToken = await CollateralToken.deploy('Collateral', 'COL');
const LendingContract = await ethers.getContractFactory('LendingWithLiquidation', borrower);
lendingContract = await LendingContract.deploy(collateralToken.address);
// Initial setup
await collateralToken.mint(borrower.address, ethers.parseEther('1000'));
await collateralToken.approve(lendingContract.address, ethers.MaxUint256);
});
afterEach(async () => {
await container.stop();
});
it('completes full lifecycle: deposit → borrow → price drop → liquidation', async () => {
// Stage 1: Deposit collateral
await lendingContract.deposit(ethers.parseEther('100'));
const collateralAfterDeposit = await lendingContract.getCollateral(borrower.address);
expect(collateralAfterDeposit).to.equal(ethers.parseEther('100'));
// Stage 2: Set initial price and borrow
await lendingContract.updatePrice(ethers.parseEther('100')); // $100 per token
await lendingContract.borrow(ethers.parseEther('5000')); // Borrow $5000
const borrowAmount = await lendingContract.getBorrow(borrower.address);
expect(borrowAmount).to.equal(ethers.parseEther('5000'));
// Verify healthy position
let isHealthy = await lendingContract.isHealthy(borrower.address);
expect(isHealthy).to.be.true;
// Stage 3: Price drops, position becomes unhealthy
await lendingContract.updatePrice(ethers.parseEther('60')); // Price drops to $60
isHealthy = await lendingContract.isHealthy(borrower.address);
expect(isHealthy).to.be.false;
// Stage 4: Liquidation occurs
const liquidatorBalanceBefore = await provider.getBalance(liquidator.address);
await lendingContract.connect(liquidator).liquidate(
borrower.address,
ethers.parseEther('5000'),
{ value: ethers.parseEther('5000') }
);
// Verify liquidation results
const borrowAfterLiquidation = await lendingContract.getBorrow(borrower.address);
expect(borrowAfterLiquidation).to.equal(0);
const collateralAfterLiquidation = await lendingContract.getCollateral(borrower.address);
expect(collateralAfterLiquidation).to.be.lessThan(ethers.parseEther('100'));
// Liquidator receives bonus
const liquidatorBalanceAfter = await provider.getBalance(liquidator.address);
expect(liquidatorBalanceAfter).to.be.greaterThan(liquidatorBalanceBefore);
});
it('handles time-based interest accrual throughout lifecycle', async () => {
// Deposit and borrow
await lendingContract.deposit(ethers.parseEther('100'));
await lendingContract.updatePrice(ethers.parseEther('100'));
await lendingContract.borrow(ethers.parseEther('5000'));
const borrowAtStart = await lendingContract.getBorrow(borrower.address);
// Simulate time passing (blocks advance automatically with blockTime: 1)
await new Promise(resolve => setTimeout(resolve, 10000)); // 10 seconds = ~10 blocks
// Mine a block to trigger interest calculation
await provider.send('evm_mine', []);
const borrowAfterTime = await lendingContract.getBorrow(borrower.address);
// Interest should have accrued
expect(borrowAfterTime).to.be.greaterThan(borrowAtStart);
});
it('handles multiple concurrent borrowers without interference', async () => {
// Setup second borrower
const accounts = await provider.listAccounts();
const borrower2 = await provider.getSigner(accounts[2]);
await collateralToken.mint(borrower2.address, ethers.parseEther('1000'));
await collateralToken.connect(borrower2).approve(lendingContract.address, ethers.MaxUint256);
// Both borrowers deposit and borrow
await lendingContract.deposit(ethers.parseEther('100'));
await lendingContract.connect(borrower2).deposit(ethers.parseEther('200'));
await lendingContract.updatePrice(ethers.parseEther('100'));
await lendingContract.borrow(ethers.parseEther('5000'));
await lendingContract.connect(borrower2).borrow(ethers.parseEther('10000'));
// Price drops affecting only borrower1
await lendingContract.updatePrice(ethers.parseEther('60'));
const isHealthy1 = await lendingContract.isHealthy(borrower.address);
const isHealthy2 = await lendingContract.isHealthy(borrower2.address);
expect(isHealthy1).to.be.false; // Borrower1 unhealthy
expect(isHealthy2).to.be.true; // Borrower2 still healthy
// Liquidate borrower1
await lendingContract.connect(liquidator).liquidate(
borrower.address,
ethers.parseEther('5000'),
{ value: ethers.parseEther('5000') }
);
// Borrower2 unaffected
const borrow2 = await lendingContract.getBorrow(borrower2.address);
expect(borrow2).to.equal(ethers.parseEther('10000'));
});
});
This lifecycle test validates:
- Complete user journey from deposit to liquidation
- Time-based features like interest accrual
- Multi-user scenarios without state interference
- State transitions triggered by external events (price changes)
- Edge cases in liquidation logic
- Contract behavior throughout its operational lifetime
All with clean, maintainable test code and zero environmental complexity.
Best Practices for Lifecycle Testing
1. Test Realistic User Journeys
Model your lifecycle tests after actual user behavior patterns. Don’t just test happy paths—include the messy reality of user mistakes, retries, and edge cases.
2. Leverage Container Isolation
Take advantage of Testcontainers’ isolation to run aggressive parallel testing. Each lifecycle test gets its own pristine blockchain, so you can run dozens simultaneously without conflicts.
3. Use Snapshots for Complex Initial States
For lifecycle tests requiring elaborate setup, use Anvil snapshots to establish a known starting point, then test from there:
// Create snapshot after setup
await provider.send('evm_snapshot', []);
const snapshotId = await provider.send('evm_snapshot', []);
// Run test
// Revert to snapshot for next test
await provider.send('evm_revert', [snapshotId]);
4. Combine with Fuzzing
Use Foundry’s fuzzing capabilities alongside lifecycle tests to explore edge cases in state transitions.
5. Monitor Gas Throughout Lifecycle
Track gas consumption at each lifecycle stage to identify optimization opportunities and detect unexpected gas spikes.
Why Hella Web3 Built This
At Hella Web3, we believe quality and security are non-negotiable in Web3 development. Smart contract bugs can lead to millions in losses—we’ve seen it happen repeatedly. Our Foundry Anvil Testcontainers module reflects our commitment to building tools that:
- Eliminate Environment Drift - Every test runs in a pristine, identical environment
- Accelerate Development Cycles - Developers spend less time on test setup and more time building
- Improve Test Reliability - Consistent, reproducible tests mean fewer false positives
- Enable Continuous Testing - Seamless CI/CD integration ensures quality at every commit
This project showcases our engineering philosophy:
- Comprehensive test coverage through dogfooding our own tools
- Modern TypeScript architecture that’s type-safe and maintainable
- Performance optimized for fast container startup
- Extensive documentation with clear examples
- Active maintenance supporting the latest Foundry releases
Get Started with Foundry Anvil Testcontainers
Installation
npm install @hellaweb3/foundryanvil-testcontainers-nodejs
or
yarn add @hellaweb3/foundryanvil-testcontainers-nodejs
Quick Start
import { FoundryAnvilContainer } from '@hellaweb3/foundryanvil-testcontainers-nodejs';
// Start an Anvil container
const container = await new FoundryAnvilContainer().start();
// Get the RPC endpoint
const rpcUrl = container.getRpcUrl();
// Use with your favorite Web3 library
const provider = new ethers.JsonRpcProvider(rpcUrl);
// Run your lifecycle tests...
// Cleanup
await container.stop();
Resources
- GitHub Repository: hella-web3/foundryanvil-testcontainers-nodejs
- NPM Package: @hellaweb3/foundryanvil-testcontainers-nodejs
- Full Documentation: API Documentation
Our Service Offerings: Beyond Open Source
While our open-source tools like Foundry Anvil Testcontainers empower developers worldwide, we also provide curated service offerings specifically tailored for emerging tech Web3 startups. Our team brings US expertise combined with offshore cost effectiveness to deliver exceptional value.
DevOps & Test Automation
We build robust CI/CD pipelines with a focus on Web3 Test Automation. As creators of foundryanvil-testcontainers and wiremock-testcontainers, we specialize in high-fidelity E2E testing for smart contracts and dApps. Your startup needs this automation as a force multiplier to compete with entrenched players.
Our automation strategies reduce your time-to-market while increasing the reliability of your protocol.
Web3 Tooling & SDKs
Need custom tooling for your protocol? We build developer tools, SDKs, and testing frameworks that make your Web3 project more accessible and reliable.
Technical Articles & Documentation
Quality technical content drives developer adoption. We craft in-depth technical articles, documentation, and educational content that resonates with Web3 developers.
dApp Web Front-Ends
Beautiful, performant front-ends that connect seamlessly with your smart contracts. We specialize in modern web technologies optimized for Web3 interactions.
Custom Discord Bots
Engage your community with custom Discord bots tailored to your protocol’s needs—from token gating to on-chain data notifications.
GTM Launch Packages
Complete go-to-market support including technical content, video tutorials, documentation, and developer advocacy to ensure your protocol launches successfully.
Ready to Ship with Confidence?
Whether you’re building a DeFi protocol, NFT marketplace, or the next breakthrough Web3 application, comprehensive lifecycle testing is non-negotiable. Foundry Anvil Testcontainers makes it easier than ever to implement the testing strategy your users deserve.
Ship with confidence.
Our automation strategies reduce your time-to-market while increasing the reliability of your protocol. This open-source project is just a glimpse of what we can deliver for your team.
Get expert guidance on implementing lifecycle tests, building robust CI/CD pipelines, or developing custom Web3 tooling for your protocol.
Get a DevOps AuditThanks for reading! If you found this article helpful, consider starring our Foundry Anvil Testcontainers repository and sharing it with your Web3 developer community.
Part of the Hella Labs commitment to open-source excellence and Web3 infrastructure.
Start the conversation