@gnosis.pm/mock-contract

中文文档
4.0.0发布于 2020/08/04ISCCommonJS零依赖近 30 天下载 4.7万

Simple Solidity contract to mock dependent contracts in truffle tests.

原始使用文档
文档目录7 节
  1. Mocking General Interactions
  2. Mocking Methods Individually
  3. Mocking Methods & Arguments
  4. Simulating Failure
  5. Inspect Invocations
  6. Resetting mock
  7. Complex return types

Build Status

MockContract

Simple Solidity contract to mock dependencies in truffle tests. It enables you to

  • Make dependent contracts return predefined values for different methods and arguments
  • Simulate exceptions such as revert and outOfGas
  • Assert on how often a dependency is called

MockContract allows for all of that without having to write a separate test contract each time.

Usage in your project

Install module from npm

npm i -D @gnosis.pm/mock-contract

Enable compilation of MockContract

  • Add a new Imports.sol to the contracts folder the project
  • Copy the following code into Imports.sol:
pragma solidity ^0.6.0;

// We import the contract so truffle compiles it, and we have the ABI 
// available when working from truffle console.
import "@gnosis.pm/mock-contract/contracts/MockContract.sol";
  • Use in javascript unit test:
const MockContract = artifacts.require("./MockContract.sol")

// Instantiate mock and make it return true for any invocation
const mock = await MockContract.new()
await mock.givenAnyReturnBool(true)

// instantiate "object under test" with mocked contract.
const contractToTest = await ComplextContract.new(mock.address)

Step by Step Example

Let's assume we want to test the following smart contract, which implements a simple bidding procedure:

pragma solidity ^0.6.0;
import "./Token.sol";

/**
 * Contract that stores the highest bidder while securing payment from a given ERC20 Token.
 * Upon each bid the cost of bidding is incremented.
 */
contract SimpleAuction {
  address public captor; // Address of the highest bidder
  
  Token private token;
  uint256 private cost;

  constructor(Token _token) public {
    token = _token;
  }

  function bid() public {
    if (token.transferFrom(msg.sender, this, cost + 1)) {
      require(token.transfer(captor, cost), "Refund failed");
      captor = msg.sender;
      cost += 1;
    }
  }
}

If we were to write unit tests for this class, we would have to provide an implementation of an ERC20 token contract. There are commonly two ways to deal with that:

  1. Use the real ERC20 token contract and configure it in a way that it will work for the test (e.g. call token.approve before bidding)
  2. Implement a fake Token contract that instead of real logic contains dummy implementations (e.g. return true for everything)

The problem with 1) is that the logic required to make our dependency behave in the intended way can be very complex and incurs additional maintenance work. It also doesn't isolate our tests - instead of only testing the unit under test it is testing the integration of multiple components.

Solution 2) requires writing a Fake contract for each dependency. This takes time and pollutes the repository and migration files with a lot of non-production code.

Mocking General Interactions

MockContract can act as a generic fake object for any type of contract. We can tell our mock what it should return upon certain invocations. For the example above, assume we want to write a test case where ERC20 transfers work just fine:

const MockContract = artifacts.require("./MockContract.sol")
const SimpleAuction = artifacts.require("./SimpleAuction.sol")
...
it('updates the captor', async () => {
  const mock = await MockContract.new()
  const auction = await SimpleAuction.new(mock.address)

  const trueEncoded = web3.eth.abi.encodeParameter("bool", true)
  await mock.givenAnyReturnBool(trueEncoded)
  await auction.bid({from: accounts[0]})
  
  assert.equal(accounts[0], await auction.captor.call())
})

In particular await mock.givenAnyReturnBool(true) will make it so that mock returns true on any method invocation.

A plain mock without any expectations will return nullish values by default (e.g. false for bool, 0 for uint, etc).

There are convenience methods for other types such as givenAnyReturnAddress or givenAnyReturnUint. The full mock interface can be found here.

Mocking Methods Individually

Now let's assume we want to test that the bid gets reverted if token.transfer succeeds but token.transferFrom fails:

const Token = artifacts.require("./Token.sol")
...
it('should fail if we fail to refund', async () => {
  const mock = await MockContract.new()
  const auction = await SimpleAuction.new(mock.address)
  const token = await Token.new();

  const transferFrom = token.contract.methods.transferFrom(0, 0, 0).encodeABI() // arguments don't matter
  const transfer = token.contract.methods.transfer(0,0).encodeABI() // arguments don't matter

  await mock.givenMethodReturnBool(transferFrom, true)
  await mock.givenMethodReturnBool(transfer, false)

  try {
    await auction.bid({from: accounts[1]})
    assert.fail("Should have reverted")
  } catch (e) {}
})

Different methods have different ABI encodings. mock.givenMethodReturnBool(bytes, boolean) takes the ABI encoded methodId as a first parameter and will only replace behavior for this method. There are two ways to construct the methodId. We recommend using the encodeABI call on the original contract's ABI:

