Skip to content
This repository has been archived by the owner on Jun 11, 2019. It is now read-only.

Files

Latest commit

 

History

History
369 lines (263 loc) · 7.83 KB

test.md

File metadata and controls

369 lines (263 loc) · 7.83 KB

Tests

Dapple provides a VM test harness so you can write your tests directly in Solidity. This is less flexible and sometimes more verbose than writing tests in the harness language, but the lack of a context switch makes writing unit tests more pleasant for the developer.

Example

Suppose you want to test this contract:

contract MyRegistry {
    address public _creator;
    mapping(bytes32=>bytes32) _values;
    event Set(bytes32 indexed key, bytes32 value);
    function MyRegistry() {
        _creator = msg.sender;
    }
    function set(bytes32 key, bytes32 value) {
        if( msg.sender != _creator ) {
            throw;
        }
        _values[key] = value;
        Set(key, value);
    }
    function get(bytes32 key) constant returns (bytes32 value) {
        return _values[key];
    }
}

A dapple test might look like this:

import 'dapple/test.sol'; // virtual "dapple" package imported when `dapple test` is run
import 'myregistry.sol';

// Deriving from `Test` marks the contract as a test and gives you access to various test helpers.
contract MyRegistryTest is Test {
    MyRegistry reg;
    Tester proxy_tester;
    // The function called "setUp" with no arguments is
    // called on a fresh instance of this contract before
    // each test. TODO: Document when to put setup logic in
    // setUp vs subclass constructor when writing Test subclasses
    function setUp() {
        reg = new MyRegistry();
        proxy_tester = new Tester();
        proxy_tester._target(reg);
    }
    function testCreatorIsCreator() {
        assertEq( address(this), reg._creator() );
    }
    function testFailNonCreatorSet() {
        MyRegistry(proxy_tester).set("no", "stop");
    }
    event Set(bytes32 indexed key, bytes32 value);
    function testSetEvent() {
        expectEventsExact(reg);
        Set("hello", "hi");
        reg.set("hello", "hi");
    }
}

Test Exeptions

This test feature captures thrown Errors (VM exceptions) of a transaction. All test functions which are starting with testThrow, testFail or testError are expected to crash: a throw; is expected somewhere in the scenario.

Example

Suppose the following contract:

contract Contract {
  [...]

  function crash() {
    throw;
  }

  function passing() {
    // nothing
  }
}

passing

The following shows a passing test, because an expected throw actually happens:

contract MyTest is Test {
  function testThrow() {
    Contract target = new Contract();
    target.crash();
  }
}

failing

The following test fails, because the function name has a wrong prefix:

contract MyTest is Test {
  function testCrash() {
    Contract target = new Contract();
    target.crash();
  }
}

The following test fails, because no expected throw happens:

contract MyTest is Test {
  function testError() {
    Contract target = new Contract();
    target.passing();
  }
}

Test Events

This test feature tests the exact emitted event sequence produced by a transaction.

Example

A contract which implements a set of Events:

contract EventDefinitions {
    event info(bytes data);
    event warn(bytes data);
}

contract Contract is EventDefinitions {
[...]
  function fire() {
    info("ok");
    warn("warning");
  }
}

In order to assert that in a scenario a correct sequence of events is emitted, one can bind the events of contract instance with expectEventsExact( <target> ). After a binding, the test function has to emit the expected events in the same order in which they are expect in the bound instance. This asserts the correct event types, correct inputs for a type and the correct order of emits. Also, expected events that are not emitted and unexpected events result in a test failure.

The easiest way to use this is to follow the pattern of defining events in their own container type like EventDefinitions, then have both the implementation and the tester derive from it.

passing example

The following shows a passing test:

contract MyTest is Test, EventDefinitions {

  [...]

  function testEvents () {
    Contract target = new Contract();
    expectEventsExact( target );
    info("ok");
    warn("warning");
    target.fire();
  }

}
failing examples

The following test will fail because of the wrong order of the events:

contract MyTest is Test, EventDefinitions {

  [...]

  function testEvents () {
    Contract target = new Contract();
    expectEventsExact( target );
    warn("warning");
    info("ok");
    target.fire();
  }

}

The following test will fail because of the wrong type of the events:

contract MyTest is Test, EventDefinitions {

  [...]

  function testEvents () {
    Contract target = new Contract();
    expectEventsExact( target );
    info("ok");
    info("warning");
    target.fire();
  }

}

The following test will fail because of the wrong content of the events:

contract MyTest is Test, EventDefinitions {

  [...]

  function testEvents () {
    Contract target = new Contract();
    expectEventsExact( target );
    info("ok");
    warn("error");
    target.fire();
  }

}

The following test will fail because an unexpected event is emited:

contract MyTest is Test, EventDefinitions {

  [...]

  function testEvents () {
    Contract target = new Contract();
    expectEventsExact( target );
    info("ok");
    target.fire();
  }

}

The following test will fail because an expected event is not emited:

contract MyTest is Test, EventDefinitions {

  [...]

  function testEvents () {
    Contract target = new Contract();
    expectEventsExact( target );
    info("ok");
    warn("warn");
    info("success");
    target.fire();
  }

}

Reference

##Modifiers

#####tests(bytes32 what)

This modifier allows you to specify the function you intend to test as a string next to your testcase name.

Example:

contract MyTest is Test {
  
  [...]
  
  function testUnsetNullValue() tests("unset") {
    DSNullableMap map = new DSNullableMap();
    assertTrue(map.unset("test"));
  }

}

#####logs_gas( )

This modifier will cause the consumed gas to be logged as an event when you run your test case.

##Assertions Functions

Any bytes32 error parameter listed below will be logged to stdout if the assertion fails.

#####assertTrue(bool what)

#####assertTrue(bool what, bytes32 error)

#####assertFalse(bool what)

#####assertFalse(bool what, bytes32 error)

#####assertEq(bool a, bool b)

#####assertEq(bool a, bool b, bytes32 err)

#####assertEq(uint a, uint b)

#####assertEq(uint a, uint b, bytes32 err)

#####assertEq(int a, int b)

#####assertEq(int a, int b, bytes32 err)

#####assertEq(address a, address b)

#####assertEq(address a, address b, bytes32 err)

#####assertEq0(bytes a, bytes b)

#####assertEq0(bytes a, bytes b, bytes32 err)

#####assertEq<N>(bytes<N> a, bytes<N> b)

<N> in this case can be any number between 1 and 32. For example:

assertEq8(bytes8 a, bytes8 b)

#####assertEq<N>(bytes<N> a, bytes<N> b, bytes32 err)

#####assertEq(bytes memory _a, bytes memory _b)

#####assertEq(string memory a, string memory b)

##Logging events

In addition to Dapple's logging framework, test contracts have access to events that are defined for the purposes of logging.

#####log_bool(bool val)

#####log_named_bool(bytes32 key, bool val)

#####log_uint(uint val)

#####log_named_uint(bytes32 key, uint val)

#####log_int(int val)

#####log_named_int(bytes32 key, int val)

#####log_address(address val)

#####log_named_address(bytes32 key, address val)

#####log_bytes(bytes val)

#####log_named_bytes(bytes32 key, bytes val)

#####log_bytes<N>(bytes<N> val)

<N> in this case can be any number between 1 and 32. For example:

log_bytes8(bytes8 val)

#####log_named_bytes<N>(bytes32 key, bytes<N> val)

#####log_named_string(string key, string val)