Version: Next

Testing LIGO

Testing LIGO code#

The LIGO command-line interpreter provides commands to directly test your LIGO code. The three main commands we currently support are:

ligo run test
ligo run interpret
ligo run dry-run

We will show how to use the first two, while an example on how to use the third one was already explained here.

Testing with `ligo run test`#

The command ligo run test can be used to test a contract using LIGO.

⚠️ Please keep in mind that this command is still BETA, and that there are features that are work in progress and are subject to change. No real test procedure should rely on this command alone.

When running the ligo run test command, LIGO code has access to an additional Test module. This module provides ways of originating contracts and executing transactions, as well as additional helper functions that allow to control different parameters of the Tezos testing library.

Note: The LIGO interpreter uses the same library that Tezos internally uses for testing.

The function Test.originate allows to deploy a contract in the testing environment. It takes a contract, which is represented as a function of type 'parameter * 'storage -> operation list * 'storage, an initial storage of type 'storage, and an initial balance for the contract being deployed. This function deploys the contract, and returns the type ('parameter, 'storage) typed_address, the compiled program in Michelson of type michelson_program, and the size of the program of type int.

The storage of a deployed contract can be queried using the Test.get_storage function, that given a typed address ('parameter, 'storage) typed_address, returns the 'storage value.

As a concrete example, suppose we have the following contract:

// This is testnew.jsligo
type storage = int;

type parameter =
  ["Increment", int]
| ["Decrement", int]
| ["Reset"];

type @return = [list<operation>, storage];

// Two entrypoints
const add = ([store, delta]: [storage, int]): storage => store + delta;
const sub = ([store, delta]: [storage, int]): storage => store - delta;

/* Main access point that dispatches to the entrypoints according to
   the smart contract parameter. */
const main = ([action, store]: [parameter, storage]) : @return => {
  return [
    list([]) as list<operation>,    // No operations
    match(action, {
      Increment:(n: int) => add ([store, n]),
      Decrement:(n: int) => sub ([store, n]),
      Reset: ()          => 0})
  ]
};

We can deploy it and query the storage right after, to check that the storage is in fact the one which we started with:

// This continues testnew.jsligo

let _test = () : bool => {
  let initial_storage = 42 as int;
  let [taddr, _, _] = Test.originate(main, initial_storage, 0 as tez);
  return (Test.get_storage(taddr) == initial_storage);
};

let test = _test();

The test sub-command will evaluate all top-level definitions and print any entries that begin with the prefix test as well as the value that these definitions evaluate to. If any of the definitions are found to have failed, a message will be issued with the line number where the problem occurred.

ligo run test gitlab-pages/docs/advanced/src/testnew.jsligo
// Outputs:
// Everything at the top-level was executed.
// - test exited with value true.

The function Test.transfer_to_contract allows to bake a transaction. It takes a target account of type 'parameter contract, the parameter of type 'parameter and an amount of type tez. This function performs the transaction, and returns a test_exec_result which can be matched on to know whether the transaction was successful or not. In case of success you will get access to the gas consumed by the execution of the contract and in case of failure you will get access to a test_exec_error describing the error.
There is an alternative version, called Test.transfer_to_contract_exn which performs the transaction and will only return the gas consumption, failing in case that there was an error.

We can extend the previous example by executing a transaction that increments the storage after deployment, we also print the gas consumption:

// This continues testnew.jsligo

let _test2 = () : bool => {
  let initial_storage = 42 as int;
  let [taddr, _, _] = Test.originate(main, initial_storage, 0 as tez);
  let contr = Test.to_contract(taddr);
  let gas_cons = Test.transfer_to_contract_exn(contr, (Increment (1)), 1 as mutez);
  let _ = Test.log(["gas consumption", gas_cons]);
  return (Test.get_storage(taddr) == initial_storage + 1);
}

let test2 = _test2();

The environment assumes a source for the operations which can be set using the function Test.set_source : address -> unit.

Unit testing a function#

Consider a map binding addresses to amounts and a function removing all entries in that map having an amount less to a given threshold.

// This is remove-balance.jsligo

type balances = map <address, tez>

const balances_under = (b : balances, threshold:tez) : balances => {
  let f = (acc : balances, kv :[address , tez] ) : balances => {
    let [k,v] = kv ;
    if (v < threshold) { return Map.remove (k,acc) } else {return acc}
  };
  return Map.fold (f,b,b);
}

Let us imagine that we want to test this function against a range of thresholds with the LIGO test framework.

First, let's include the file under test and reset the state with 5 bootstrap accounts (we are going to use the bootstrap addresses later)

