Ethereum Waffle is a comprehensive smart contract testing framework that provides a sweet set of chai matchers for Ethereum development, enabling developers to write expressive and maintainable test suites for Solidity smart contracts. The framework focuses on simplicity with minimal dependencies, enhanced syntax with custom chai matchers for contract interactions, and optimized performance for fast test execution.
npm install ethereum-waffleimport { deployContract, MockProvider, solidity } from "ethereum-waffle";For CommonJS:
const { deployContract, MockProvider, solidity } = require("ethereum-waffle");import { deployContract, MockProvider, solidity, loadFixture } from "ethereum-waffle";
import { use } from "chai";
import { ethers } from "ethers";
// Enable Waffle chai matchers
use(solidity);
// Create test setup with MockProvider
const [wallet, otherWallet] = new MockProvider().getWallets();
// Deploy a contract from JSON artifact
const contract = await deployContract(wallet, contractJson, [constructorArg]);
// Use enhanced chai matchers for testing
await expect(contract.someFunction()).to.be.reverted;
await expect(contract.transfer(otherWallet.address, 100))
.to.emit(contract, 'Transfer')
.withArgs(wallet.address, otherWallet.address, 100);
// Test balance changes
await expect(() => wallet.sendTransaction({
to: otherWallet.address,
value: ethers.utils.parseEther("1.0")
})).to.changeEtherBalance(otherWallet, ethers.utils.parseEther("1.0"));
// Use fixtures for complex test setup
const loadedFixture = await loadFixture(myFixture);Ethereum Waffle is built around several key components:
MockProvider extends Web3Provider with call history tracking, pre-funded accounts, and ENS supportdeployContract supports both JSON artifacts and TypeChain factories with type safetydeployMockContract creates fully configurable mock contracts for testing interactionssolidity plugin adds 17+ custom matchers for contract-specific assertionsloadFixture provides automatic snapshotting and restoration for efficient test setuplink function enables library linking for complex contract deploymentsCore testing infrastructure including MockProvider for local blockchain simulation, pre-funded test accounts, fixtures for test setup, and call history tracking.
class MockProvider extends providers.Web3Provider {
constructor(options?: MockProviderOptions);
getWallets(): Wallet[];
createEmptyWallet(): Wallet;
}
function loadFixture<T>(fixture: Fixture<T>): Promise<T>;
const defaultAccounts: Array<{balance: string; secretKey: string}>;Contract deployment functionality supporting both JSON artifacts and TypeChain factories with full type safety and flexible deployment options.
function deployContract<T extends ContractFactoryOrJSON>(
wallet: Wallet | Signer,
factoryOrContractJson: T,
args?: DeployArgumentsOf<T>,
overrideOptions?: providers.TransactionRequest
): Promise<ContractTypeOf<T>>;
type ContractJSON = StandardContractJSON | SimpleContractJSON;Advanced mocking system for creating configurable smart contract mocks that can return specific values, revert with custom reasons, or track call history for testing contract interactions.
function deployMockContract<T extends BaseContract = BaseContract>(
signer: Signer,
abi: ABI,
options?: DeployOptions
): Promise<MockContract<T>>;
interface MockContract<T extends BaseContract = BaseContract> extends Contract {
mock: {
[key in ((keyof T['functions'] | 'receive'))]: StubInterface;
};
}Comprehensive set of 17+ custom chai matchers specifically designed for smart contract testing, including transaction revert checking, event emission testing, balance change assertions, and contract interaction verification.
function solidity(chai: Chai.ChaiStatic, utils: Chai.ChaiUtils): void;
// Transaction matchers
.reverted: AsyncAssertion;
.revertedWith(reason: string | RegExp): RevertedWithAssertion;
.emit(contract: Contract, eventName: string): EmitAssertion;
// Balance matchers
.changeEtherBalance(account: Account, balance: BigNumberish): AsyncAssertion;
.changeTokenBalance(token: Contract, account: Account, balance: BigNumberish): AsyncAssertion;Comprehensive Solidity compilation system including project compilation, library linking, TypeChain integration, and advanced configuration management.
function compileProject(configPath?: string): Promise<void>;
function compileAndSave(input: InputConfig): Promise<void>;
function compile(input: InputConfig): Promise<any>;
function link(contract: LinkableContract, libraryName: string, libraryAddress: string): void;
function generateTypes(config: Config): Promise<void>;ENS (Ethereum Name Service) testing utilities providing comprehensive domain management and resolution testing infrastructure for smart contract development.
function deployENS(signer: Signer): Promise<ENS>;
function createResolver(signer: Signer, ens: Contract): Promise<Contract>;
function createReverseRegistrar(signer: Signer, ens: Contract, resolver: Contract): Promise<Contract>;
class ENS {
createTopLevelDomain(domain: string): Promise<void>;
createDomain(domain: string, options?: DomainRegistrationOptions): Promise<void>;
setAddress(domain: string, address: string, options?: DomainRegistrationOptions): Promise<void>;
setAddressWithReverse(domain: string, signer: Signer, options?: DomainRegistrationOptions): Promise<void>;
}Specialized provider implementation for Optimism Layer 2 blockchain testing with L1 fee calculation and optimized wallet management.
class OptimismProvider extends providers.JsonRpcProvider implements TestProvider {
getWallets(): Wallet[];
getL1Fee(transactionHash: string): Promise<BigNumber>;
}