Migrating from Truffle

Test Environment’s scope is much smaller than Truffle’s: it is only a testing library, while Truffle is an all-out development framework.

Despite this, it is still quite simple to migrate from a truffle test-based suite. Doing the whole process on the OpenZeppelin Contracts repository took less than thirty minutes!

We will only be replacing truffle test in this guide. You can continue using other Truffle commands such as truffle compile, truffle migrate or truffle console.

Installing Dependencies

Since we’re not running truffle test any more, we’ll need a test runner to take care of this.

Under the hood, Truffle runs tests with a lightly modified Mocha (bundled with Chai for assertions). Because of this, these two make best choice for a simple migration:

$ npm install --save-dev @openzeppelin/test-environment mocha chai
If you want to use a test runner other than Mocha, it is still recommended to first migrate out of Truffle using Mocha, and then switch to your test runner of choice.

Don’t forget to make Mocha the entry point of your test suite once you install it:

// package.json

 "scripts": {
-  "test": "truffle test"
+  "test": "mocha --exit --recursive"
 }
Mocha’s --exit flag is required when using Truffle contracts. Otherwise, the test suite will not exit. Learn more.

Switching to Test Environment

Some bits of your test files will need to be modified during the migration. The changes are only a few, but important:

  1. Add require('@openzeppelin/test-environment') and export relevant objects, such as accounts, contract and web3.

  2. Add require('chai') and set it up (Truffle does this automagically).

  3. Replace all instances of artifacts.require with contract.fromArtifact

  4. Replace all instances of Truffle’s contract function with a regular Mocha describe. You can still access the accounts array in accounts.

That’s it! Let’s see what a full migration might look like:

+const { accounts, contract, web3 } = require('@openzeppelin/test-environment');

 // Setup Chai for 'expect' or 'should' style assertions (you only need one)
+const { expect } = require('chai');
+require('chai').should();

-const ERC20 = artifacts.require('ERC20');
+const ERC20 = contract.fromArtifact('ERC20');

-contract('ERC20', function (accounts) {
+describe('ERC20', function () {
   ...
 }

Running Tests

With all changes in place, you are are now ready to run your tests:

$ npm test

  ERC20
    total supply
      ✓ returns the total amount of tokens
    balanceOf
      when the requested account has no tokens
        ✓ returns zero
      when the requested account has some tokens
        ✓ returns the total amount of tokens
    transfer
      when the recipient is not the zero address
  ...

You will notice your tests start executing almost immediately: the OpenZeppelin Contracts have over 150 contracts and 2000 individual tests, and testing setup time is under 2 seconds.

Enjoy lightning fast testing!

Unlike Truffle, Test Environment will not compile your contracts. You can do this manually with truffle compile.

Learn More

← Getting Started
Choosing a Test Runner →