Vyper Testing

Blueprints and Factories

blueprint = token.deploy_as_blueprint()

factory = factory_module.deploy(blueprint)

child_addr = factory.create_child("Name", "SYM")
child = token.at(child_addr)

Identity and Pranking

addr = boa.env.generate_address(alias="alice")
boa.env.set_balance(addr, 10 ** 18)

with boa.env.prank(addr):
    contract.restricted_function()

Expecting Reverts

# Match assert message
with boa.reverts("insufficient balance"):
    contract.transfer(to, amount)

# Match vm_error (assert with message)
with boa.reverts(vm_error="Not authorized"):
    contract.admin_only()

# Match compiler-level revert (e.g. underflow)
with boa.reverts(compiler="safesub"):
    contract.subtract(1, 2)

# Match dev comment: `assert x  # dev: reason`
with boa.reverts(dev="only owner"):
    contract.set_owner(addr)

State Snapshots

boa.env.anchor() snapshots VM state and rolls back on exit:

with boa.env.anchor():
    contract.mint(addr, 100)
    assert contract.balanceOf(addr) == 100
# state is reverted here
assert contract.balanceOf(addr) == 0

Evaluating Vyper In-Context

# Standalone evaluation
result = boa.eval("keccak256('hello')")

# Evaluate against a deployed contract's state
contract.eval("self.some_variable")
contract.eval("self._internal_var + 1")

Forking

with boa.fork("https://eth.llamarpc.com"):
    usdc = ERC20.at("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48")
    assert usdc.symbol() == "USDC"

Token Balance Manipulation

boa.deal(usdc, alice, 1_000 * 10 ** 6)
assert usdc.balanceOf(alice) == 1_000 * 10 ** 6

Time and Block Manipulation

boa.env.time_travel(seconds=86400)   # advance 1 day
boa.env.time_travel(blocks=100)      # advance 100 blocks
boa.env.time_travel(seconds=3600, blocks=10)  # both at once

Accessing Private Members

Boa exposes contract internals for white-box testing:

# Internal functions
contract.internal._compute_hash(data)

# Private storage variables
contract._storage.my_var.get()

# Private immutables
contract._immutables.MY_CONST

# Module variables (Vyper 0.4+)
contract.eval("imported_module.x")

Fixtures (conftest.py)

Structure fixtures in layers: accounts, roles, contracts, blueprints, factories.

import pytest
import boa
from src import my_token
from src.blueprints import nft


@pytest.fixture(scope="session")
def accounts():
    accts = {}
    for i in range(5):
        addr = boa.env.generate_address(alias=f"user_{i}")
        boa.env.set_balance(addr, 10 ** 18)
        accts[f"user_{i}"] = addr
    return accts


@pytest.fixture
def owner(accounts):
    return accounts["user_0"]


@pytest.fixture
def user(accounts):
    return accounts["user_1"]


@pytest.fixture
def token_contract(owner):
    with boa.env.prank(owner):
        return my_token.deploy("Token", "TKN", 18, 1_000_000, owner)


@pytest.fixture
def nft_blueprint():
    return nft.deploy_as_blueprint()

Use scope="session" for expensive, read-only fixtures (accounts, blueprints). Use default function scope for contracts that tests mutate.

Moccasin projects can also wrap deploy scripts:

from script.deploy import deploy_feed

@pytest.fixture(scope="session")
def price_feed():
    return deploy_feed()

Fuzzing with Hypothesis

Import strategies from boa.test.strategies:

from boa.test import strategies as boa_st
from hypothesis import given, settings


@given(amount=boa_st.uint256().filter(lambda x: 0 < x < 10 ** 20))
@settings(max_examples=200, deadline=None)
def test_deposit_any_amount(token, user, amount):
    with boa.env.prank(user):
        token.deposit(value=amount)
    assert token.balanceOf(user) >= amount

Available Strategies

Filtering for Realistic Values

realistic_amount = boa_st.uint256().filter(lambda x: 10 ** 16 <= x <= 10 ** 21)

non_zero_addr = boa_st.address().filter(
    lambda x: x != "0x0000000000000000000000000000000000000000"
)

Stateful Testing

from hypothesis.stateful import RuleBasedStateMachine, rule, invariant


class TokenStateMachine(RuleBasedStateMachine):
    def __init__(self):
        super().__init__()
        self.token = boa.load("src/token.vy", "T", "T", 18, 0, boa.env.eoa)
        self.balances = {}
        self.total = 0

    @rule(acct=boa_st.address(), amt=boa_st.uint256().filter(lambda x: x < 10 ** 20))
    def mint(self, acct, amt):
        self.token.mint(acct, amt)
        self.balances[acct] = self.balances.get(acct, 0) + amt
        self.total += amt

    @invariant()
    def supply_matches(self):
        assert self.token.totalSupply() == self.total


TestToken = TokenStateMachine.TestCase

Gas Profiling

Per-Test Marker

@pytest.mark.gas_profile
def test_expensive_op(contract):
    contract.batch_process(data)

CLI (all tests)

pytest tests/ --gas-profile

Exclude specific tests with @pytest.mark.ignore_gas_profiling.

Programmatic

boa.env.enable_gas_profiling()
contract.operation()
boa.env.reset_gas_metering_behavior()

Output includes two tables: call profile (per-function stats) and line profile (per-line gas within functions), each showing count, mean, median, stdev, min, max.

Coverage

Setup

Add to .coveragerc:

[run]
plugins = boa.coverage

Run

pytest --cov= --cov-branch tests/

# Moccasin shorthand
mox test --coverage

Coverage does not work with fast mode enabled.

Moccasin-Specific Features

Staging Markers

Run tests only on live networks:

@pytest.mark.staging
@pytest.mark.ignore_isolation
def test_oracle_integration(price_feed):
    assert price_feed.latestAnswer() > 0

• mox test runs only non-staging tests
• mox test --network sepolia runs only @pytest.mark.staging tests
• Add @pytest.mark.local to also run staging tests on local networks

Networks with live_or_staging = true in moccasin.toml skip non-staging tests automatically.

Test Organization Best Practices

Structure

Follow Arrange-Act-Assert:

def test_transfer_updates_balances(token, owner, user):
    # Arrange
    initial = token.balanceOf(owner)
    amount = 100

    # Act
    with boa.env.prank(owner):
        token.transfer(user, amount)

    # Assert
    assert token.balanceOf(owner) == initial - amount
    assert token.balanceOf(user) == amount

Test Grouping

Organize tests by category within each file:

1. Deployment / initial state -- constructor values, default storage
2. Happy path -- normal operations succeed
3. Access control -- unauthorized callers revert
4. Edge cases / reverts -- zero values, max values, overflow, underflow
5. Invariants / fuzzing -- property-based tests at the bottom

Naming

test_<function>_<scenario>_<expected>

test_transfer_zero_amount_reverts
test_mint_by_owner_succeeds
test_burn_exceeds_balance_reverts

One Assertion Per Test

Prefer one logical assertion per test for clear failure messages. Multiple related asserts (e.g. sender and receiver balances after transfer) in one test are acceptable when they verify a single operation.

Forge-to-Titanoboa Cheatsheet

Quick reference for developers migrating from Foundry/Forge. See the full guide in Forge Analogues.

Creating Mock Contracts

mock_token = boa.loads("""