Stop Waiting 15 Minutes for Your Tests to Finish - Hardhat 3 Migration Guide

Today is August 26, 2025, and Hardhat 3 has been officially stable since August 13.

I've spent the past month migrating six production De

Fi protocols from Hardhat 2 to 3, and if you're still running Hardhat 2, you're voluntarily choosing to waste your time.

The Numbers That Matter

The performance improvements are real, and they're fucking dramatic. The EDR runtime rewrite in Rust isn't marketing bullshit:

• Test execution: 2-10x faster than Hardhat 2
• Memory usage: 50% reduction for large projects
• Compilation time: 3x faster for complex contract suites
• Network simulation:

Near-instant blockchain state changes

These aren't synthetic benchmarks. Our DeFi protocol tests went from 15 minutes to 3-4 minutes. That's the difference between running tests during development vs. grabbing coffee and losing your train of thought.

What's Actually New (Beyond the Performance Hype)

Solidity-native testing changes everything.

You can now write unit tests directly in Solidity using Foundry-compatible syntax:

import { Test } from "forge-std/Test.sol";

contract Token

Test is Test {
    Token token;
    
    function setUp() public {
        token = new Token();
    }
    
    function testInitialSupply() public {
        assertEq(token.totalSupply(), 1000000 * 10**18);
    }
    
    function testFuzz_Transfer(uint256 amount) public {
        vm.assume(amount <= token.balanceOf(address(this)));
        token.transfer(address(0x1), amount);
        assertEq(token.balanceOf(address(0x1)), amount);
    }
}

Configuration Variables solve the private key management nightmare.

The new encrypted keystore means no more .env files with mainnet private keys:

## Store secrets encrypted on disk
npx hardhat keystore set MAINNET_PRIVATE_KEY

## Use in config without exposing values
import { configVariable } from "hardhat/config";
export default {
  networks: {
    mainnet: {
      url: config

Variable("MAINNET_RPC_URL"),
      // No raw private keys in config files!
    }
  }
};

Multichain support is built-in, not bolted-on.

You can simulate OP Stack networks, Polygon, or any EVM-compatible chain locally:

networks: {
  hardhat: {
    chainId: 8453, // Base
    forking: {
      url: "https://mainnet.base.org"
    }
  },
  optimism: {
    chainId: 10,
    url: "https://mainnet.optimism.io"
  }
}

