Handy utilities for testing contracts in Hardhat projects.
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.
Install with:
npm:
npm install --save-dev hardhat-test-utils hardhat ethers @nomiclabs/hardhat-ethersor, yarn:
yarn add -D hardhat-test-utils hardhat ethers @nomiclabs/hardhat-ethersImport 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';This plugin creates no additional tasks.
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
BigNumberobject.
See API.
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);
});
});The testUtils objects exposes following properties with methods:
Exposes methods to manipulate blocks.
const { block } = testUtils;Returns true if automatic mining is enabled, and false otherwise. See Mining Modes to learn more.
None
<Promise<boolean>>: true if automatic mining is enabled, and false otherwise.
Sets automatic mining mode. See Mining Modes to learn more.
enabled: boolean:trueto enable automatic mining,falseto disable it.
<Promise<boolean>>: Result of the rpc call.
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.
interval: number | BigNumber: Interval in milliseconds.
<Promise<boolean>>: Result of the rpc call.
Returns the latest block information. This is same as calling provider.getBlock('latest') with ethers.
None
<Promise<Block>>: Latest block information.
Returns the latest block number. This is same as calling provider.getBlockNumber() with ethers.
None
<Promise<number>>: Latest block number.
Forces n number of blocks to be mined, incrementing the block height by n.
n: number | BigNumber: Number of blocks to mine. Defaults to1.interval: number | BigNumber: Interval between the timestamps of each block, in seconds. Defaults to1.
<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.
Forces blocks to be mined until the target height` is reached.
target: number | BigNumber: Target block height.interval: number | BigNumber: Interval between the timestamps of each block, in seconds. Defaults to1.
<Promise<boolean>>: Result of the rpc call.
Simulates passing of time.
const { time } = testUtils;Gets the latest block timestamp.
None
<Promise<number>>: Latest block timestamp.
Increases blockchain's time by duration seconds and mines a new block.
duration: number | BigNumber: Number of seconds to increase the time by.
<Promise<number>>: Total time adjustment, in seconds.
Same as time.increase(), but takes the exact timestamp that you want in the next block, and mines that block.
target: number | BigNumber: Target timestamp for the newly mined block.
<Promise<number>>: Total time adjustment, in seconds.
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); // 31536000Available units are minutes, hours, days, weeks, years.
value: number | BigNumber: Value in a time unit to convert to number of seconds.
<Promise<number>>: Number of seconds.
Manipulate addresses.
const { address } = testUtils;Returns true if addr is valid ethereum address, false otherwise.
addr: string: address to check
boolean: true if addr is valid ethereum address, false otherwise.
Returns balance of given address in wei unit.
addr: string: address to fetch balance of.
<Promise<BigNumber>>: balance of given address in wei.
Returns balance of given address in eth unit.
addr: string: address to fetch balance of.
<Promise<BigNumber>>: balance of given address in eth.
Modify the balance of given address.
addr: string: address to modify balance of.balance: number | BigNumber: new balance of given address.
<Promise<boolean>>: result of the rpc call.
Impersonate as specific account and contract addresses and returns the corresponding ethers Signer. See hardhat_impersonateAccount
addr: string: address to impersonate.
<Promise<Signer>>: Signer corresponding to impersonated account.
Stops impersonating an account after having previously used address.impersonate().
addr: string: address to stop impersonating.
<Promise<boolean>>: result of the rpc call.
Blockchain network utilities.
const { network } = testUtils;Takes snapshot of current network state.
None
<Promise<string>>: Snapshot id
Reverts the state of network to a previous snapshot.
snapshotId: string: Id of snapshot to revert to.
<Promise<boolean>>: Result of the rpc call.
Abi encoding utilities.
const { abi } = testUtils;Outputs the function selector of a function.
func: string: Function name with parameter types. E.g."transfer(address,uint256)"
string: Function selector.
Outputs the encoded function call.
func: string: Function name with parameter types. E.g."transfer(address,uint256)"args: any[]: Function arguments. E.g.["0xd55..64b", "10000000"]
string: Abi encoded function call.
Some useful constants.
const { constants } = testUtils;The zero ethereum address - 0x0000000000000000000000000000000000000000
The zero 32 bytes array - 0x0000000000000000000000000000000000000000000000000000000000000000
The BigNumber value representing the maximum uint256 value.
The BigNumber value representing the maximum int256 value.
The BigNumber value representing the minimum int256 value.
The BigNumber value representing 1000000000000000000, which is the number of wei per ether.
Shorthand for ethers BigNumber object.