How to use Hardhat to test a smart contract?

Hardhat is an Ethereum development environment that streamlines smart contract testing with tools like Mocha and Chai, ensuring reliable deployment.

Jul 26, 2025 at 11:15 pm

What Is Hardhat and Why Use It for Smart Contract Testing?

Hardhat is an Ethereum development environment that allows developers to compile, deploy, debug, and test smart contracts efficiently. It provides a local blockchain environment known as Hardhat Network, which mimics the behavior of real Ethereum networks like Mainnet or Ropsten, making it ideal for testing purposes.

One of the key reasons developers prefer Hardhat is its flexibility and rich plugin ecosystem. Whether you're writing unit tests with Mocha, using Chai for assertions, or debugging with built-in tools, Hardhat streamlines the entire smart contract development lifecycle. This makes it particularly useful when you want to ensure your contract logic behaves correctly before deploying it on a live network.

Setting Up Your Development Environment

Before diving into testing, it's essential to set up a proper environment:

• Install Node.js: Make sure Node.js (version 14.x or higher) and npm are installed.
• Initialize a Project: Run npm init -y in your project directory to create a package.json file.
• Install Hardhat: Execute npm install --save-dev hardhat to add Hardhat to your project.
• Create Hardhat Configuration File: Run npx hardhat and select "Create a JavaScript project" to generate the hardhat.config.js file.

Once this setup is complete, you can begin writing and testing your smart contracts.

Writing a Basic Smart Contract for Testing

To demonstrate how to use Hardhat for testing, let’s consider a simple Solidity contract:

// contracts/Token.sol
pragma solidity ^0.8.0;
contract Token {
mapping(address => uint256) public balances;

function transfer(address to, uint256 amount) external {
    require(balances[msg.sender] >= amount, "Insufficient balance");
    balances[msg.sender] -= amount;
    balances[to] += amount;
}

function mint(address account, uint256 amount) external {
    balances[account] += amount;
}
}

This basic token contract includes functions for transferring and minting tokens. The goal is to test whether these functions behave as expected under different scenarios using Hardhat's testing framework.

Configuring the Test Environment

Before writing tests, make sure your project structure supports testing:

• Place your Solidity contracts in the contracts/ folder.
• Store test files in the test/ directory.
• Update hardhat.config.js if needed (e.g., adding networks or plugins).

Here’s a minimal configuration example:

// hardhat.config.js
module.exports = {
  solidity: "0.8.0",
};

With this setup, you’re ready to write and execute tests using Mocha and Chai.

Writing Tests Using Mocha and Chai

Hardhat integrates seamlessly with Mocha, a popular JavaScript test framework, and Chai, an assertion library.

Start by creating a test file in the test/ directory:

// test/token-test.js
const { expect } = require("chai");
describe("Token Contract", function () {
  let Token;
  let hardhatToken;
  let owner;
  let addr1;
beforeEach(async function () {
Token = await ethers.getContractFactory("Token");
[owner, addr1] = await ethers.getSigners();
hardhatToken = await Token.deploy();
await hardhatToken.deployed();
});
it("Should assign the total supply to the owner", async function () {
await hardhatToken.mint(owner.address, 100);
const ownerBalance = await hardhatToken.balances(owner.address);
expect(ownerBalance).to.equal(100);
});
it("Should transfer tokens between accounts", async function () {
await hardhatToken.mint(owner.address, 100);
await hardhatToken.transfer(addr1.address, 50);
const addr1Balance = await hardhatToken.balances(addr1.address);
expect(addr1Balance).to.equal(50);
});
it("Should fail if sender doesn’t have enough tokens", async function () {
const initialOwnerBalance = await hardhatToken.balances(owner.address);
await expect(
  hardhatToken.transfer(addr1.address, 1)
).to.be.revertedWith("Insufficient balance");
expect(await hardhatToken.balances(owner.address)).to.equal(initialOwnerBalance);
});
});

Each test case uses Chai to assert expected outcomes. The beforeEach hook ensures a fresh deployment for every test, preventing interference between test cases.

Running Tests with Hardhat

Once your tests are written, executing them is straightforward:

• Open a terminal in your project root directory.
• Run the command npx hardhat test.

The output will show the results of each test, including passed and failed cases. If any test fails, Hardhat will display detailed error messages to help identify issues quickly.

For more granular control, you can run specific test files by appending the file path:

npx hardhat test test/token-test.js

This allows you to focus on specific contract behaviors without re-running the entire test suite.

---

Frequently Asked Questions

Q: Can I use Hardhat without Solidity?

Yes, while Hardhat is primarily designed for Solidity, it can also be used with other EVM-compatible languages such as Vyper, although community support may vary.

Q: How do I debug failed tests in Hardhat?

Use console.log from @nomiclabs/hardhat-waffle or the Hardhat Runtime Environment (HRE) to print variable values during test execution. Additionally, inspect the transaction receipts and revert reasons provided in the test output.

Q: Can I test contract upgrades using Hardhat?

Yes, Hardhat supports proxy patterns through plugins like @openzeppelin/hardhat-upgrades, allowing you to simulate and test upgradeable contracts locally.

Q: Are there alternatives to Mocha and Chai for testing in Hardhat?

While Mocha and Chai are widely adopted, you can integrate other testing frameworks like Jest with additional configuration, though native support and documentation are more mature for Mocha and Chai.