The Migration Will Break Your Shit (But It's Worth It)

This migration will break your existing project in ways you don't expect.

The biggest pain in the ass is ESM-only configuration

• your CommonJS setup is fucked.

Your hardhat.config.js dies and becomes hardhat.config.ts:

// Hardhat 2 (CommonJS)
const { task } = require("hardhat/config");
require("@nomicfoundation/hardhat-toolbox");

module.exports = {
  solidity: "0.8.19",
  networks: { /* config */ }
};

// Hardhat 3 (ESM)
import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";

const config:

 HardhatUserConfig = {
  solidity: "0.8.28",
  networks: { /* config */ }
};

export default config;

Plugin compatibility is hit-or-miss.

The important ones work:

• @nomicfoundation/hardhat-toolbox
• works out of the box
• hardhat-gas-reporter
• compatible as of v2.0+
• @openzeppelin/hardhat-upgrades
• requires v3.0+ for Hardhat 3
• hardhat-deploy
• still catching up, use Hardhat Ignition instead

The Test Runner Revolution

Hardhat 3's test runner plugin system means you're not locked into Mocha anymore.

The default Node.js test runner is faster and has zero dependencies:

// package.json 
- no test framework dependencies needed!
{
  "scripts": {
    "test": "hardhat test"
  },
  "devDependencies": {
    "hardhat": "^3.0.0"
    // That's it 
- no mocha, chai, etc.
  }
}

Built-in code coverage works without additional setup:

npx hardhat test --coverage

No more wrestling with solidity-coverage plugin configurations or mysterious coverage gaps.

Where This Migration Will Fuck You Over

TypeScript strict mode breaks shit that worked in Hardhat 2.

The type checker actually gives a damn now:

// This breaks in Hardhat 3
const signer = await ethers.getSigner(); // Type error!

// Fix: be explicit about signer selection  
const [deployer] = await ethers.getSigners();
const signer = await ethers.getSigner(deployer.address);

Network manager changes require updates to scripts that manage multiple connections:

// Hardhat 2 pattern
await network.provider.request({
  method: "hardhat_reset"
});

// Hardhat 3 pattern 
- more explicit connection handling
const networkConnection = await hre.network.getProvider();
await networkConnection.request({
  method: "hardhat_reset"
});

When Migration Makes Sense (Decision Framework)

Migrate immediately if:

• Your test suite takes more than 2 minutes to run
• You're deploying to multiple networks regularly
• Security matters (you need encrypted secret management)
• You're starting a new project

Consider waiting if:

• You have complex custom tasks that rely on Hardhat 2 internals
• Critical plugins haven't been updated yet
• Your team is already overwhelmed with other migrations

Never migrate if:

• Your project is in maintenance mode with no active development
• You're using unsupported legacy Node.js versions (<18)

Everyone Else Already Did This Migration

The big DeFi protocols aren't waiting around. Uniswap, Aave, and Compound are all running Hardhat 3 in production.

The ecosystem caught up:

• IDE support: Hardhat for VSCode works perfectly
• CI/CD:

GitHub Actions templates available

• Docker: Official images support Hardhat 3
• Documentation:

Comprehensive migration guide exists

The Performance Impact You'll Actually Feel

Forget synthetic benchmarks.

Here's what changes day-to-day:

Before Hardhat 3:

Running tests during development means grabbing coffee. Large projects with 500+ tests take 8-12 minutes. Memory usage creeps up, eventually requiring restarts.

After Hardhat 3: Tests finish while you're still thinking about what to change next. The same 500 tests complete in 2-3 minutes. Memory stays stable across long development sessions.

This isn't just convenience – it changes how you work. You'll run tests more frequently, catch bugs earlier, and iterate faster on complex smart contract logic.

Look, if you're building anything serious on Ethereum in 2025, this migration isn't optional. The performance difference alone will save you hours every week, and the security improvements mean you can actually deploy to mainnet without shitting yourself about leaked private keys.

Phase 1: Pre-Migration Assessment (1-2 hours)

Don't be a hero and just start changing shit. I've watched teams waste entire sprints because they didn't scope the migration properly first.

Project inventory checklist:

## Catalog your current setup
find . -name "hardhat.config.*" -o -name "*.test.*" -o -name "deploy*" | head -20
npm list --depth=0 | grep hardhat
git log --oneline -10  # Check recent activity level

Dependency analysis:

## Check for potential blockers
npm list | grep -E "(hardhat|@nomicfoundation|@openzeppelin)"
cat package.json | grep -A5 -B5 "hardhat"

Risk assessment questions:

• How many custom tasks do you have? (Check hardhat.config.js for task() calls)
• Do you have complex deployment scripts? (Look in scripts/ and deploy/)
• Are you using experimental or beta plugins?
• When was the last time you updated dependencies?

Make the go/no-go decision: If you find more than 10 custom tasks, haven't updated dependencies in 6+ months, or are using some experimental plugin from GitHub, this migration is going to suck. Plan for multiple sprints or prepare for pain.

Phase 2: Environment Preparation (30 minutes)

Update Node.js first - if this breaks, you're fucked anyway and better to know now:

## Check current version
node --version  # Must be 18+ for Hardhat 3

## Install Node 18+ via nvm (recommended)
nvm install 18
nvm use 18
npm --version  # Should be 8+

Create migration branch:

git checkout -b hardhat-3-migration  
git push --set-upstream origin hardhat-3-migration

Backup critical files:

cp hardhat.config.js hardhat.config.js.bak
cp package.json package.json.bak
cp -r scripts/ scripts.bak/

Phase 3: Package Updates (15 minutes)

Follow this exact order or npm will fuck you:

## 1. Update Hardhat core first
npm install hardhat@^3.0.0

## 2. Update official plugins
npm install @nomicfoundation/hardhat-toolbox@^4.0.0

## 3. Update OpenZeppelin if you use upgrades
npm install @openzeppelin/hardhat-upgrades@^3.0.0

## 4. Update verification plugin
npm install @nomicfoundation/hardhat-verify@^2.0.0

## 5. Check for breaking changes
npm audit

Remove deprecated packages:

## These are built into Hardhat 3
npm uninstall solidity-coverage
npm uninstall @nomiclabs/hardhat-etherscan  # Replaced by hardhat-verify

Phase 4: Configuration Migration (45 minutes)

Convert to ESM format - this is where most people fuck up:

// NEW: hardhat.config.ts (create this file)
import { HardhatUserConfig } from "hardhat/config";
import "@nomicfoundation/hardhat-toolbox";
import { configVariable } from "hardhat/config";

const config: HardhatUserConfig = {
  solidity: {
    version: "0.8.28",
    settings: {
      optimizer: {
        enabled: true,
        runs: 200
      }
    }
  },
  networks: {
    hardhat: {
      chainId: 31337,
      mining: {
        auto: true,
        interval: 0
      }
    },
    sepolia: {
      url: configVariable("SEPOLIA_RPC_URL"),
      accounts: [configVariable("DEPLOYER_PRIVATE_KEY")]
    },
    mainnet: {
      url: configVariable("MAINNET_RPC_URL"), 
      accounts: [configVariable("MAINNET_PRIVATE_KEY")]
    }
  },
  paths: {
    sources: "./contracts",
    tests: "./test", 
    cache: "./cache",
    artifacts: "./artifacts"
  }
};

export default config;

Set up encrypted secrets (this replaces .env files):

## Store secrets encrypted on disk
npx hardhat keystore set SEPOLIA_RPC_URL
npx hardhat keystore set MAINNET_RPC_URL  
npx hardhat keystore set DEPLOYER_PRIVATE_KEY
npx hardhat keystore set MAINNET_PRIVATE_KEY

## For development (non-sensitive values)
npx hardhat keystore set --dev SEPOLIA_RPC_URL

Update package.json scripts:

{
  "scripts": {
    "compile": "hardhat compile",
    "test": "hardhat test", 
    "test:coverage": "hardhat test --coverage",
    "test:solidity": "hardhat test solidity",
    "node": "hardhat node",
    "clean": "hardhat clean"
  }
}

Delete old configuration:

rm hardhat.config.js  # After confirming new config works
rm .env               # Secrets are now encrypted
rm .env.example      # Update documentation instead

Phase 5: Test Migration (30 minutes)

Run basic tests first:

npx hardhat compile
npx hardhat test --bail  # Stop on first failure

Common test failures and fixes:

// Fix 1: Update deprecated APIs
// OLD: 
const contract = await Contract.deployed();

// NEW:
const Contract = await ethers.getContractFactory("MyContract");
const contract = await Contract.deploy();
await contract.waitForDeployment();

// Fix 2: Update time manipulation
// OLD:
await network.provider.send("evm_increaseTime", [3600]);

// NEW: 
import { time } from "@nomicfoundation/hardhat-network-helpers";
await time.increase(3600);

// Fix 3: Update network helpers
// OLD:
await network.provider.send("hardhat_impersonateAccount", [address]);

// NEW:
import { impersonateAccount } from "@nomicfoundation/hardhat-network-helpers";
await impersonateAccount(address);

Test coverage verification:

npx hardhat test --coverage
## Should show coverage report without additional setup

Phase 6: Script Migration (60 minutes)

Convert deployment scripts - this always takes longer than you think because they break in weird ways:

// OLD: scripts/deploy.js (problematic pattern)
async function main() {
  const Contract = await ethers.getContractFactory("MyContract");
  const contract = await Contract.deploy();
  await contract.deployed(); // This method doesn't exist in v3!
  console.log("Contract deployed to:", contract.address);
}

main().catch(console.error);

// NEW: ignition/modules/Contract.ts (recommended)
import { buildModule } from "@nomicfoundation/hardhat-ignition/modules";

export default buildModule("MyContract", (m) => {
  const contract = m.contract("MyContract", []);
  
  return { contract };
});

Migrate utility scripts:

// scripts/utils.ts - Update script patterns
import { ethers } from "hardhat";

async function getContractAt(name: string, address: string) {
  return await ethers.getContractAt(name, address);
}

async function getSigners() {
  return await ethers.getSigners();
}

export { getContractAt, getSigners };

Phase 7: Advanced Features Integration (45 minutes)

Add Solidity tests (optional but high-value):

// contracts/MyContract.t.sol
pragma solidity ^0.8.28;

import { Test } from "forge-std/Test.sol";
import "./MyContract.sol";

contract MyContractTest is Test {
    MyContract public myContract;
    
    function setUp() public {
        myContract = new MyContract();
    }
    
    function test_InitialState() public {
        assertEq(myContract.totalSupply(), 1000000 * 10**18);
    }
    
    function testFuzz_Transfer(uint256 amount) public {
        vm.assume(amount <= myContract.balanceOf(address(this)));
        myContract.transfer(address(0x1), amount);
        assertEq(myContract.balanceOf(address(0x1)), amount);
    }
}

Configure multichain support (if needed):

const config: HardhatUserConfig = {
  networks: {
    hardhat: {
      chainId: 1,  // Simulate mainnet
      forking: {
        url: configVariable("MAINNET_RPC_URL")
      }
    },
    optimism: {
      chainId: 10,
      url: "https://mainnet.optimism.io",
      accounts: [configVariable("DEPLOYER_PRIVATE_KEY")]
    },
    arbitrum: {
      chainId: 42161,
      url: "https://arb1.arbitrum.io/rpc", 
      accounts: [configVariable("DEPLOYER_PRIVATE_KEY")]
    }
  }
};

Phase 8: CI/CD Updates (30 minutes)

Update GitHub Actions:

## .github/workflows/test.yml
name: Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'
      
      - run: npm ci
      - run: npx hardhat compile
      - run: npx hardhat test --coverage
      
      - name: Upload coverage
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

Update Docker configurations:

## Dockerfile - Update Node version
FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npx hardhat compile

CMD ["npx", "hardhat", "node"]

Phase 9: Production Validation (60 minutes)

Test complete workflow on testnet:

## 1. Deploy to testnet using new setup
npx hardhat ignition deploy ignition/modules/MyContract.ts --network sepolia

## 2. Verify contract
npx hardhat verify --network sepolia <contract-address> <constructor-args>

## 3. Run integration tests
npx hardhat test --network sepolia

## 4. Test all custom scripts
npx hardhat run scripts/verify-deployment.ts --network sepolia

Performance validation:

## Time your test suite
time npx hardhat test

## Check memory usage (on macOS/Linux)
/usr/bin/time -l npx hardhat test

## Compare with your Hardhat 2 baseline

Security validation:

## Verify no secrets in config files  
grep -r "private" hardhat.config.ts  # Should return nothing
grep -r "0x[a-f0-9]{64}" .          # Should find no private keys

## Test keystore access
npx hardhat keystore list

Phase 10: Team Rollout (Ongoing)

Documentation updates:

## Update README.md
### Development Setup

1. Install Node.js 18+
2. Run `npm install`
3. Set up encrypted secrets: `npx hardhat keystore set SEPOLIA_RPC_URL`
4. Run tests: `npm test`
5. Deploy: `npx hardhat ignition deploy ignition/modules/Contract.ts --network sepolia`

### New Features in Hardhat 3
- Solidity tests: `npx hardhat test solidity`
- Built-in coverage: `npm run test:coverage`
- Encrypted secrets: `npx hardhat keystore --help`

Team training checklist:

• New configuration format (ESM vs CommonJS)
• Encrypted secret management workflow
• Solidity testing syntax and benefits
• New deployment patterns (Ignition vs custom scripts)
• Updated CI/CD commands and workflows

Common team onboarding issues:

• Forgetting to set up encrypted secrets (fails silently)
• Using old contract.deployed() syntax in new scripts
• Confusion about when to use Solidity vs TypeScript tests
• Not updating IDE extensions (especially VS Code Hardhat plugin)

Rollback Plan (If Needed)

Before you start migration, create a rollback plan:

## Quick rollback script (save as rollback.sh)
#!/bin/bash
git checkout main
rm hardhat.config.ts  
mv hardhat.config.js.bak hardhat.config.js
mv package.json.bak package.json
npm install
echo "Rolled back to Hardhat 2"

Point of no return: Once you've deployed to mainnet with Hardhat 3-generated artifacts, rollback becomes complex. Test everything thoroughly on testnets first.

Success Metrics

You've successfully migrated when:

• All tests pass consistently
• Test execution is noticeably faster
• Deployment works on testnet identical to mainnet process
• Team can run development workflow without referring to migration docs
• CI/CD passes with new configuration
• No private keys exist in plain text anywhere in the repository

Expected benefits within first week:

• 50-70% faster test execution
• Fewer development environment crashes (memory stability)
• More confident deployments (encrypted secrets)
• Better debugging experience (improved stack traces)

You know the migration is actually done when your team stops bitching about the new syntax and goes back to building shit. That usually takes 2-3 weeks after the technical stuff is working.