hardhat-test-utils 🛠

Handy utilities for testing contracts in Hardhat projects.

What

This plugin provides a set of various utility functions for testing solidity smart contracts that in a Hardhat project.

Check Usage or API section for more details.

Installation

Install with:

npm:

npm install --save-dev hardhat-test-utils hardhat ethers @nomiclabs/hardhat-ethers

or, yarn:

yarn add -D hardhat-test-utils hardhat ethers @nomiclabs/hardhat-ethers

Import the plugin in your hardhat.config.js:

require('hardhat-test-utils');

Or if you are using TypeScript, in your hardhat.config.ts:

import 'hardhat-test-utils';

Required plugins

@nomiclabs/hardhat-ethers

Tasks

This plugin creates no additional tasks.

Environment extensions

This plugin adds testUtils object to Hardhat Runtime Environment. This object exposes following properties to manipulate corresponding aspects:

🧱 block: Block related utilities.
⏳ time: Time related utilities.
📃 address: Address related utilities.
⛓️ network: Network related utilities.
🔡 abi: ABI related utilities.
🔩 constants: Common constants.
1️⃣ BN: Shorthand for ethers BigNumber object.

See API.

Usage

There are no additional steps you need to take for this plugin to work.

Install it and access testUtils through the Hardhat Runtime Environment anywhere you need it (tasks, scripts, tests, etc). For example:

const { testUtils } = require('hardhat');

const { time, address, constants } = testUtils;

describe('my tests', function () {
  it('simulates passing of time', async function () {
    const oneHourInSeconds = time.duration.hours(1);
    await time.increase(oneHourInSeconds);
  });

  it('sets the balance of an address', async function () {
    const userAddr = '0x....';
    const newBalance = constants.WEI_PER_ETHER; // 1 ether
    await address.setBalance(userAddr, newBalance);
  });
});

API

The testUtils objects exposes following properties with methods:

`block` 🧱

Exposes methods to manipulate blocks.

const { block } = testUtils;

`block.getAutomine()`

Returns true if automatic mining is enabled, and false otherwise. See Mining Modes to learn more.

Params

None

Returns

<Promise<boolean>>: true if automatic mining is enabled, and false otherwise.

`block.setAutomine(enabled: boolean)`

Sets automatic mining mode. See Mining Modes to learn more.

Params

enabled: boolean: true to enable automatic mining, false to disable it.

Returns

<Promise<boolean>>: Result of the rpc call.

`block.setIntervalMine(interval: number | BigNumber)`

Enables (with a numeric argument greater than 0) or disables (with a numeric argument equal to 0), the automatic mining of blocks at a regular interval of milliseconds, each of which will include all pending transactions. See also Mining Modes.

Params

interval: number | BigNumber: Interval in milliseconds.

Returns

<Promise<boolean>>: Result of the rpc call.

`block.latest()`

Returns the latest block information. This is same as calling provider.getBlock('latest') with ethers.

Params

None

Returns

<Promise<Block>>: Latest block information.

`block.latestNumber()`

Returns the latest block number. This is same as calling provider.getBlockNumber() with ethers.

Params

None

Returns

<Promise<number>>: Latest block number.

`block.advance(n: number | BigNumber, interval: number | BigNumber)`

Forces n number of blocks to be mined, incrementing the block height by n.

Params

n: number | BigNumber: Number of blocks to mine. Defaults to 1.
interval: number | BigNumber: Interval between the timestamps of each block, in seconds. Defaults to 1.

Returns

<Promise<boolean>>: Result of the rpc call.

NOTE: This method can mine any number of blocks at once, in constant time. It exhibits the same performance no matter how many blocks are mined.

`block.advanceTo(target: number | BigNumber, interval: number | BigNumber)`

