or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

chai-matchers.mdcompiler-utilities.mdcontract-deployment.mdens-utilities.mdindex.mdmock-contracts.mdoptimism-provider.mdprovider-testing.md
tile.json

tessl/npm-ethereum-waffle

Advanced framework for testing smart contracts with enhanced chai matchers, mock contracts, and testing utilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ethereum-waffle@4.0.x

To install, run

npx @tessl/cli install tessl/npm-ethereum-waffle@4.0.0

index.mddocs/

Ethereum Waffle

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.

Package Information

  • Package Name: ethereum-waffle
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install ethereum-waffle

Core Imports

import { deployContract, MockProvider, solidity } from "ethereum-waffle";

For CommonJS:

const { deployContract, MockProvider, solidity } = require("ethereum-waffle");

Basic Usage

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);

Architecture

Ethereum Waffle is built around several key components:

  • Testing Provider: MockProvider extends Web3Provider with call history tracking, pre-funded accounts, and ENS support
  • Contract Utilities: deployContract supports both JSON artifacts and TypeChain factories with type safety
  • Mock Contracts: deployMockContract creates fully configurable mock contracts for testing interactions
  • Chai Integration: solidity plugin adds 17+ custom matchers for contract-specific assertions
  • Test Fixtures: loadFixture provides automatic snapshotting and restoration for efficient test setup
  • Compiler Integration: link function enables library linking for complex contract deployments

Capabilities

Provider & Testing Utilities

Core 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}>;

Provider & Testing Utilities

Contract Deployment

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;

Contract Deployment

Mock Contracts

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;
  };
}

Mock Contracts

Chai Matchers

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;

Chai Matchers

Compiler Utilities

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>;

Compiler Utilities

ENS Utilities

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>;
}

ENS Utilities

Optimism Provider

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>;
}

Optimism Provider