# ethereum-waffle

> Sweeter, faster and simpler than truffle.

Latest version **4.0.10** (published 2023-02-15) · MIT license · 0 weekly downloads

## Install

```sh
npm install ethereum-waffle
pnpm add ethereum-waffle
yarn add ethereum-waffle
bun add ethereum-waffle
```

Provides the command `waffle`.

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 4.0.10 |
| Published | 2023-02-15 |
| First published | 2018-08-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=10.0 |
| Dependencies | 6 |
| Unpacked size | 192.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 959 |
| Author | Marek Kirejczyk |
| Maintainers | ethworks |
| Keywords | ethereum, smart-contracts, solidity, compiler, testing, javascript, typescript, library |

## Links

- npm: https://www.npmjs.com/package/ethereum-waffle
- Repository: https://github.com/EthWorks/Waffle
- Issues: https://github.com/EthWorks/Waffle/issues
- npm.io page: https://npm.io/package/ethereum-waffle

## Dependencies (6)

- [solc](https://npm.io/package/solc.md) 0.8.15
- [typechain](https://npm.io/package/typechain.md) ^8.0.0
- [@ethereum-waffle/chai](https://npm.io/package/@ethereum-waffle/chai.md) 4.0.10
- [@ethereum-waffle/compiler](https://npm.io/package/@ethereum-waffle/compiler.md) 4.0.3
- [@ethereum-waffle/provider](https://npm.io/package/@ethereum-waffle/provider.md) 4.0.5
- [@ethereum-waffle/mock-contract](https://npm.io/package/@ethereum-waffle/mock-contract.md) 4.0.4

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 4.0.10 (latest) — 2023-02-15
- 4.0.10-dev.238c11c (dev) — 2023-10-12
- 4.0.7 (alpha) — 2022-09-16
- 3.0.0-beta.3 (beta) — 2020-06-12
- 4.0.10-dev.efd5f2a — 2023-10-12
- 4.0.10-dev.0915e72 — 2023-02-15
- 4.0.10-dev.4740ec6 — 2023-02-06
- 4.0.9-dev.a1d89d0 — 2023-01-27
- 4.0.9 — 2023-01-27
- 4.0.9-dev.f8ca718 — 2023-01-26
- 4.0.8-dev.13d1af0 — 2023-01-26
- 4.0.8 — 2023-01-26
- 4.0.8-dev.0bc9af4 — 2023-01-26
- 4.0.8-dev.166b72c — 2023-01-26
- 4.0.8-dev.a50814e — 2023-01-24
- … 223 more at https://npm.io/package/ethereum-waffle/versions

## README

![CI](https://github.com/EthWorks/Waffle/workflows/CI/badge.svg)
[![](https://img.shields.io/npm/v/ethereum-waffle.svg)](https://www.npmjs.com/package/ethereum-waffle)
[![Discord](https://badgen.net/badge/icon/discord?icon=discord&label)](https://discord.gg/ppFxC3E44X)

![Ethereum Waffle](https://raw.githubusercontent.com/EthWorks/Waffle/master/docs/source/logo.png)

The most advanced framework for testing smart contracts.

Sweeter, simpler and faster.

## Links
* Website - https://getwaffle.io/
* Documentation - https://ethereum-waffle.readthedocs.io/

## Philosophy
* __Simpler__: Minimalistic, few dependencies.
* __Sweeter__: Nice syntax, easy to extend.
* __Faster__: Strong focus on the speed of test execution.

## Features:
* Sweet set of chai matchers, e.g.:
  * `expect(...).to.be.revertedWith('Error message')`
  * `expect(...).to.emit(contract, 'EventName').withArgs(...)`)
* Importing contracts from npm modules working out of the box, e.g.:
  * `import "openzeppelin-solidity/contracts/token/ERC20/ERC20.sol";`
* Fixtures that help write fast and maintainable test suites, e.g.:
  * `const {token} = await loadFixture(standardTokenWithBalance);`
* Customizable compilation options with native solc, dockerized solc and any version of solc-js loaded remotely at compiled time
* Mocking smart contracts, e.g.:
  * `const mockToken = await deployMockContract(wallet, IERC20.abi);`
* Support for promise-based configuration, e.g.:
  * use native solc binary for fast compilation in CI environment
  * use solc-js based on contract versions detected (async)
* Support for TypeScript
* Type-safe contract deployment and interactions with TypeChain
* [Documentation](https://ethereum-waffle.readthedocs.io/en/latest/)

## Documentation
Documentation is available [here](https://ethereum-waffle.readthedocs.io/en/latest/).

## Installation:

To get started install `ethereum-waffle` with yarn:
```
yarn add --dev ethereum-waffle
```

Or if you prefer using npm:
```
npm install --save-dev ethereum-waffle
```

## Step by step guide

### Add external dependency:
To add an external library install it using npm:

```sh
npm install @openzeppelin/contracts -D
```

or with yarn:

```sh
yarn add @openzeppelin/contracts -D
```

### Note

Find this example in `examples/basic` and use it.

### Example contract
Below is an example contract written in Solidity. Place it in `contracts/BasicToken.sol` file of your project:

```solidity
pragma solidity ^0.6.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") public {
        _mint(msg.sender, initialBalance);
    }
}

```

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

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

use(solidity);

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)).to.be.reverted;
  });

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

  it('Calls totalSupply on BasicToken contract', async () => {
    await token.totalSupply();
    expect('totalSupply').to.be.calledOnContract(token);
  });

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

Note: You will also need to install the following dependencies to run the example above:

```sh
yarn add mocha -D
yarn add chai -D
```

Or with npm:

```
npm i chai -D
npm i mocha -D
```

### Compiling
To compile your smart contracts run:

```sh
npx waffle
```

To compile using a custom configuration file run:

```sh
npx waffle config.json
```

Example configuration file looks like this (all fields optional):
```json
{
  "sourceDirectory": "./custom_contracts",
  "outputDirectory": "./custom_build",
  "nodeModulesDirectory": "./custom_node_modules"
}
```

To enable generation of [typechain](https://github.com/ethereum-ts/TypeChain) artifacts:
```json
{
  "typechainEnabled": true
}
```

### Flattener
To flat your smart contracts run:

```sh
npx waffle flatten
```

In configuration file you can add optional field with path to flatten files:
```json
{
  "flattenOutputDirectory": "./custom_flatten"
}
```



### Running tests
To run the tests run the following command:

```sh
npx mocha
```

### Adding an npm script
For convenience, you can add the following to your `package.json`:
```
{
  ...,
  "scripts": {
    "test": "waffle && mocha"
  }
}
```

Now you can build and test your contracts with one command:

```sh
npm test
```

## Documentation
For detailed feature walkthrough checkout [documentation](https://ethereum-waffle.readthedocs.io/en/latest/).

## Contributing

Contributions are always welcome, no matter how large or small. Before contributing, please read the [code of conduct](https://github.com/EthWorks/Waffle/blob/master/CODE_OF_CONDUCT.md) and [contribution policy](https://github.com/EthWorks/Waffle/blob/master/CONTRIBUTION.md).

Before you issue pull request:

Make sure all tests and linters pass.
Make sure you have test coverage for any new features.

### Running tests
Note: To make end-to-end test pass, you need to:
* have Docker installed, up and running
* have Ethereum stable docker image pulled, if not run `docker pull ethereum/solc:stable`
* have native solidity 0.5.* installed

To run tests type:
```sh
yarn test
```

To run linter type:
```sh
yarn lint
```

### Building documentation

[Install Sphinx](https://www.sphinx-doc.org/en/master/usage/installation.html) to build documentation:

```sh
cd docs
make html
```

Before building documentation for the first time you may have to install required python packages:
```sh
pip3 install -r docs/requirements.txt
```

## Roadmap

See https://github.com/EthWorks/Waffle/issues/155

## License

Waffle is released under the [MIT License](https://opensource.org/licenses/MIT).

---
_Source: https://npm.io/package/ethereum-waffle · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._