Forces blocks to be mined until the target height` is reached.

Params

target: number | BigNumber: Target block height.
interval: number | BigNumber: Interval between the timestamps of each block, in seconds. Defaults to 1.

Returns

<Promise<boolean>>: Result of the rpc call.

`time` ⏳

Simulates passing of time.

const { time } = testUtils;

`time.latest()`

Gets the latest block timestamp.

Params

None

Returns

<Promise<number>>: Latest block timestamp.

`time.increase(duration: number | BigNumber)`

Increases blockchain's time by duration seconds and mines a new block.

Params

duration: number | BigNumber: Number of seconds to increase the time by.

Returns

<Promise<number>>: Total time adjustment, in seconds.

`time.increaseTo(target: number | BigNumber)`

Same as time.increase(), but takes the exact timestamp that you want in the next block, and mines that block.

Params

target: number | BigNumber: Target timestamp for the newly mined block.

Returns

<Promise<number>>: Total time adjustment, in seconds.

`time.duration.<unit>(value: number | BigNumber)`

An set of duration object methods to convert time units to seconds. For example:

time.duration.minutes(1); // 60
time.duration.hours(1); // 3600
time.duration.days(1); // 86400
time.duration.weeks(1); // 604800
time.duration.years(1); // 31536000

Available units are minutes, hours, days, weeks, years.

Params

value: number | BigNumber: Value in a time unit to convert to number of seconds.

Returns

<Promise<number>>: Number of seconds.

`address` 📃

Manipulate addresses.

const { address } = testUtils;

`address.isValid(addr: string)`

Returns true if addr is valid ethereum address, false otherwise.

Params

addr: string: address to check

Returns

boolean: true if addr is valid ethereum address, false otherwise.

`address.balance(addr: string)`

Returns balance of given address in wei unit.

Params

addr: string: address to fetch balance of.

Returns

<Promise<BigNumber>>: balance of given address in wei.

`address.balanceEth(addr: string)`

Returns balance of given address in eth unit.

Params

addr: string: address to fetch balance of.

Returns

<Promise<BigNumber>>: balance of given address in eth.

`address.setBalance(addr: string, balance: number | BigNumber)`

Modify the balance of given address.

Params

addr: string: address to modify balance of.
balance: number | BigNumber: new balance of given address.

Returns

<Promise<boolean>>: result of the rpc call.

`address.impersonate(addr: string)`

Impersonate as specific account and contract addresses and returns the corresponding ethers Signer. See hardhat_impersonateAccount

Params

addr: string: address to impersonate.

Returns

<Promise<Signer>>: Signer corresponding to impersonated account.

`address.stopImpersonating(addr: string)`

Stops impersonating an account after having previously used address.impersonate().

Params

addr: string: address to stop impersonating.

Returns

<Promise<boolean>>: result of the rpc call.

`network` ⛓️

Blockchain network utilities.

const { network } = testUtils;

`network.snapshot()`

Takes snapshot of current network state.

Params

None

Returns

<Promise<string>>: Snapshot id

`network.revert(snapshotId: string)`

Reverts the state of network to a previous snapshot.

Params

snapshotId: string: Id of snapshot to revert to.

Returns

<Promise<boolean>>: Result of the rpc call.

`abi` 🔡

Abi encoding utilities.

const { abi } = testUtils;

`abi.encodeFunctionSignature(func: string)`

Outputs the function selector of a function.

Params

func: string: Function name with parameter types. E.g. "transfer(address,uint256)"

Returns

string: Function selector.

`abi.encodeFunctionCall(func: string, args: any[])`

Outputs the encoded function call.

Params

func: string: Function name with parameter types. E.g. "transfer(address,uint256)"
args: any[]: Function arguments. E.g. ["0xd55..64b", "10000000"]

Returns

string: Abi encoded function call.

`constants` 🔩

Some useful constants.

const { constants } = testUtils;

`constants.ZERO_ADDRESS: string`

The zero ethereum address - 0x0000000000000000000000000000000000000000

`constants.ZERO_BYTES32: string`

The zero 32 bytes array - 0x0000000000000000000000000000000000000000000000000000000000000000

`constants.MAX_UINT256: BigNumber`

The BigNumber value representing the maximum uint256 value.

`constants.MAX_INT256: BigNumber`

The BigNumber value representing the maximum int256 value.

`constants.MIN_INT256: BigNumber`

The BigNumber value representing the minimum int256 value.

`constants.WEI_PER_ETHER: BigNumber`

The BigNumber value representing 1000000000000000000, which is the number of wei per ether.

`BN` 1️⃣

Shorthand for ethers BigNumber object.