// Arguments do not matter, mock will only extract methodId
const transferFrom = token.contract.transferFrom(0, 0, 0).encodeABI()

We could also create it manually using e.g.:

const transferFrom = web3.sha3("transferFrom(address,address,uint256)").slice(0,10) // first 4 bytes

However, the latter approach is not type-safe and can lead to unexpected test behavior if the ABI on the original contract changes. The first approach would give a much more descriptive compilation error in that case.

Again there are convenience functions for other return types (e.g. givenMethoReturnUint).

Mocked methods will take priority over mocks using any.

Mocking Methods & Arguments

We can also specify different behaviors for when the same method is called with different arguments:

it('Keeps the old bidder if the new bidder fails to transfer', async () => {
  ...
  const transferFromA = token.contract.methods.transferFrom(accounts[0], auction.address, 1).encodeABI()
  const transferFromB = token.contract.methods.transferFrom(accounts[1], auction.address, 2).encodeABI()

  await mock.givenCalldataReturnBool(transferFromA, true)
  await mock.givenCalldataReturnBool(transferFromB, false)

  await auction.bid({from: accounts[0]})
  await auction.bid({from: accounts[1]})
      
  assert.equal(accounts[0], await auction.captor.call())
})

This time we need to provide the full calldata. We can easily use the original contract's ABI encodeABIcall to generate it. Again, convenience functions for other return types exist (e.g. givenMethoReturnUint).

Mocked calls with exact calldata will takes priority over method mocks and any mocks.

Simulating Failure

We can also simulate EVM exceptions using MockContract. All methods are available for any, method and calldata specific calls:

// Revert upon any invocation on mock without a specific message
await mock.givenAnyRevert()

// Revert upon any invocation of `methodId` with the specific message
await mock.givenMethodRevertWithMessage(methodId, "Some specific message")

// Run out of gas, if mock is called with `calldata`
await mock.givenCalldataRunOutOfGas(calldata)

Inspect Invocations

It can sometime be useful to see how often a dependency has been called during a test-case. E.g. we might want to assert that transfer is not called if transferFrom failed in the first place:

it('only does the second transfer if the first transfer succeed', async () => {
  ...
  await mock.givenAnyReturnBool(false)
  await auction.bid()

  const transfer = token.contract.methods.transfer(0,0).encodeABI()
  
  const invocationCount = await mock.invocationCountForMethod.call(transfer)
  assert.equal(0, invocationCount)
})

We can inspect the total invocation of mock for all methods combined using await invocationCount.call() and for individual arguments using await invocationCountForCalldata.call(calldata).

Resetting mock

We can override existing behavior throughout the lifetime of the test:

await mock.givenAnyReturnBool(true) // will return true from now on
await auction.bid()
await mock.givenAnyReturnBool(false) // will return false from now on
await auction.bid()

Note that previously specified method and calldata based behavior will be unaffected by overriding any mock behavior.

To completely reset all behavior and clear invocation counts, we can call:

await mock.reset()

Complex return types

If the methods for returning the most commonly used types are not enough, we can manually ABI encode our responses with arbitrary solidity types:

const hello_world = web3.eth.abi.encodeParameter("string", 'Hello World!')
await mock.givenAnyReturn(hello_world);

This is a work in progress and feedback is highly appreciated. Please open an issue on GitHub and/or submit a pull request.

版本与发布记录

@gnosis.pm/mock-contract 共发布 13 个版本,首次发布于 2018/09/04;过去 12 个月发布了 0 个版本。

版本发布日期距今
4.0.0latest2020/08/046 年前
3.0.82019/11/226 年前
3.0.72019/02/017 年前
3.0.62019/01/037 年前
3.0.52018/12/207 年前
3.0.42018/12/067 年前

关于 @gnosis.pm/mock-contract 的常见问题

@gnosis.pm/mock-contract 是什么?

Simple Solidity contract to mock dependent contracts in truffle tests.

如何安装 @gnosis.pm/mock-contract?

在项目目录运行 npm install @gnosis.pm/mock-contract,或使用 pnpm add / yarn add / bun add。

@gnosis.pm/mock-contract 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/gnosis.pm__mock-contract 是否存在。

@gnosis.pm/mock-contract 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@gnosis.pm/mock-contract 可以商用吗?

@gnosis.pm/mock-contract 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gnosis.pm/mock-contract 的下载量有多少?

根据 npm 官方下载统计,@gnosis.pm/mock-contract 在 2026/10/17 – 2026/11/15 这 30 天内被下载 46,662 次,日均约 1,555 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gnosis.pm/mock-contract 还在维护吗?

最新版本 4.0.0 发布于 2020/08/04(6 年前);至今共发布 13 个版本,其中过去 12 个月发布了 0 个;首次发布于 2018/09/04。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。