#Testing contracts
After compiling your contracts, the next step is to write some tests to verify that they work as intended.
This guide explains our recommended approach for testing contracts in Hardhat. It relies on ethers to connect to Hardhat Network and on Mocha and Chai for the tests. It also uses our custom Chai matchers and our Hardhat Network Helpers to make it easier to write clean test code. These packages are part of the Hardhat Toolbox plugin; if you followed the previous guides, you should already have them installed.
While this is our recommended test setup, Hardhat is flexible: you can customize the approach or take a completely different path with other tools.
#Initial setup
In this guide we’ll write some tests for the sample project. If you haven’t done it yet, go and initialize it.
We recommend you use TypeScript to get better autocompletion and catch possible errors earlier. This guide will assume you are using TypeScript, but you can click the tabs of the code examples to see the Javascript counterpart.
The setup includes some example tests in the test/Lock.ts
file, but ignore them for now. Instead, create a test/my-tests.ts
file. During this guide we'll only run those, by running npx hardhat test test/my-tests.ts
, instead of just npx hardhat test
.
#A simple test
In the following sections we'll write some tests for the Lock
contract that comes with the sample project. If you haven't read it yet, please take a look at the contracts/Lock.sol
file.
For our first test we’ll deploy the Lock
contract and assert that the unlock time returned by the unlockTime()
getter is the same one that we passed in the constructor:
import { expect } from "chai";
import hre from "hardhat";
import { time } from "@nomicfoundation/hardhat-toolbox/network-helpers";
describe("Lock", function () {
it("Should set the right unlockTime", async function () {
const lockedAmount = 1_000_000_000;
const ONE_YEAR_IN_SECS = 365 * 24 * 60 * 60;
const unlockTime = (await time.latest()) + ONE_YEAR_IN_SECS;
// deploy a lock contract where funds can be withdrawn
// one year in the future
const lock = await hre.ethers.deployContract("Lock", [unlockTime], {
value: lockedAmount,
});
// assert that the value is correct
expect(await lock.unlockTime()).to.equal(unlockTime);
});
});
const { expect } = require("chai");
const hre = require("hardhat");
const { time } = require("@nomicfoundation/hardhat-toolbox/network-helpers");
describe("Lock", function () {
it("Should set the right unlockTime", async function () {
const lockedAmount = 1_000_000_000;
const ONE_YEAR_IN_SECS = 365 * 24 * 60 * 60;
const unlockTime = (await time.latest()) + ONE_YEAR_IN_SECS;
// deploy a lock contract where funds can be withdrawn
// one year in the future
const lock = await hre.ethers.deployContract("Lock", [unlockTime], {
value: lockedAmount,
});
// assert that the value is correct
expect(await lock.unlockTime()).to.equal(unlockTime);
});
});
First we import the things we are going to use: the expect
function from chai
to write our assertions, the Hardhat Runtime Environment (hre
), and the network helpers to interact with the Hardhat Network. After that we use the describe
and it
functions, which are global Mocha functions used to describe and group your tests. (You can read more about Mocha here.)
The test itself is what’s inside the callback argument to the it
function. First we set the values for the amount we want to lock (in wei) and the unlock time. For the latter we use time.latest
, a network helper that returns the timestamp of the last mined block. Then we deploy the contract itself: we call ethers.deployContract
with the name of the contract we want to deploy and an array of constructor arguments that has the unlock time. We also pass an object with the transaction parameters. This is optional, but we'll use it to send some ETH by setting its value
field.
Finally, we check that the value returned by the unlockTime()
getter in the contract matches the value that we used when we deployed it. Since all the functions on a contract are async, we have to use the await
keyword to get its value; otherwise, we would be comparing a promise with a number and this would always fail.
#Testing a function that reverts
In the previous test we checked that a getter function returned the correct value. This was a read-only function that can be called without paying a fee and without any risk. Other functions, however, can modify the state of the contract, like the withdraw
function in the Lock
contract. This means that we want some pre-conditions to be met for this function to be called successfully. If you look at its first lines you’ll see a couple of require
checks for that purpose:
function withdraw() public {
require(block.timestamp >= unlockTime, "You can't withdraw yet");
require(msg.sender == owner, "You aren't the owner");
The first statement checks that the unlock time has been reached, and the second one checks that the address calling the contract is its owner. Let’s start by writing a test for the first pre-condition:
it("Should revert with the right error if called too soon", async function () {
// ...deploy the contract as before...
await expect(lock.withdraw()).to.be.revertedWith("You can't withdraw yet");
});
In the previous test we used .to.equal
, which is part of Chai and is used to compare two values. Here we are using .to.be.revertedWith
, which asserts that a transaction reverts, and that the reason string of the revert is equal to the given string. The .to.be.revertedWith
matcher is not part of Chai itself; instead, it’s added by the Hardhat Chai Matchers plugin, which is included in the sample project we are using.
Notice that in the previous test we wrote expect(await ...)
but now we are doing await expect(...)
. In the first case we were comparing two values in a synchronous way; the inner await is just there to wait for the value to be retrieved. In the second case, the whole assertion is async because it has to wait until the transaction is mined. This means that the expect
call returns a promise that we have to await.
#Manipulating the time of the network
We are deploying our Lock
contract with an unlock time of one year. If we want to write a test that checks what happens after the unlock time has passed, we can’t wait that amount of time. We could use a shorter unlock time, like 5 seconds, but that’s a less realistic value and it's still a long time to wait in a test.
The solution is to simulate the passage of time. This can be done with the time.increaseTo
network helper, which mines a new block with the given timestamp:
it("Should transfer the funds to the owner", async function () {
// ...deploy the contract...
await time.increaseTo(unlockTime);
// this will throw if the transaction reverts
await lock.withdraw();
});
As we mentioned, calling lock.withdraw()
returns a Promise. If the transaction fails, the promise will be rejected. Using await
will throw in that case, so the test will fail if the transaction reverts.
#Using a different address
The second check done by the withdraw
function is that the function was called by the owner of the contract. By default, deployments and function calls are done with the first configured account. If we want to check that only the owner can call some function, we need to use a different account and verify that it fails.
The ethers.getSigners()
returns an array with all the configured accounts. We can use the .connect
method of the contract to call the function with a different account and check that the transaction reverts:
it("Should revert with the right error if called from another account", async function () {
// ...deploy the contract...
const [owner, otherAccount] = await hre.ethers.getSigners();
// we increase the time of the chain to pass the first check
await time.increaseTo(unlockTime);
// We use lock.connect() to send a transaction from another account
await expect(lock.connect(otherAccount).withdraw()).to.be.revertedWith(
"You aren't the owner"
);
});
Here again we are calling a function and asserting that it reverts with the correct reason string. The difference is that we are using .connect(anotherAccount)
to call the method from a different address.
#Using fixtures
So far we've deployed the Lock
contract in each test. This means that at the beginning of each test we have to get the contract factory and then deploy the contract. This might be fine for a single contract but, if you have a more complicated setup, each test will have several lines at the beginning just to set up the desired state, and most of the time these lines will be the same.
In a typical Mocha test, this duplication of code is handled with a beforeEach
hook:
import hre from "hardhat";
import { time } from "@nomicfoundation/hardhat-toolbox/network-helpers";
describe("Lock", function () {
let lock: any;
let unlockTime: number;
let lockedAmount = 1_000_000_000;
beforeEach(async function () {
const ONE_YEAR_IN_SECS = 365 * 24 * 60 * 60;
unlockTime = (await time.latest()) + ONE_YEAR_IN_SECS;
lock = await hre.ethers.deployContract("Lock", [unlockTime], {
value: lockedAmount,
});
});
it("some test", async function () {
// use the deployed contract
});
});
const hre = require("hardhat");
const { time } = require("@nomicfoundation/hardhat-toolbox/network-helpers");
describe("Lock", function () {
let lock;
let unlockTime;
let lockedAmount = 1_000_000_000;
beforeEach(async function () {
const ONE_YEAR_IN_SECS = 365 * 24 * 60 * 60;
unlockTime = (await time.latest()) + ONE_YEAR_IN_SECS;
lock = await hre.ethers.deployContract("Lock", [unlockTime], {
value: lockedAmount,
});
});
it("some test", async function () {
// use the deployed contract
});
});
However, there are two problems with this approach:
- If you have to deploy many contracts, your tests will be slower because each one has to send multiple transactions as part of its setup.
- Sharing the variables like this between the
beforeEach
hook and your tests is ugly and error-prone.
The loadFixture
helper in the Hardhat Network Helpers fixes both of these problems. This helper receives a fixture, a function that sets up the chain to some desired state. The first time loadFixture
is called, the fixture is executed. But the second time, instead of executing the fixture again, loadFixture
will reset the state of the network to the point where it was right after the fixture was executed. This is faster, and it undoes any state changes done by the previous test.
This is how our tests look like when a fixture is used:
import { expect } from "chai";
import hre from "hardhat";
import {
time,
loadFixture,
} from "@nomicfoundation/hardhat-toolbox/network-helpers";
describe("Lock", function () {
async function deployOneYearLockFixture() {
const lockedAmount = 1_000_000_000;
const ONE_YEAR_IN_SECS = 365 * 24 * 60 * 60;
const unlockTime = (await time.latest()) + ONE_YEAR_IN_SECS;
const lock = await hre.ethers.deployContract("Lock", [unlockTime], {
value: lockedAmount,
});
return { lock, unlockTime, lockedAmount };
}
it("Should set the right unlockTime", async function () {
const { lock, unlockTime } = await loadFixture(deployOneYearLockFixture);
// assert that the value is correct
expect(await lock.unlockTime()).to.equal(unlockTime);
});
it("Should revert with the right error if called too soon", async function () {
const { lock } = await loadFixture(deployOneYearLockFixture);
await expect(lock.withdraw()).to.be.revertedWith("You can't withdraw yet");
});
it("Should transfer the funds to the owner", async function () {
const { lock, unlockTime } = await loadFixture(deployOneYearLockFixture);
await time.increaseTo(unlockTime);
// this will throw if the transaction reverts
await lock.withdraw();
});
it("Should revert with the right error if called from another account", async function () {
const { lock, unlockTime } = await loadFixture(deployOneYearLockFixture);
const [owner, otherAccount] = await hre.ethers.getSigners();
// we increase the time of the chain to pass the first check
await time.increaseTo(unlockTime);
// We use lock.connect() to send a transaction from another account
await expect(lock.connect(otherAccount).withdraw()).to.be.revertedWith(
"You aren't the owner"
);
});
});
const { expect } = require("chai");
const hre = require("hardhat");
const {
loadFixture,
time,
} = require("@nomicfoundation/hardhat-toolbox/network-helpers");
describe("Lock", function () {
async function deployOneYearLockFixture() {
const lockedAmount = 1_000_000_000;
const ONE_YEAR_IN_SECS = 365 * 24 * 60 * 60;
const unlockTime = (await time.latest()) + ONE_YEAR_IN_SECS;
const lock = await hre.ethers.deployContract("Lock", [unlockTime], {
value: lockedAmount,
});
return { lock, unlockTime, lockedAmount };
}
it("Should set the right unlockTime", async function () {
const { lock, unlockTime } = await loadFixture(deployOneYearLockFixture);
// assert that the value is correct
expect(await lock.unlockTime()).to.equal(unlockTime);
});
it("Should revert with the right error if called too soon", async function () {
const { lock } = await loadFixture(deployOneYearLockFixture);
await expect(lock.withdraw()).to.be.revertedWith("You can't withdraw yet");
});
it("Should transfer the funds to the owner", async function () {
const { lock, unlockTime } = await loadFixture(deployOneYearLockFixture);
await time.increaseTo(unlockTime);
// this will throw if the transaction reverts
await lock.withdraw();
});
it("Should revert with the right error if called from another account", async function () {
const { lock, unlockTime } = await loadFixture(deployOneYearLockFixture);
const [owner, otherAccount] = await hre.ethers.getSigners();
// we increase the time of the chain to pass the first check
await time.increaseTo(unlockTime);
// We use lock.connect() to send a transaction from another account
await expect(lock.connect(otherAccount).withdraw()).to.be.revertedWith(
"You aren't the owner"
);
});
});
The fixture function can return anything you want, and the loadFixture
helper will return it. We recommend returning an object like we did here, so you can extract only the values you care about for that test.
#Other tests
There are several other things you can test, like which events are emitted or how the balances of the involved addresses change. Check the test/Lock.ts
file to see the other examples.
#Measuring code coverage
The Hardhat Toolbox includes the solidity-coverage
plugin to measure the test coverage in your project. Just run the coverage
task and you'll get a report:
npx hardhat coverage
#Using the gas reporter
The Hardhat Toolbox also includes the hardhat-gas-reporter
plugin to get metrics of how much gas is used, based on the execution of your tests. The gas reporter is run when the test
task is executed and the REPORT_GAS
environment variable is set:
REPORT_GAS=true npx hardhat test
#Running tests in parallel
You can run your tests in parallel by using the --parallel
flag:
npx hardhat test --parallel
Alternatively, use parallel: true
in the mocha
section of your Hardhat config.
Most of the time, running your tests serially or in parallel should produce the same results, but there are some scenarios where tests run in parallel will behave differently:
- In serial mode all the test files share the same instance of the Hardhat Runtime Environment, but in parallel mode this is not always the case. Mocha uses a pool of workers to execute the tests, and each worker starts with its own instance of the HRE. This means that if one test file deploys a contract, then that deployment will exist in some of the other test files and it won't in others.
- The
.only
modifier doesn't work in parallel mode. As an alternative, you can use--grep
to run specific tests. - Because parallel mode uses more system resources, the duration of individual tests might be longer, so there's a chance that some tests start timing out for that reason. If you run into this problem, you can increase the tests timeout in the Mocha section of your Hardhat config or using
this.timeout()
in your tests. - The order in which tests are executed is non-deterministic.
There are some other limitations related to parallel mode. You can read more about them in Mocha's docs. And if you are running into some issue when using parallel mode, you can check their Troubleshooting parallel mode section.