Smart Contract Testing Guide: Unit Tests, Integration Tests, and Test Coverage

Smart contract testing is the difference between a deployable protocol and an expensive public bug report. Once a contract is on Ethereum mainnet, where the chain ID is 1, you cannot patch that bytecode in place. You can deploy a new contract, migrate users, or use an upgrade pattern if you planned for it, but the original logic stays on-chain.

That is why serious teams treat testing as a layered discipline: unit tests first, integration tests next, coverage tracking throughout, then fuzzing, security review, testnet deployment, and audit for contracts that hold value.

Why Smart Contract Testing Needs a Layered Strategy

Smart contracts run in an adversarial environment. Every function call is public, every storage update can be inspected, and attackers have financial reasons to try edge cases that normal users never hit.

A good test strategy answers three questions:

• Does each function work correctly by itself? That is the job of unit testing.
• Do contracts behave correctly together? That is where integration and end-to-end testing matter.
• How much critical logic is actually exercised? Test coverage gives you a measurable signal, though not a guarantee.

To be blunt, 100 percent line coverage can still miss the bug that drains a pool. Coverage is useful only when the tests include invalid inputs, boundary values, authorization checks, failed transactions, oracle edge cases, and economic invariants.

Unit Tests for Smart Contracts

What Unit Tests Should Prove

Unit tests validate a single function, module, or tightly scoped behavior in isolation. In Solidity 0.8.x, that often means testing one public or external function at a time, plus the internal state changes and events it triggers.

For an ERC-20 contract, unit tests should cover minting, burning, transfers, approvals, allowance changes, access control, and event emissions. For an ERC-721 contract, test minting, ownership, approvals, safe transfers, token URI logic, and burn behavior. Do not stop at the happy path.

A Practical Unit Test Checklist

Before writing code, document the assumptions. Ethereum developer documentation recommends writing down expected business logic and using tests to verify those assumptions. That sounds basic. It saves teams later.

1. Test normal behavior. Check that the expected state changes occur.
2. Test reverts. Unauthorized calls, zero addresses, expired deadlines, insufficient balances, and invalid parameters should fail.
3. Test boundary values. Use minimum values, maximum values, empty arrays, single-item arrays, and repeated calls.
4. Test events. Indexers and off-chain systems often depend on emitted events.
5. Test role changes. Access control bugs are still one of the most common smart contract failure modes.

A small detail that catches newer Solidity developers: OpenZeppelin Contracts 5.x changed some constructor patterns. If you inherit Ownable and forget to pass the initial owner, the compiler can throw TypeError: No arguments passed to the base constructor. Specify the arguments or mark.... A good unit test suite will not fix that compiler error, but it will force you to define who owns the contract at deployment and who can call privileged functions.

Tools for Unit Testing

Hardhat is a strong fit if your team already writes TypeScript or JavaScript. It works well with Ethers.js, Chai matchers, fixtures, local snapshots, and scripts. Use it when readable test code and plugin support matter.

Foundry is my pick for speed, fuzz tests, and Solidity-native test files. It is especially useful when you want tests close to the contract logic. Foundry tests written in Solidity can call cheatcodes such as vm.prank to simulate another caller and vm.expectRevert to verify failed execution.

Truffle still appears in older codebases and training projects. If you maintain one, keep the tests running, but for a new production Ethereum project I would usually choose Hardhat or Foundry.

Integration Tests: Where Contracts Meet Reality

Integration tests verify interactions between contracts and system components. Unit tests may prove that a lending contract calculates collateral correctly. Integration tests prove that the lending contract, ERC-20 collateral token, price oracle, interest model, and liquidation module behave correctly together.

What to Test in Integration Suites

• Token flows: deposits, withdrawals, approvals, transfers, fees, and balance accounting across contracts.
• DeFi sequences: swap, stake, borrow, repay, liquidate, and claim rewards.
• Oracle behavior: stale prices, missing rounds, decimals mismatches, and sudden price moves.
• Governance flows: proposal creation, voting, quorum checks, timelock execution, and failed execution.
• Upgrade paths: storage layout assumptions and initializer behavior for proxy-based systems.

Integration tests should run after unit tests pass. Keep them slower and fewer, but make them realistic. If your protocol depends on Uniswap, Chainlink, Aave, or another third-party protocol, write tests against mocks first, then consider fork tests against a real network state.

