Test
Important: The
Testmodule is only available inside theligo run testcommand. See also Testing LIGO.
type michelson_program
type michelson_program
A type for code that is compiled to Michelson.
type michelson_contract
type michelson_contract
A type for Michelson compiled contracts.
type test_exec_error_balance_too_low = { contract_balance : tez ; contract_too_low : address ; spend_request : tez }
type test_exec_error_balance_too_low = { contract_balance : tez , contract_too_low : address , spend_request : tez }
type test_exec_error =
Rejected of michelson_program * address
| Balance_too_low of test_exec_error_balance_too_low
| Other of string
type test_exec_error =
["Rejected", michelson_program, address]
| ["Balance_too_low", test_exec_error_balance_too_low]
| ["Other", string]
A test error:
- The
Rejectedcase means the called contract or its transitive callees (identified by the address in the second constructor argument) failed with some data (first constructor argument) - The
Balance_too_lowcase means a contract tried to push an operation but did not have enough balance.contract_too_lowis the address of the contract,contract_balanceis the actual balance of the contract andspend_requestis the amount of tez that was required for the operation - The
Othercase wraps all the other possible reasons. Its argument is a string representation of the tezos_client error
type test_exec_result =
Success of nat
| Fail of test_exec_error
type test_exec_result =
["Success", nat]
| ["Fail", test_exec_error]
A test execution result:
- The
Successcase means the transaction went through without an issue. Its argument represent the total amount of gas consumed by the transaction - The "Fail reason" case means something went wrong. Its argument encode the causes of the failure (see type
test_exec_error)
type test_baker_policy =
| By_round of int
| By_account of address
| Excluding of address list
type test_baker_policy =
["By_round", int]
| ["By_account", address]
| ["Excluding", list<address>]
A test baking policy as used by the underlying testing helpers. The
case By_account is the standard one, as used by Test.set_baker.
Policies to select the next baker (taken from test helpers documentation):
By_round rselects the baker at roundrBy_account pkhselects the first slot for bakerpkhExcluding pkhsselects the first baker that doesn't belong topkhs
type ('param, 'storage) typed_address
type typed_address <'param, 's>
A type for an address of a contract with parameter 'param and storage
'storage.
type 's unforged_ticket = { ticketer : address; value : 's; amount : nat }
type unforged_ticket <s> = { ticketer : address, value : s, amount : nat }
A type for decompiling tickets.
val to_contract : ('param, 'storage) typed_address -> 'param contract
let to_contract = (account: typed_address <'param, 'storage>) => contract <'param>
Get the contract corresponding to the default entrypoint of a typed
address: the contract parameter in the result will be the type of the
default entrypoint (generally 'param, but this might differ if
'param includes a "default" entrypoint).
val to_entrypoint : string -> ('param, 'storage) typed_address -> 'e contract
let to_entrypoint = (entrypoint: string, account: typed_address <'param, 'storage>) => contract <'e>
Get the contract corresponding to an entrypoint of a typed address: the contract parameter in the result will be the type of the entrypoint, it needs to be annotated, entrypoint string should omit the prefix "%", but if passed a string starting with "%", it will be removed (and a warning emitted).
val originate_from_file : string -> string -> string list -> michelson_program -> tez -> address * michelson_contract * int
let originate_from_file = (filepath: string, entrypoint: string, views: list<string>, init: michelson_program, balance: tez) => [address, michelson_contract, int]
Originate a contract with a path to the contract file, an entrypoint, and a list of views, together with an initial storage and an initial balance.
let addr, contract, size =
Test.originate_from_file testme_test "main" [] init_storage 0tez
...
let [addr, contract, size] = Test.originate_from_file(testme_test, "main", list([]), init_storage, 0tez);
val compile_contract_from_file : string -> string -> string list -> michelson_contract
let compile_contract_from_file = (filepath: string, entrypoint: string, views: list<string>) => michelson_contract
Compiles a contract with a path to the contract file, an entrypoint, and a list of views.
val originate : ('param -> 'storage -> operation list * 'storage) -> 'storage -> tez -> (('param, 'storage) typed_address * michelson_contract * int)
let originate = (contract: (p: 'param, s: 'storage) => [list <operation>, 'storage], init: 'storage, balance: tez) => [typed_address <'param, 'storage>, michelson_contract, int]
Originate a contract with an entrypoint function in curried form, initial storage and initial balance.
val originate_module : (('param, 'storage) module_contract) -> 'storage -> tez -> (('param, 'storage) typed_address * michelson_contract * int)
let originate_module = (contract: module_contract<'param, 'storage>, init: 'storage, balance: tez) => [typed_address <'param, 'storage>, michelson_contract, int]
Originate a contract from a module/namespace. To obtain a module_contract from a module, use the contract_of keyword.
let taddr, contract, size =
Test.originate (contract_of C) init_storage 0tez
...
let [taddr, contract, size] = Test.originate(contract_of(C), init_storage, 0tez);
val compile_contract : ('param * 'storage -> operation list * 'storage) -> michelson_contract
let compile_contract = (contract: ('param, 'storage) => (list <operation>, 'storage)) => michelson_contract
Compiles a contract from an entrypoint function.
val read_contract_from_file : string -> michelson_contract
let read_contract_from_file = (filepath: string) => michelson_contract
Reads a contract from a .tz file.
val originate_contract : michelson_contract -> michelson_program -> tez -> address
let originate_contract = (contract: michelson_contract, init: michelson_program, balance: tez) => address
Originate a contract with initial storage and initial balance.
val size : michelson_contract -> int
let size = (contract: michelson_contract) => int
Measure the size of a contract.
val set_source : address -> unit
let set_source = (source: address) => unit
Set the source for Test.transfer and Test.originate.
val set_baker_policy : test_baker_policy -> unit
let set_baker_policy = (policy: test_baker_policy) => unit
Force the baking policy for Test.transfer and Test.originate. By
default, the first bootstrapped account.
val set_baker : address -> unit
let set_baker = (source: address) => unit
Force the baker for Test.transfer and Test.originate, implemented
using Test.set_baker_policy with By_account. By default, the first
bootstrapped account.
val transfer : address -> michelson_program -> tez -> test_exec_result
let transfer = (addr: address, param: michelson_program, amount: tez) => test_exec_result
Bake a transaction by sending an amount of tez with a parameter from the current source to another account. Returns the amount of gas consumed by the execution of the contract.
val transfer_exn : address -> michelson_program -> tez -> nat
let transfer_exn = (addr: address, parameter: michelson_program, amount: tez) => nat
Similar as Test.transfer, but fails when anything goes wrong.
val transfer_to_contract : 'param contract -> 'param -> tez -> test_exec_result
let transfer_to_contract = (addr: contract<'p>, param: 'p, amount: tez) => test_exec_result
Bake a transaction by sending an amount of tez with a parameter from the current source to a contract. Returns the amount of gas consumed by the execution of the contract.
val transfer_to_contract_exn : 'p contract -> 'p -> tez -> nat
let transfer_to_contract_exn = (addr: contract<'p>, parameter: 'p, amount: tez) => nat
Similar as Test.transfer_to_contract, but fails when anything goes wrong.
val storage_with_dynamic_entrypoints : 'contract ->
'storage ->
{
dynamic_entrypoints : dynamic_entrypoints;
storage : 'storage
}
let storage_with_dynamic_entrypoints = (contract: module_contract<'param, 'storage>, 'storage) =>
{
dynamic_entrypoints : dynamic_entrypoints;
storage : 'storage
}
val get_storage_of_address : address -> michelson_program
let get_storage_of_address = (account: address) => michelson_program
Get the storage of an account in michelson_program.
val get_storage : ('param, 'storage) typed_address -> 'storage
let get_storage = (account: typed_address <'p, 's>) => 's
Get the storage of a typed account.
val get_balance : address -> tez
let get_balance = (account: address) => tez
Get the balance of an account in tez.
val get_voting_power : key_hash -> nat
let get_voting_power = (kh: key_hash) => nat
Return the voting power of a given contract. This voting power coincides with the weight of the contract in the voting listings (i.e., the rolls count) which is calculated at the beginning of every voting period.
val get_total_voting_power : nat
let get_total_voting_power = nat
Return the total voting power of all contracts. The total voting power coincides with the sum of the rolls count of every contract in the voting listings. The voting listings is calculated at the beginning of every voting period.
val michelson_equal : michelson_program -> michelson_program -> bool
let michelson_equal = (a: michelson_program, b: michelson_program) => bool
Compare two Michelson values.
val log : 'a -> unit
let log = (a: 'a) => unit
Log a value.
val to_string : 'a -> string
let to_string = (a: 'a) => string
Convert a value to a string (same conversion as used by log).
val to_json : 'a -> string
let to_json = (a: 'a) => string
Convert a value to its JSON representation (as a string). A JSON schema is available here.
val print : string -> unit
let print = (s: string) => unit
Prints an string to stdout.
val println : string -> unit
let println = (s: string) => unit
Prints an string to stdout, ended with a newline.
val eprint : string -> unit
let eprint = (s: string) => unit
Prints an string to stderr.
val nl : string
let nl : string
String consisting of only a newline.
val chr : nat -> string option
let chr = (c: nat) => option<string>
String consisting of the character represented by a nat in the
interval [0, 255].
val reset_state : nat -> tez list -> unit
let reset_state = (no_of_accounts: nat, amount: list<tez>) => unit
Generate a number of random bootstrapped accounts with a default amount of 4000000 tez. The passed list can be used to overwrite the amount. By default, the state only has two bootstrapped accounts.
Notice that since Ithaca, a percentage of an account's balance is
frozen (5% in testing mode) in case the account can be taken to be a
validator (see
here),
and thus Test.get_balance can show a different amount to the one
being set with Test.reset_state.
val reset_state_at : timestamp -> nat -> tez list -> unit
let reset_state_at = (initial_timestamp : timestamp, no_of_accounts: nat, amount: list<tez>) => unit
Same as reset_state but accepts a timestamp which is set as the initial timestamp of the genesis block.
val get_time : unit -> timestamp
let get_time = (_u: unit) => timestamp
Gets the current time (to be used in test mode).
val baker_account : (string * key) -> tez option -> unit
let baker_account = ([string, key], amount : option<tez>) => unit
Adds an account (sk, pk) as a baker. The change is only effective
after Test.reset_state.
val register_delegate : key_hash -> unit
let register_delegate = (account : key_hash) => unit
Registers a key_hash corresponding to an account as a delegate.
val register_constant : michelson_program -> string
let register_constant = (constant : michelson_program) => string
Registers a global constant constant, returns its hash as a string.
See the documentation for global constants for an example of usage.
val constant_to_michelson_program : string -> michelson_program
let constant_to_michelson_program = (constant : string) => michelson_program
Turn a constant (as a string) into a michelson_program. To be used
together with Test.register_constant.
val parse_michelson : string -> michelson_program
let parse_michelson = (constant : string) => michelson_program
Parses Michelson (as string) into a michelson_program.
val register_file_constants : string -> string list
let register_file_constants = (filepath : string) => list<string>
Registers the global constants listed in a JSON file. It takes a string (file path) and returns a list of strings corresponding to the hashes of the registered constants.
val bake_until_n_cycle_end : nat -> unit
let bake_until_n_cycle_end = (cycles : nat) => unit
It bakes until a number of cycles pass, so that an account registered as delegate can effectively act as a baker.
Note : It can be used in tests to manually advance time
val new_account : unit -> (string * key)
let new_account = (_: unit) => (string, key)
Creates and returns secret key & public key of a new account.
val add_account : (string * key) -> unit
let add_account = (sk: string, pk: key) => unit
Adds an account specfied by secret key & public key to the test context.
val nth_bootstrap_account : int -> address
let nth_bootstrap_account = (nth: int) => address
Returns the address of the nth bootstrapped account.
val nth_bootstrap_contract : nat -> address
let nth_bootstrap_contract = (nth: nat) => address
Returns the address corresponding to the nth bootstrapped contract.
val bootstrap_contract : tez -> ('param * 'storage -> operation list * 'storage) -> 'storage -> unit
let bootstrap_contract = (balance: tez, contract: ('param, 'storage) => (list <operation>, 'storage), init: 'storage) => unit
Setup a bootstrap contract with an entrypoint function, initial storage and initial balance. Bootstrap contracts will be loaded in order, and they will be available only after reset.
val nth_bootstrap_typed_address : int -> ('param, 'storage) typed_address
let nth_bootstrap_typed_address = (nth: int) => typed_address <'p, 's>
Returns the typed address corresponding to the nth bootstrapped
contract currently loaded. The types are inferred from those contracts
loaded with Test.bootstrap_contract (before reset).
val get_bootstrap_account : nat -> address * key * string
let get_bootstrap_account = (nth: nat) => [address, key, string]
Returns the address, key and secret key of the nth bootstrapped account.
val last_originations : unit -> (address * address list) map
let last_originations = (_: unit) => map<address , address list>
Returns addresses of orginated accounts in the last transfer. It is given in the form of a map binding the address of the source of the origination operation to the addresses of newly originated accounts.
val compile_value : 'a -> michelson_program
let compile_value = (value: 'a) => michelson_program
Compile a LIGO value to Michelson.
val eval : 'a -> michelson_program
let eval = (value: 'a) => michelson_program
Compile a LIGO value to Michelson. Currently it is a renaming of
compile_value.
val run : ('a -> 'b) -> 'a -> michelson_program
let run = (func: ('a => 'b), value: 'a) => michelson_program
Run a function on an input, all in Michelson. More concretely: a)
compiles the function argument to Michelson f_mich; b) compiles the
value argument (which was evaluated already) to Michelson v_mich; c)
runs the Michelson interpreter on the code f_mich with starting
stack [v_mich].
type some_r = [@layout comb] {
one : int;
two : nat;
three : string;
four : bytes;
five : unit
}
let f = fun (x : some_r) -> x.one
let test_example =
Test.run (fun (x : int * nat * string * bytes * unit) -> f ({ one = x.0 ; two = x.1 ; three = x.2 ; four = x.3 ; five = x.4 }))
(1 + 3 + 2, 1n + 2n, "a" ^ "b", 0xFF00, ())
type some_r = [@layout comb] {
one : int;
two : nat;
three : string;
four : bytes;
five : unit
}
let f = fun (x : some_r) -> x.one
let test_example =
Test.run (fun (x : int * nat * string * bytes * unit) -> f ({ one = x.0 ; two = x.1 ; three = x.2 ; four = x.3 ; five = x.4 }))
(1 + 3 + 2, 1n + 2n, "a" ^ "b", 0xFF00, ())
type some_r =
@layout("comb")
{ one : int , two : nat , three : string , four : bytes , five : unit };
let f = (x: some_r) : int => x.one;
let test_example =
Test.run (((x : [int, nat, string, bytes, unit]) => f ({ one : x[0] , two : x[1] , three : x[2] , four : x[3] , five : x[4] })),
[1 + 3 + 2, 1n + 2n, ("a" + "b"), 0xFF00, unit]);
val decompile : michelson_program -> 'a
let decompile = (value: michelson_program) => 'a
Decompile a Michelson value to LIGO, following the (mandatory) type
annotation. Note: This operation can fail at run-time, in case that
the michelson_program given cannot be decompiled to something
compatible with the annotated type.
val mutate_value : nat -> 'a -> ('a * mutation) option
let mutate_value : (index: nat, value: 'a) => option <['a, mutation]>
Mutates a value using a natural number as an index for the available mutations, returns an option for indicating whether mutation was successful or not.
val mutation_test : 'a -> ('a -> 'b) -> ('b * mutation) option
let mutation_test : (value: 'a, tester: ('a -> 'b)) => option <['b, mutation]>
Given a value to mutate (first argument), it will try all the mutations available of it, passing each one to the function (second argument). On the first case of non failure when running the function on a mutation, the value and mutation involved will be returned.
val mutation_test_all : 'a -> ('a -> 'b) -> ('b * mutation) list
let mutation_test_all : (value: 'a, tester: ('a -> 'b)) => list <['b, mutation]>
Given a value to mutate (first argument), it will try all the mutations of it, passing each one to the function (second argument). In case no failure arises when running the function on a mutation, the failure and mutation involved will be added to the list to be returned.
val originate_from_file_and_mutate : string -> string -> string list -> michelson_program -> tez -> (address * michelson_contract * int -> 'b) -> ('b * mutation) option
let originate_from_file_and_mutate : (filepath: string, entrypoint: string, views: list<string>, init: michelson_program, balance: tez, (tester: (originated_address: address, code: michelson_contract, size: int) => 'b)) => option<['b, mutation]>
Given a contract from a file (passed by filepath, entrypoint and views), an initial storage and balance, it will originate mutants of the contract and pass the result to the function (last argument). On the first case of non failure when running the function on a mutation, the value and mutation involved will be returned.
val originate_from_file_and_mutate_all : string -> string -> string list -> michelson_program -> tez -> (address * michelson_contract * int -> 'b) -> ('b * mutation) list
let originate_from_file_and_mutate_all : (filepath: string, entrypoint: string, views: list<string>, init: michelson_program, balance: tez, (tester: (originated_address: address, code: michelson_contract, size: int) => 'b)) => list<['b, mutation]>
Given a contract from a file (passed by filepath, entrypoint and views), an initial storage and balance, it will originate mutants of the contract and pass the result to the function (last argument). In case no failure arises when running the function on a mutation, the failure and mutation involved will be added to the list to be returned.
val originate_module_and_mutate : (('param, 'storage) module_contract) -> 'storage -> tez -> (('param, 'storage) typed_address -> michelson_contract -> int -> b) -> ('b * mutation) option
let originate_module_and_mutate : (contract: module_contract<'p, 's>, init: 's, balance: tez, (tester: (originated_address: typed_address<'p, 's>, code: michelson_contract, size: int) => 'b)) => option<['b, mutation]>
Given a contract as a module/namespace, an initial storage and balance, it will originate mutants of the contract and pass the result to the function (last argument). On the first case of non failure when running the function on a mutation, the value and mutation involved will be returned.
val originate_module_and_mutate_all : (('param, 'storage) module_contract) -> 'storage -> tez -> (('param, 'storage) typed_address -> michelson_contract -> int -> b) -> ('b * mutation) list
let originate_module_and_mutate_all : (contract: module_contract<'p, 's>, init: 's, balance: tez, (tester: (originated_address: typed_address<'p, 's>, code: michelson_contract, size: int) => 'b)) => list<['b, mutation]>
Given a contract as a module/namespace, an initial storage and balance, it will originate mutants of the contract and pass the result to the function (last argument). In case no failure arises when running the function on a mutation, the failure and mutation involved will be added to the list to be returned.
val save_mutation : string -> mutation -> string option
let save_mutation : (path: string, mutation: mutation) => option <string>
This function reconstructs a file from a mutation (second argument),
and saves it to a file in the directory path (first argument). It
returns an optional string indicating the filename where the mutation
was saved, or None if there was an error.
val random : unit -> 'a
let random : (u: unit) => 'a
This function creates a random value for a chosen type.
val cast_address : address -> ('param,'storage) typed_address
let cast_address : (addr: adress) => typed_address <'param, 'storage>
This function casts an address to a typed address. You will need to annotate the result with the type you expect.
val set_big_map : int -> ('key, 'value) big_map -> unit
let set_big_map: (id: 'int, big_map: big_map<'key, 'value>) => unit
The testing framework keeps an internal reference to the values corresponding to big map identifiers. This function allows to override the value of a particular big map identifier. It should not be normally needed, except in particular circumstances such as using custom bootstrap contracts that initialize big maps.
val save_context : unit -> unit
let save_context: (u: unit) => unit
Takes current testing framework context and saves it, pushing it into a stack of contexts.
val restore_context : unit -> unit
let restore_context: (u: unit) => unit
Pops a testing framework context from the stack of contexts, and sets it up as the new current context. In case the stack was empty, the current context is kept.
val drop_context : unit -> unit
let drop_context: (u: unit) => unit
Drops a testing framework context from the stack of contexts. In case the stack was empty, nothing is done.
val sign : string -> bytes -> signature
let sign: (secret_key: string, data: bytes) => signature
Creates a signature of bytes from a string representing a secret
key, it can be checked with Crypto.check.
val set_print_values : unit -> unit
let set_print_values = (u: unit) => unit
Turns on the printing of test prefixed values at the end of tests. This is the default behaviour.
val unset_print_values : unit -> unit
let unset_print_values = (u: unit) => unit
Turns off the printing of test prefixed values at the end of tests.
val get_last_events_from : ('p,'s) typed_address -> string -> 'a list
let get_last_events_from: typed_address <'p,'s> => string => list <'a>
Returns the list of all the event payloads emited with a given tag by a given address. Any call to this function must be annotated with the expected payload type.
Failwith and asserts
val failwith : 'a -> unit
let failwith: (message: 'a) => unit
Cause the testing framework to fail.
val assert : bool -> unit
let assert: (condition: bool) => unit
Check if a certain condition has been met. If not the testing framework will fail.
val assert_with_error : bool -> string -> unit
let assert_with_error: (condition: bool, message: string) => unit
Check if a certain condition has been met. If not the testing framework will fail with the string passed as message.
Timelock
val create_chest : bytes -> nat -> chest * chest_key
let create_chest: (payload: bytes, time: nat) => [chest, chest_key]
Function which given a payload and time, generates a chest and
chest_key.
val create_chest_key : chest -> nat -> chest_key
let create_chest_key: (chest: chest, time: nat) => chest_key
Function to unlock the value and create a proof.
Proxy_ticket
Helper functions for working with tickets in the LIGO Testing framework.
Find the complete API reference here