Тестируем смарт-контракты на Hardhat 3: node:test, viem и ни одного mocha

Hardhat в третьей версии решили не мелочиться, взяли и сменили весь тестовый стек. Вместо привычной связки mocha + chai + ethers теперь такой родной node:test и viem. Апгрейд-гайды в основном рассказывают, как мигрировать конфиг, а вот как теперь писать тесты - материала заметно меньше. Я не так давно, буквально несколько дней назад, писал свой учебный проект на Hardhat 3 и собрал рецепт целиком. От init до ассертов на балансы. Всё из этой статьи ты сможешь повторить за вечер

Тестировать будем мой учебный проект контракт-копилку. Его суть максимально простая. Положить деньги в копилку могут все, забирать может только владелец, и только тогда, когда накоплена цель. Полный код в репозитории, но для статьи достаточно его интерфейса

function deposit() external payable;   // revert EmptyDeposit()
function withdraw() external;          // revert NotOwner() / GoalNotReached(current, goal)
function progress() external view returns (uint256 current, uint256 target);

event Deposited(address indexed from, uint256 amount, uint256 total);
event Withdrawn(address indexed to, uint256 amount);

Что изменилось в Hardhat 3

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

Требования: Node 22.13+ (жёсткое, node:test нужной версии), дальше:

npx hardhat --init   # шаблон: node-test-runner-viem

Если выбрал шаблон, как из примера выше, тогда у тебя есть contracts/, test/, ignition/ и конфиг на TypeScript. Пуляем контракт в contracts/ и полетели тестить.

Каркас теста

import assert from "node:assert/strict";
import { describe, it } from "node:test";
import { parseEther, getAddress } from "viem";
import { network } from "hardhat";

describe("Kopilka", async function () {
  const { viem } = await network.create();
  const [owner, stranger] = await viem.getWalletClients();

  const GOAL = parseEther("1");
  const deploy = () => viem.deployContract("Kopilka", [GOAL]);

  // тесты ниже
});

Две вещи, которые, на мой взгляд, стоит посмотреть дважды. Первая это describe, и он асинхронный, а вместе с ним network.create(), который живёт внутри него. Каждый describe получает собственную EVM в памяти. "Зачем это нужно?" - спросишь ты. Отвечаю: мгновенные блоки, 20 предзаряженных аккаунтов, ноль сетевых вызовов. Вторая вещь это deploy и он стал фабрикой. И снова тот же вопрос от тебя и снова ответ от меня: Свежий контракт на каждый тест дешевле, чем отлов межтестового состояния между тестами и попытка понять, "А как так выходит, что тест вроде правильный, а падает с кривыми цифрами?"

Первый тест — тривиальный, но он проверяет весь конвейер от компиляции до чтения:

it("деплой: владелец — деплоер, цель записана", async function () {
  const kopilka = await deploy();

  assert.equal(await kopilka.read.owner(), getAddress(owner.account.address));
  const [current, target] = await kopilka.read.progress();
  assert.equal(current, 0n);
  assert.equal(target, GOAL);
});

Запоминаем, где зарыта первая грабля: read.owner() возвращает адрес в EIP-55 checksum-регистре, а owner.account.address в нижнем. Из этого следует, что сравнивать надо через getAddress(), иначе тест падает на «одинаковых» адресах.

События: emitWithArgs

it("deposit эмитит Deposited", async function () {
  const kopilka = await deploy();

  await viem.assertions.emitWithArgs(
    kopilka.write.deposit({ value: parseEther("0.4"), account: stranger.account }),
    kopilka,
    "Deposited",
    [getAddress(stranger.account.address), parseEther("0.4"), parseEther("0.4")],
  );
});

Тут все довольно стандартно. Аргументы сверяются позиционно по ABI, не перепутай порядок. Обрати внимание на третий аргумент. Контракт пишет в событие address(this).balance, а он к моменту emit уже включает пришедший депозит. Небольшой вывод из опыта: Тест на событие - это прекрасный способ зафиксировать тонкости и сложности семантики контракта, о которых не расскажет ни один геттер. Поменяешь контракт и упадет тест из-за несоответствия нового ABI и аргументов теста.

Отказы: revertWithCustomError

Тест «функция работает» пишут все. Давай говорить откровенно: на такой "сложный" тест ума много не надо. Но в жизни все наоборот. Деньги теряют там, где функция не отказала, хотя должна была:

it("withdraw чужаком откатывается", async function () {
  const kopilka = await deploy();
  await kopilka.write.deposit({ value: GOAL });

  await viem.assertions.revertWithCustomError(
    kopilka.write.withdraw({ account: stranger.account }),
    kopilka,
    "NotOwner",
  );
});

Теперь под другим углом, тот же профиль. Версия с аргументами, которая проверяет не только причину отказа, но и цифры в ней:

await viem.assertions.revertWithCustomErrorWithArgs(
  kopilka.write.withdraw(),
  kopilka,
  "GoalNotReached",
  [parseEther("0.3"), GOAL],
);

И опять из опыта: это намного сильнее, чем может казаться: «отказал, но не по той причине» - это полноценный баг, который строковые require-сообщения ловили плохо, а типизированные custom errors ловят бесплатно и главное "красиво".

Деньги: balancesHaveChanged

Мой любимый ассерт нового стека:

it("после цели владелец забирает всё", async function () {
  const kopilka = await deploy();
  await kopilka.write.deposit({ value: GOAL, account: stranger.account });

  await viem.assertions.balancesHaveChanged(kopilka.write.withdraw(), [
    { address: owner.account.address, amount: GOAL },
  ]);
});

Здесь одна строка кода утверждает главное для любого контракта с деньгами. Проверяем, что после транзакции баланс владельца вырос ровно на GOAL. Что мне нравится здесь особенно, так это то, что комиссию за газ ассерт учитывает сам, не нужно ничего вычитать руками и следить за математикой лишний раз. Типичное место кривых тестов - плохо посчитанная вручную математика, при их написании. В HH2 такой тест собирался из getBalance-до и getBalance-после и ручной арифметики с receipt.gasUsed. Теперь это просто хорошо забытое старое.

Шпаргалка по viem.assertions

Опыт, собранный по дороге

1. Checksum-адреса - сравнивай через getAddress()

2. describe обязан быть async, а network.create() внутри него

3. Всё в bigint. assert.equal(current, 0) упадёт: 0 !== 0n. Литералы с суффиксом n, суммы только через parseEther

4. Node ниже 22.13 - самая частая причина «ничего не работает» сразу после init. Ошибки поймаешь не про версию ноды, а про синтаксис, так что может быть не очевидно

Запуск - npx hardhat test. Семь тестов моей копилки пробегают за треть секунды, потому что сеть живёт в памяти процесса. CI-конфиг сводится к npm ci && npx hardhat test - никаких сервисов и RPC-ключей. Не это ли счастье?

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