Getting Started


To get started, install ethereum-waffle:

yarn add --dev ethereum-waffle
npm install --save-dev ethereum-waffle

Add external dependency

Add an external library by installing it with yarn or npm:

yarn add @openzeppelin/contracts@^4.6.0 -D
npm install @openzeppelin/contracts@^4.6.0 -D

Writing a contract

Below is an example contract written in Solidity. Place it in src/BasicToken.sol file of your project:

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

// Example class - a mock class using delivering from ERC20
contract BasicToken is ERC20 {
  constructor(uint256 initialBalance) ERC20("Basic", "BSC") {
      _mint(msg.sender, initialBalance);

Compiling the contract

Add the following entry in the package.json of your project :


Since Waffle 3.0.0 it recognises waffle.json as default configuration file. If your configuration file is called waffle.json, it’s possible to use just waffle to build contracts.

  "scripts": {
    "build": "waffle"
  "scripts": {
    "build": "waffle waffle.json"

In the waffle.json file of your project add the following entry:

  "compilerType": "solcjs",
  "compilerVersion": "0.8.13",
  "sourceDirectory": "./src",
  "outputDirectory": "./build"

Then run the following command:

yarn build
npm run build

You should see that Waffle compiled your contract and placed the resulting JSON output inside the build directory.

If you want to know more about how to configure Waffle, see Configuration.


To flat your smart contracts run:

npx waffle flatten

In configuration file you can add optional field with path to flatten files:

  "flattenOutputDirectory": "./custom_flatten"

Writing tests

After you have successfully authored a Smart Contract you can now think about testing it. Fortunately for you, Waffle is packed with tools that help with that.

Tests in waffle are written using Mocha alongside with Chai. You can use a different test environment, but Waffle matchers only work with chai.


yarn add --dev mocha chai
npm install --save-dev mocha chai


If you are using Typescript don’t forget to add ts-node, typescript and @types/mocha to your devDependencies. Also, make sure to add a tsconfig.json, and within it, set "esModuleInterop" and "resolveJsonModule" to true.

Below is an example test file for the contract above written with Waffle. Place it under test/BasicToken.test.ts file in your project directory:

import {expect, use} from 'chai';
import {Contract} from 'ethers';
import {deployContract, MockProvider, solidity} from 'ethereum-waffle';
import BasicToken from '../build/BasicToken.json';


describe('BasicToken', () => {
  const [wallet, walletTo] = new MockProvider().getWallets();
  let token: Contract;

  beforeEach(async () => {
    token = await deployContract(wallet, BasicToken, [1000]);

  it('Assigns initial balance', async () => {
    expect(await token.balanceOf(wallet.address)).to.equal(1000);

  it('Transfer adds amount to destination account', async () => {
    await token.transfer(walletTo.address, 7);
    expect(await token.balanceOf(walletTo.address)).to.equal(7);

  it('Transfer emits event', async () => {
    await expect(token.transfer(walletTo.address, 7))
      .to.emit(token, 'Transfer')
      .withArgs(wallet.address, walletTo.address, 7);

  it('Can not transfer above the amount', async () => {
    await expect(token.transfer(walletTo.address, 1007));

  it('Can not transfer from empty account', async () => {
    const tokenFromOtherWallet = token.connect(walletTo);
    await expect(tokenFromOtherWallet.transfer(wallet.address, 1));

  it('Calls totalSupply on BasicToken contract', async () => {
    await token.totalSupply();

  it('Calls balanceOf with sender address on BasicToken contract', async () => {
    await token.balanceOf(wallet.address);
    expect('balanceOf'), [wallet.address]);

Running tests

Update your package.json file to include:

  "scripts": {
    "build": "waffle",
    "test": "NODE_ENV=test mocha",

Next, add a .mocharc.json file in your root directory:

  "spec": "test/**/*.test.{js,ts}"
  "require": "ts-node/register/transpile-only",
  "spec": "test/**/*.test.{js,ts}"

And run:

yarn test
npm test

You should see the following output:

  ✓ Assigns initial balance (67ms)
  ✓ Transfer adds amount to destination account (524ms)
  ✓ Transfer emits event (309ms)
  ✓ Can not transfer above the amount (44ms)
  ✓ Can not transfer from empty account (78ms)
  ✓ Calls totalSupply on BasicToken contract (43ms)
  ✓ Calls balanceOf with sender address on BasicToken contract (45ms)

7 passing (5s)

If you want to know more about testing with Waffle, see Basic testing.