{"id":18786343,"url":"https://github.com/nvnx7/hardhat-test-utils","last_synced_at":"2025-04-13T12:34:16.227Z","repository":{"id":41900935,"uuid":"479000531","full_name":"nvnx7/hardhat-test-utils","owner":"nvnx7","description":"Utilities for testing hardhat contracts","archived":false,"fork":false,"pushed_at":"2022-04-23T18:00:31.000Z","size":276,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-27T04:12:20.385Z","etag":null,"topics":["ethereum","hardhat","hardhat-plugin","smart-contracts","solidity"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/hardhat-test-utils","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nvnx7.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-04-07T13:36:37.000Z","updated_at":"2022-09-23T09:23:30.000Z","dependencies_parsed_at":"2022-08-11T20:40:23.583Z","dependency_job_id":null,"html_url":"https://github.com/nvnx7/hardhat-test-utils","commit_stats":null,"previous_names":["nvnx7/hardhat-test-utils"],"tags_count":3,"template":false,"template_full_name":"NomicFoundation/hardhat-ts-plugin-boilerplate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvnx7%2Fhardhat-test-utils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvnx7%2Fhardhat-test-utils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvnx7%2Fhardhat-test-utils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvnx7%2Fhardhat-test-utils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nvnx7","download_url":"https://codeload.github.com/nvnx7/hardhat-test-utils/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248714754,"owners_count":21149961,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ethereum","hardhat","hardhat-plugin","smart-contracts","solidity"],"created_at":"2024-11-07T20:51:20.375Z","updated_at":"2025-04-13T12:34:15.828Z","avatar_url":"https://github.com/nvnx7.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hardhat-test-utils 🛠\n\n[![npm version](https://badge.fury.io/js/hardhat-test-utils.svg)](https://badge.fury.io/js/hardhat-test-utils)\n[![Node.js CI](https://github.com/theNvN/hardhat-test-utils/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/theNvN/hardhat-test-utils/actions/workflows/ci.yml)\n\nHandy utilities for testing contracts in [Hardhat](https://hardhat.org) projects.\n\n## What\n\nThis plugin provides a set of various utility functions for testing solidity smart contracts that in a [Hardhat](https://hardhat.org) project.\n\nCheck [Usage](#usage) or [API](#api) section for more details.\n\n## Installation\n\nInstall with:\n\n**npm**:\n\n```bash\nnpm install --save-dev hardhat-test-utils hardhat ethers @nomiclabs/hardhat-ethers\n```\n\nor, **yarn**:\n\n```bash\nyarn add -D hardhat-test-utils hardhat ethers @nomiclabs/hardhat-ethers\n```\n\nImport the plugin in your `hardhat.config.js`:\n\n```js\nrequire('hardhat-test-utils');\n```\n\nOr if you are using TypeScript, in your `hardhat.config.ts`:\n\n```ts\nimport 'hardhat-test-utils';\n```\n\n## Required plugins\n\n- [@nomiclabs/hardhat-ethers](https://hardhat.org/plugins/nomiclabs-hardhat-ethers.html)\n\n## Tasks\n\nThis plugin creates no additional tasks.\n\n## Environment extensions\n\nThis plugin adds `testUtils` object to Hardhat Runtime Environment. This object exposes following properties to manipulate corresponding aspects:\n\n- [🧱 block](#block-🧱): Block related utilities.\n- [⏳ time](#time-⏳): Time related utilities.\n- [📃 address](#address-📃): Address related utilities.\n- [⛓️ network](#network-⛓️): Network related utilities.\n- [🔡 abi](#abi-🔡): ABI related utilities.\n- [🔩 constants](#constants-🔩): Common constants.\n- [1️⃣ BN](#bn-1️⃣): Shorthand for ethers [`BigNumber`](https://docs.ethers.io/v5/api/utils/bignumber/#BigNumber) object.\n\nSee [API](#api).\n\n## Usage\n\nThere are no additional steps you need to take for this plugin to work.\n\nInstall it and access `testUtils` through the Hardhat Runtime Environment anywhere\nyou need it (tasks, scripts, tests, etc). For example:\n\n```js\nconst { testUtils } = require('hardhat');\n\nconst { time, address, constants } = testUtils;\n\ndescribe('my tests', function () {\n  it('simulates passing of time', async function () {\n    const oneHourInSeconds = time.duration.hours(1);\n    await time.increase(oneHourInSeconds);\n  });\n\n  it('sets the balance of an address', async function () {\n    const userAddr = '0x....';\n    const newBalance = constants.WEI_PER_ETHER; // 1 ether\n    await address.setBalance(userAddr, newBalance);\n  });\n});\n```\n\n## API\n\nThe `testUtils` objects exposes following properties with methods:\n\n### `block` 🧱\n\nExposes methods to manipulate blocks.\n\n```js\nconst { block } = testUtils;\n```\n\n---\n\n#### `block.getAutomine()`\n\nReturns true if automatic mining is enabled, and false otherwise. See [Mining Modes](https://hardhat.org/hardhat-network/explanation/mining-modes.html) to learn more.\n\n##### Params\n\nNone\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: `true` if automatic mining is enabled, and `false` otherwise.\n\n---\n\n#### `block.setAutomine(enabled: boolean)`\n\nSets automatic mining mode. See [Mining Modes](https://hardhat.org/hardhat-network/explanation/mining-modes.html) to learn more.\n\n##### Params\n\n- `enabled: boolean`: `true` to enable automatic mining, `false` to disable it.\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: Result of the rpc call.\n\n---\n\n#### `block.setIntervalMine(interval: number | BigNumber)`\n\nEnables (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](https://hardhat.org/hardhat-network/explanation/mining-modes.html).\n\n##### Params\n\n- `interval: number | BigNumber`: Interval in milliseconds.\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: Result of the rpc call.\n\n---\n\n#### `block.latest()`\n\nReturns the latest block information. This is same as calling `provider.getBlock('latest')` with [ethers](https://docs.ethers.io/v5/api/providers/provider/#Provider-getBlock).\n\n##### Params\n\nNone\n\n##### Returns\n\n`\u003cPromise\u003cBlock\u003e\u003e`: Latest block information.\n\n---\n\n#### `block.latestNumber()`\n\nReturns the latest block number. This is same as calling `provider.getBlockNumber()` with [ethers](https://docs.ethers.io/v5/api/providers/provider/#Provider-getBlockNumber).\n\n##### Params\n\nNone\n\n##### Returns\n\n`\u003cPromise\u003cnumber\u003e\u003e`: Latest block number.\n\n---\n\n#### `block.advance(n: number | BigNumber, interval: number | BigNumber)`\n\nForces `n` number of blocks to be mined, incrementing the block height by `n`.\n\n##### Params\n\n- `n: number | BigNumber`: Number of blocks to mine. Defaults to `1`.\n- `interval: number | BigNumber`: Interval between the timestamps of each block, in seconds. Defaults to `1`.\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: Result of the rpc call.\n\n**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.\n\n---\n\n#### `block.advanceTo(target: number | BigNumber, interval: number | BigNumber)`\n\nForces blocks to be mined until the `target` height` is reached.\n\n##### Params\n\n- `target: number | BigNumber`: Target block height.\n- `interval: number | BigNumber`: Interval between the timestamps of each block, in seconds. Defaults to `1`.\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: Result of the rpc call.\n\n---\n\n---\n\n### `time` ⏳ \n\nSimulates passing of time.\n\n```js\nconst { time } = testUtils;\n```\n\n---\n\n#### `time.latest()`\n\nGets the latest block timestamp.\n\n##### Params\n\nNone\n\n##### Returns\n\n`\u003cPromise\u003cnumber\u003e\u003e`: Latest block timestamp.\n\n---\n\n#### `time.increase(duration: number | BigNumber)`\n\nIncreases blockchain's time by `duration` seconds and mines a new block.\n\n##### Params\n\n- `duration: number | BigNumber`: Number of seconds to increase the time by.\n\n##### Returns\n\n`\u003cPromise\u003cnumber\u003e\u003e`: Total time adjustment, in seconds.\n\n---\n\n#### `time.increaseTo(target: number | BigNumber)`\n\nSame as `time.increase()`, but takes the exact timestamp that you want in the next block, and mines that block.\n\n##### Params\n\n- `target: number | BigNumber`: Target timestamp for the newly mined block.\n\n##### Returns\n\n`\u003cPromise\u003cnumber\u003e\u003e`: Total time adjustment, in seconds.\n\n---\n\n#### `time.duration.\u003cunit\u003e(value: number | BigNumber)`\n\nAn set of `duration` object methods to convert time units to seconds. For example:\n\n```js\ntime.duration.minutes(1); // 60\ntime.duration.hours(1); // 3600\ntime.duration.days(1); // 86400\ntime.duration.weeks(1); // 604800\ntime.duration.years(1); // 31536000\n```\n\nAvailable units are `minutes`, `hours`, `days`, `weeks`, `years`.\n\n##### Params\n\n- `value: number | BigNumber`: Value in a time unit to convert to number of seconds.\n\n##### Returns\n\n`\u003cPromise\u003cnumber\u003e\u003e`: Number of seconds.\n\n---\n\n---\n\n### `address` 📃\n\nManipulate addresses.\n\n```js\nconst { address } = testUtils;\n```\n\n---\n\n#### `address.isValid(addr: string)`\n\nReturns true if `addr` is valid ethereum address, false otherwise.\n\n##### Params\n\n- `addr: string`: address to check\n\n##### Returns\n\n`boolean`: true if `addr` is valid ethereum address, false otherwise.\n\n---\n\n#### `address.balance(addr: string)`\n\nReturns balance of given address in wei unit.\n\n##### Params\n\n- `addr: string`: address to fetch balance of.\n\n##### Returns\n\n`\u003cPromise\u003cBigNumber\u003e\u003e`: balance of given address in wei.\n\n---\n\n#### `address.balanceEth(addr: string)`\n\nReturns balance of given address in eth unit.\n\n##### Params\n\n- `addr: string`: address to fetch balance of.\n\n#### Returns\n\n`\u003cPromise\u003cBigNumber\u003e\u003e`: balance of given address in eth.\n\n---\n\n#### `address.setBalance(addr: string, balance: number | BigNumber)`\n\nModify the balance of given address.\n\n##### Params\n\n- `addr: string`: address to modify balance of.\n- `balance: number | BigNumber`: new balance of given address.\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: result of the rpc call.\n\n---\n\n#### `address.impersonate(addr: string)`\n\nImpersonate as specific account and contract addresses and returns the corresponding ethers [`Signer`](https://docs.ethers.io/v5/api/signer/#Signer). See [hardhat_impersonateAccount](https://hardhat.org/hardhat-network/reference/#hardhat-impersonateaccount)\n\n##### Params\n\n- `addr: string`: address to impersonate.\n\n##### Returns\n\n`\u003cPromise\u003cSigner\u003e\u003e`: Signer corresponding to impersonated account.\n\n---\n\n#### `address.stopImpersonating(addr: string)`\n\nStops impersonating an account after having previously used `address.impersonate()`.\n\n##### Params\n\n- `addr: string`: address to stop impersonating.\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: result of the rpc call.\n\n---\n\n---\n\n### `network` ⛓️\n\nBlockchain network utilities.\n\n```js\nconst { network } = testUtils;\n```\n\n---\n\n#### `network.snapshot()`\n\nTakes snapshot of current network state.\n\n##### Params\n\nNone\n\n##### Returns\n\n`\u003cPromise\u003cstring\u003e\u003e`: Snapshot id\n\n---\n\n#### `network.revert(snapshotId: string)`\n\nReverts the state of network to a previous snapshot.\n\n##### Params\n\n- `snapshotId: string`: Id of snapshot to revert to.\n\n##### Returns\n\n`\u003cPromise\u003cboolean\u003e\u003e`: Result of the rpc call.\n\n---\n\n---\n\n### `abi` 🔡\nAbi encoding utilities.\n\n```js\nconst { abi } = testUtils;\n```\n---\n\n#### `abi.encodeFunctionSignature(func: string)`\n\nOutputs the function selector of a function.\n\n##### Params\n\n- `func: string`: Function name with parameter types. E.g. `\"transfer(address,uint256)\"`\n\n##### Returns\n\n`string`: Function selector.\n\n---\n\n#### `abi.encodeFunctionCall(func: string, args: any[])`\nOutputs the encoded function call.\n\n##### Params\n\n- `func: string`: Function name with parameter types. E.g. `\"transfer(address,uint256)\"`\n- `args: any[]`: Function arguments. E.g. `[\"0xd55..64b\", \"10000000\"]`\n\n##### Returns\n\n`string`: Abi encoded function call.\n\n---\n\n---\n\n### `constants` 🔩\n\nSome useful constants.\n\n```js\nconst { constants } = testUtils;\n```\n\n---\n\n#### `constants.ZERO_ADDRESS: string`\n\nThe zero ethereum address - `0x0000000000000000000000000000000000000000`\n\n---\n\n#### `constants.ZERO_BYTES32: string`\n\nThe zero 32 bytes array - `0x0000000000000000000000000000000000000000000000000000000000000000`\n\n---\n\n#### `constants.MAX_UINT256: BigNumber`\n\nThe `BigNumber` value representing the maximum `uint256` value.\n\n---\n\n#### `constants.MAX_INT256: BigNumber`\n\nThe `BigNumber` value representing the maximum `int256` value.\n\n---\n\n#### `constants.MIN_INT256: BigNumber`\n\nThe `BigNumber` value representing the minimum `int256` value.\n\n---\n\n#### `constants.WEI_PER_ETHER: BigNumber`\n\nThe `BigNumber` value representing `1000000000000000000`, which is the number of wei per ether.\n\n---\n\n---\n\n### `BN` 1️⃣\n\nShorthand for ethers [`BigNumber`](https://docs.ethers.io/v5/api/utils/bignumber/#BigNumber) object.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvnx7%2Fhardhat-test-utils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvnx7%2Fhardhat-test-utils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvnx7%2Fhardhat-test-utils/lists"}