#include "./gitlab-pages/docs/advanced/src/remove-balance.jsligo"
let x = Test.reset_state (5 as nat, list([]) as list <tez>);

Now build the balances map that will serve as the input of our test.

let balances : balances =
  Map.literal(list([[Test.nth_bootstrap_account(1), 10 as tez],
                    [Test.nth_bootstrap_account(2), 100 as tez],
                    [Test.nth_bootstrap_account(3), 1000 as tez]]));

Our simple test loop will call balances_under with the compiled map defined above, get the size of the resulting map and compare it to an expected value with Test.michelson_equal.

The call to balance_under and the computation of the size of the resulting map is achieved through the primitive Test.run. This primitive runs a function on an input, translating both (function and input) to Michelson before running on the Michelson interpreter. More concretely Test.run f v performs the following:

Compiles the function argument f to Michelson f_mich
Compiles the value argument v (which was already evaluated) to Michelson v_mich
Runs the Michelson interpreter on the code f_mich with the initial stack [ v_mich ]

The function that is being compiled is called tester.

We also print the actual and expected sizes for good measure.

let test =
  List.iter
    ( ([threshold , expected_size] : [tez , nat]) : unit => {
      let tester = ([balances, threshold] : [balances, tez]) : nat => Map.size (balances_under (balances, threshold));
      let size = Test.run(tester, [balances, threshold]);
      let expected_size_ = Test.eval(expected_size) ;
      let unit_ = Test.log (["expected", expected_size]) ;
      let unit__ = Test.log (["actual",size]) ;
      return (assert (Test.michelson_equal (size,expected_size_)))
    },
    list ([ [15 as tez,2 as nat] , [130 as tez,1 as nat] , [1200 as tez,0 as nat]]) );

You can now execute the test:

> ligo run test gitlab-pages/docs/advanced/src/unit-remove-balance-mixed.jsligo
// Outputs:
// ("expected" , 2)
// ("actual" , 2)
// ("expected" , 1)
// ("actual" , 1)
// ("expected" , 0)
// ("actual" , 0)
// Everything at the top-level was executed.
// - test exited with value ().

Testing with `ligo run interpret`#

The command ligo run interpret allows to interpret an expression in a context initialised by a source file. The interpretation is done using Michelson's interpreter.

We can see how it works on an example. Suppose we want to test the following contract.

// This is testme.jsligo

type storage = int;

type parameter =
  ["Increment", int]
| ["Decrement", int]
| ["Reset"];

type @return = [list<operation>, storage];

// Two entrypoints

let add = ([store, delta]: [storage, int]): storage => store + delta;
let sub = ([store, delta]: [storage, int]): storage => store - delta;

/* Main access point that dispatches to the entrypoints according to
   the smart contract parameter. */

let main = ([action, store]: [parameter, storage]) : @return => {
  return [
    list([]) as list<operation>,    // No operations
    match(action, {
      Increment:(n: int) => add ([store, n]),
      Decrement:(n: int) => sub ([store, n]),
      Reset: ()          => 0})
  ]
};

This contract keeps an integer as storage, and has three entry-points: one for incrementing the storage, one for decrementing the storage, and one for resetting the storage to 0.

As a simple property, we check whether starting with a storage of 10, if we execute the entry-point for incrementing 32, then we get a resulting storage of 42. For checking it, we can interpret the main function:

ligo run interpret "main (Increment (32), 10)" --init-file testme.jsligo
// Outputs:
// ( LIST_EMPTY() , 42 )

With the argument --init-file we pass the contract we want to test, and the sub-command requires also the expression to evaluate in that context, in this case, a call to our contract (main) with parameter Increment (32) and storage 10. As a result, we can check that the resulting storage is 42 (the second component of the pair), and there are no further operations to execute (the first component).

We can tune certain parameters of the execution by passing them as arguments:

--amount=AMOUNT (absent=0)
    AMOUNT is the amount the Michelson interpreter will use for the
    transaction.
--balance=BALANCE (absent=0)
    BALANCE is the balance the Michelson interpreter will use for the
    contract balance.
--now=NOW
    NOW is the NOW value the Michelson interpreter will use
    (e.g. '2000-01-01T10:10:10Z')
--sender=SENDER
    SENDER is the sender the Michelson interpreter transaction will use.
--source=SOURCE
    SOURCE is the source the Michelson interpreter transaction will use.

Testing LIGO code#

Testing with ligo run test#

Unit testing a function#

Testing with ligo run interpret#

Testing with `ligo run test`#

Testing with `ligo run interpret`#