With Hardhat or Foundry, mainnet forking can expose mistakes that local mocks hide. One common example is token decimals. USDC uses 6 decimals, while many ERC-20 examples use 18. If your tests only use an 18-decimal mock, your accounting may look fine until a real integration fails.

End-to-End Tests for User Flows

End-to-end tests simulate complete user journeys across the application stack. You do not need hundreds of them. You need the ones that match how people will actually use the protocol.

A few examples:

• DeFi lending: deposit collateral, borrow, accrue interest, repay, withdraw.
• NFT marketplace: mint, approve marketplace, list, buy, transfer, burn.
• DAO governance: create proposal, vote, queue in timelock, execute call.
• Compliance flow: add wallet to whitelist, transfer, revoke wallet, confirm transfer fails.

Organize these tests by user flow, not by contract file. That small choice makes the suite easier to read when something breaks six months later.

Test Coverage: Useful Metric, Dangerous Obsession

Test coverage measures how much of your code or functionality is exercised by tests. The common line coverage formula is:

Test Coverage = Lines Covered by Tests / Total Lines in Application x 100

For smart contracts, many teams target more than 90 percent coverage, with 95 percent or higher for value-bearing systems. Security-critical functions should sit close to 100 percent. That includes functions that move funds, lock funds, change roles, update oracle sources, upgrade contracts, or execute governance decisions.

Still, coverage can lie. A test that calls withdraw() once may cover the line, but it may not prove that partial withdrawals, zero withdrawals, repeated withdrawals, reentrancy attempts, or paused-state withdrawals behave correctly.

Coverage That Actually Matters

Prioritize these areas first:

• Fund movement and accounting invariants
• Access control and role administration
• Upgrade and initialization logic
• External calls to tokens, oracles, bridges, and routers
• Emergency controls such as pause and withdrawal mechanisms
• Boundary conditions around timestamps, block numbers, and rounding

Use solidity-coverage with Hardhat or forge coverage with Foundry. Run coverage in CI, but do not let the percentage become a vanity score. Review uncovered branches by hand. Some uncovered code may be unreachable by design, but you should know why.

Fuzzing and Property-Based Testing

Fuzz testing feeds varied inputs into your contracts to find edge cases you did not write by hand. Foundry makes this unusually accessible: add parameters to a test function, and Foundry will try many values automatically.

Property-based testing goes one step further. Instead of checking one expected output, you define rules that should always hold. For example:

• Total user balances should never exceed total token supply.
• A user should not withdraw more collateral than allowed.
• Only an authorized role should update a price source.
• A completed governance proposal should not execute twice.

This is where smart contract testing starts to feel like security engineering, not ordinary QA. Good. That is the right mindset.

CI/CD, Testnets, and Audits

Run unit and integration tests on every pull request. At minimum, your CI pipeline should install dependencies, compile contracts, run tests, run coverage, and fail on errors. Add static analysis tools such as Slither when the codebase matures.

Before mainnet, deploy to an active testnet. Sepolia is widely used for Ethereum testing. Goerli is deprecated, and Polygon Mumbai has been replaced by Amoy for current Polygon test deployments, so check the network status before building scripts around an old testnet.

Audits are valuable, but they are not a substitute for your own tests. An auditor should receive a codebase that already has passing tests, documented assumptions, coverage reports, and known limitations. Otherwise, you are paying experts to find issues your team should have caught.

Recommended Test Suite Structure

A clean project structure helps as the protocol grows:

• test/unit for isolated function and module tests
• test/integration for contract-to-contract behavior
• test/e2e for user journeys
• test/invariant or test/fuzz for property-based tests
• test/helpers for fixtures, deploy scripts, mock setup, and shared assertions

Keep tests small. Name them clearly. A test called test_RevertWhen_NonOwnerCallsMint tells the next developer far more than testMint2.

Learning Path for Developers

If you are building production contracts, learn testing alongside Solidity, not after. You can connect this topic with structured programmes such as the Certified Smart Contract Developer™, Certified Solidity Developer™, and Certified Blockchain Developer™ credentials. The right order is simple: Solidity fundamentals, ERC standards, testing frameworks, security patterns, then audit preparation.

Start today with one contract. Write unit tests for every public function. Add one integration test that uses two contracts. Run coverage. Then add one fuzz test for the function you trust least. That habit will improve your contracts faster than any checklist sitting in a document.