Foundry — это довольно свежий и очень мощный инструмент для разработки, деплоя и тестирования смарт-контрактов на языке Solidity, и в последнее время он набирает бешенную популярность. Основная причина, по моему мнению, заключается в том, что Foundry позволяет реализовывать все этапы развития проекта на одном языке без знаний JavaScript, Node.js и прочего.

На данный момент в русскоязычном медиа-поле я смог найти очень мало инфы по данному инструменту, поэтому решил составить небольшую методическую рекомендацию для тех, у кого очень плохо с английским языком и кто хочет быстро втянуться и научиться работать с данным фреймворком.

В данной части мы установим, создадим и настроим проект, узнаем, как тестировать ошибки, ивенты и равенства.

Хочу сразу предупредить, что Foundry содержит в себе тонну различных команд, скриптов, дополнительных плагинов и инструментов. В рамках данного курса я затрону базовые команды и ограничусь объяснением их работы на уровне «чёрного ящика». Если вам интересно узнать, как реализованы некоторые команды, можете изучить открытый исходный код или документацию

Исходный код к данной части курса

Ссылка на мой аккаунт в Хабр Карьере (буду рад знакомству)

Оглавление

Часть 1 (Создание проекта, обзор файловой структуры, assertEq, prank, expectEmit, expectRevert)
Часть 2 (Aвтоматическое форматирование кода (forge fmt) отслеживание качества тестирования контрактов (forge coverage), логи (vvvv), управление временем (warp) и деньгами(deal, hoax).)
Часть 3 (Работа с прокси-контрактами (Proxy Upgradable Contracts, UUPS), написание скриптов для деплоя и вызова функций, работа с env (переменные среды), автоматизация запусков скриптов (Makefile), форк-тестирование)
Часть 4 (fuzz-тестирование, работа с cast)

Знакомство с Foundry (Forge, Anvil)

Перед тем, как преступить к работе с Foundry, следует его установить. Для спокойной и комфортной работы рекомендую использовать ОС семейства UNIX (WSL в случае, если у вас Windows). Установка максимально простая и понятная, подробно изложена сайте документации вот здесь

Для работы советую использовать VS code с данным плагином

Создание нового проекта

После того, как Foundry был успешно установлен, можно создавать первый проект

За инициализацию проекта отвечает следующая команда:

$ forge init

Примерно такая структура должна появится в той директории, в которой вы запустили данную команду

По умолчанию в каталогах script, src и test будут находится тестовые файлы для демонстрации работы фреймворка.

Кратко по каталогам и файлам:

lib — хранит все зависимости, которые нужны для проекта, но не так, как node_modules (node.js), поэтому данную папку можно смело пушить в гит и не добавлять в .gitignore
src — здесь будут хранится основные смарт-контракты вашего проекта, с которыми вы непосредственно работаете
script — здесь будут писаться скрипты для работы с контрактами. Это могут быть скрипты на деплой конкретного контракта, на вызов конкретной функции и т.д. Файлы в данном каталоге должны иметь формат .s.sol
test — аналогично для тестов, файлы должны иметь формат .t.sol
foundry.toml — это файл конфигурации проекта, он не раз вам понадобится для настройки тестов, зависимостей и прочего

Первый контракт, первый тест.

Я буду работать с контрактом Counter.sol, но только немного его модифицирую:

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

contract Counter is Ownable {
    uint256 public number;

    event Incremented();

    error onlyNotZero();

    constructor() Ownable() {
  
    }

    /**
     * Функция для установления нового значения number
     * Доступна для вызова только owner'y
     * @param newNumber не должен быть равен 0
     */
    function setNumber(uint256 newNumber) public onlyOwner {
        if (newNumber == 0) {
            revert onlyNotZero();
        }
        number = newNumber;
    }

    /**
     * Увеличивает значение number на 1
     * Инициирует событие Incremented
     */
    function increment() public {
        number++;
        emit Incremented();
    }
}

Если вы работаете в VS code с включенным плагином, то скорее всего вы увидите данную ошибку

Конечно же нам нужно установить контракты от OpenZeppelin, чтобы ими воспользоваться. Для этого воспользуемся следующей командой:

$ forge install OpenZeppelin/openzeppelin-contracts

Если вы столкнулись с ошибкой в процессе установки, попробуйте добавить в конец команды ключ “ — no-commit”

Теперь в папке lib должна появится соответствующая директория, но проблема не решена до конца. Всё дело в том, что для того, чтобы наш импорт в контракте работал, мы должны направить его в нашу папку lib/openzeppelin-contracts.. для этого сделаем соответствующий remapping (в файле foundry.toml добавьте следующий код)

remappings = ["@openzeppelin/contracts/=lib/openzeppelin-contracts/contracts/"]

После этого ошибка должна пропасть и теперь мы можем скомпилировать наш проект

$ forge build

Теперь давайте рассмотрим тест для данного контракта (Counter.t.sol):

// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;

//Здесь мы импортируем самый важный контракт для тестирования в Foundry
//Его обязательно нужно добавить в наследование к нашему контракту 
//для тестирования
import {Test} from "forge-std/Test.sol";

import {Counter} from "../src/Counter.sol";

/**
 * Структура теста такая же, как и у обычного контракта
 * Мы создаём самый обычный контракт, только наследуем его от Test
 */
contract CounterTest is Test {
    Counter public counter;

    //Для дальнейшего тестирования события Incremented
    //копируем его в тестирующий контракт
    event Incremented(uint256 indexed number);

    //Первая функция для тестирования - создание адреса (makeAddr)
    //Данная функция принимает в аргументы некоторую строку
    //Которая служит, как источник энтропии для генерации адреса
    //Обычно, данный параметр называют также, как и переменную
    address owner = makeAddr("owner");

    /**
     * Стартовая функция setUp()
     * Она запускается в самом начале выполнения теста (аналог конструктора)
     * Изменения состояния, которые происходят в данной функции,
     * будут применены ко всем остальным функциям.
     * В данном тесте мы используем данную функцию для того,
     * чтобы инициализировать тестируемый контракт
     */
    function setUp() public {
        counter = new Counter();
        //В данный момент owner контракта - это контракт тестирования
        //Для дальнейшей работы следует заменить его на созданный
        //ранее адрес (owner)
        counter.transferOwnership(owner);
    }

    /**
     * Стандартная тестовая функция
     * Её название не важно, изменения, которые в ней происходят
     * никак не повлияют на общее состояние, то есть все тесты
     * работают в "вакууме"
     */
    function testIncrement() public {
        counter.increment();

        //Самая простая и тревиальная функция сравнения двух значений
        assertEq(counter.number(), 1);
    }

    /**
     * В примере по-умолчанию уже используется так называемое fuzz-тестирование
     * Это более сложный уровень, но на данном этапе погружения можно
     * понять это следующим образом: fuzz-тестирование в Foundry используется
     * для тестирования нетривиальных (случайных) ситуаций
     *
     * В данном примере мы поместили в параметры тестирующей функции
     * параметр x - это значит, что при тестировании будет сгенерировано
     * множество различных (случайных) чисел x
     * и с каждым из них будет проведено тестирование данной функции
     */
    function testSetNumber(uint256 x) public {
        if (x != 0) {
            //Очень важная и крутая функция startPrank используется для того,
            //чтобы следующий участок кода выполнялся
            //от имени заданного нам адреса
            //В данном примере мы хотим использовать owner, чтобы от его имени
            //вызвать функцию setNumber()
            vm.startPrank(owner);
            counter.setNumber(x);
            vm.stopPrank();
            assertEq(counter.number(), x);
        }
    }

    /**
     * В данной функции мы будет использовать метод для проверки появления
     * нужной ошибки - expectRevert()
     * Данный метод может не принимать никаких аргументов и будет срабатывать
     * при любой ошибке
     * Но чтобы сделать наше тестирование более проработанным,
     * в качестве аргумента можно добавить текст ошибки
     */
    function testRevertIfCallerIsNotOwner() public {
        vm.expectRevert("Ownable: caller is not the owner");
        counter.setNumber(100);
    }

    /**
     * В случае, если контракт использует в качестве вызова
     * ошибок специальные объекты error, то в данном случае для
     * тестирования данной ошибки
     * в качестве аргумента к expectRevert() следует добавить
     * селектор нужной нам ошибки Counter.ZeroNumber.selector
     */
    function testRevertIfNumberIsZero() public {
        vm.expectRevert(Counter.ZeroNumber.selector);
        vm.startPrank(owner);
        counter.setNumber(0);
        vm.stopPrank();
    }

    /**
     * В данной функции мы рассмотрим метод для тестирования ивентов -
     * expectEmit()
     * На первый взгляд он мужет напугать, потому что имеет много
     * различных параметров, но на самом деле всё очень просто
     * Чтобы протестировать событие, нам нужно:
     * 1) Задать данные, которые будет проверять
     * 2) "Фиктивно" инициировать событие, которое мы собираемся проверять
     * 3) Вызвать функцию, в которой вызывается данное событие
     */
    function testEmitEventIncremented() public {
        //Это одна из простых форм вызова метода expectEmit,
        //где в качестве аргумента указывается только адрес того
        //от кого ожидаем получения события
        vm.expectEmit(address(counter));
        emit Incremented(1);
        counter.increment();
    }
}

Если у вас возник вопрос, что такое селектор или вам непонятны некоторые строчки кода рекомендую посмотреть серию обучающих роликов от Ильи Круковского или почитать очень интересную книгу от одного из создателей Solidity — “Осваиваем Ethereum”

Селектор — это первые 4 байта хеша сигнатуры функции (в нашем случае — объекта ошибки)

Если по-простому, селектор — это идентификатор объекта, по которому компилятор Solidity понимает, какую именно функцию или ошибку вызывать

Для проверки тестов воспользуемся командой:

$ forge test

Если вы всё сделали правильно, то в консоли должны появится приятные и успокаивающие зелёные логи :)

При желании вы можете конкретизировать, какой именно тест вы хотите запустить c помощью ключа “ — match-test”, например:

$ forge test --match-test testIncrement

Заключение

В первой (вводной части) мы затронули самые базовые инструменты тестирования Foundry, протестировали простые функции, ошибки (в виде текста и селектора), события, и немного затронули fuzz-тестирование.

2 часть >>>

Тестирование смарт-контрактов в Foundry (часть 1)