Test

Important: The Test module is only available inside the ligo run test command. See also Testing LIGO.

cameligo

type michelson_program

jsligo

type michelson_program

A type for code that is compiled to Michelson.

cameligo

type michelson_contract

jsligo

type michelson_contract

A type for Michelson compiled contracts.

cameligo

type test_exec_error_balance_too_low = { contract_balance : tez ; contract_too_low : address ; spend_request : tez }

jsligo

type test_exec_error_balance_too_low = { contract_balance : tez , contract_too_low : address , spend_request : tez }

cameligo

type test_exec_error =
Rejected of michelson_program * address
| Balance_too_low of test_exec_error_balance_too_low
| Other of string

jsligo

type test_exec_error =
["Rejected", michelson_program, address]
| ["Balance_too_low", test_exec_error_balance_too_low]
| ["Other", string]

A test error:

• The Rejected case 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_low case means a contract tried to push an operation but did not have enough balance. contract_too_low is the address of the contract, contract_balance is the actual balance of the contract and spend_request is the amount of tez that was required for the operation
• The Other case wraps all the other possible reasons. Its argument is a string representation of the tezos_client error

cameligo

type test_exec_result =
Success of nat
| Fail of test_exec_error

jsligo

type test_exec_result =
["Success", nat]
| ["Fail", test_exec_error]

A test execution result:

• The Success case 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)

cameligo

type test_baker_policy =
| By_round of int
| By_account of address
| Excluding of address list

jsligo

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 r selects the baker at round r
• By_account pkh selects the first slot for baker pkh
• Excluding pkhs selects the first baker that doesn't belong to pkhs

cameligo

type ('param, 'storage) typed_address

jsligo

type typed_address <'param, 's>

A type for an address of a contract with parameter 'param and storage 'storage.

cameligo

type 's unforged_ticket = { ticketer : address; value : 's; amount : nat }

jsligo

type unforged_ticket <s> = { ticketer : address, value : s, amount : nat }

A type for decompiling tickets.

cameligo

val to_contract : ('param, 'storage) typed_address -> 'param contract

jsligo

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).

cameligo

val to_entrypoint : string -> ('param, 'storage) typed_address -> 'e contract

jsligo

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).

cameligo

val originate_from_file : string -> string -> string list -> michelson_program -> tez -> address * michelson_contract * int

jsligo

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", list([]), init_storage, 0tez);

cameligo

val compile_contract_from_file : string -> string -> string list -> michelson_contract

jsligo

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.

cameligo

val originate : ('param -> 'storage -> operation list * 'storage) -> 'storage -> tez -> (('param, 'storage) typed_address * michelson_contract * int)

jsligo

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.

cameligo

val originate_module : (('param, 'storage) module_contract) -> 'storage -> tez -> (('param, 'storage) typed_address * michelson_contract * int)

jsligo

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);

cameligo

val compile_contract : ('param * 'storage -> operation list * 'storage) -> michelson_contract

jsligo

let compile_contract = (contract: ('param, 'storage) => (list <operation>, 'storage)) => michelson_contract

Compiles a contract from an entrypoint function.

cameligo

val read_contract_from_file : string -> michelson_contract

jsligo

let read_contract_from_file = (filepath: string) => michelson_contract

Reads a contract from a .tz file.

cameligo

val originate_contract : michelson_contract -> michelson_program -> tez -> address

jsligo

let originate_contract = (contract: michelson_contract, init: michelson_program, balance: tez) => address

Originate a contract with initial storage and initial balance.

cameligo

val size : michelson_contract -> int

jsligo

let size = (contract: michelson_contract) => int

Measure the size of a contract.

cameligo

val set_source : address -> unit

jsligo

let set_source = (source: address) => unit

Set the source for Test.transfer and Test.originate.

cameligo

val set_baker_policy : test_baker_policy -> unit

jsligo

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.

cameligo

val set_baker : address -> unit

jsligo

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.

cameligo

val transfer : address -> michelson_program -> tez -> test_exec_result

jsligo

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.

cameligo

val transfer_exn : address -> michelson_program -> tez -> nat

jsligo

let transfer_exn = (addr: address, parameter: michelson_program, amount: tez) => nat

Similar as Test.transfer, but fails when anything goes wrong.

cameligo

val transfer_to_contract : 'param contract -> 'param -> tez -> test_exec_result

jsligo

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.

cameligo

val transfer_to_contract_exn : 'p contract -> 'p -> tez -> nat

jsligo

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.

let storage_with_dynamic_entrypoints = (contract: module_contract<'param, 'storage>, 'storage) =>
  {
   dynamic_entrypoints : dynamic_entrypoints;
   storage : 'storage
  }

cameligo

val get_storage_of_address : address -> michelson_program

jsligo

let get_storage_of_address = (account: address) => michelson_program

Get the storage of an account in michelson_program.

cameligo

val get_storage : ('param, 'storage) typed_address -> 'storage

jsligo

let get_storage = (account: typed_address <'p, 's>) => 's

Get the storage of a typed account.

cameligo

val get_balance : address -> tez

jsligo

let get_balance = (account: address) => tez

Get the balance of an account in tez.

cameligo

val get_voting_power : key_hash -> nat

jsligo

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.

cameligo

val get_total_voting_power : nat

jsligo

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.

cameligo

val michelson_equal : michelson_program -> michelson_program -> bool

jsligo

let michelson_equal = (a: michelson_program, b: michelson_program) => bool

Compare two Michelson values.

cameligo

val log : 'a -> unit

jsligo

let log = (a: 'a) => unit

Log a value.

cameligo

val to_string : 'a -> string

jsligo

let to_string = (a: 'a) => string

Convert a value to a string (same conversion as used by log).

cameligo

val to_json : 'a -> string

jsligo

let to_json = (a: 'a) => string

Convert a value to its JSON representation (as a string). A JSON schema is available here.

cameligo

val print : string -> unit

jsligo

let print = (s: string) => unit

Prints an string to stdout.

cameligo

val println : string -> unit

jsligo

let println = (s: string) => unit

Prints an string to stdout, ended with a newline.

cameligo

val eprint : string -> unit

jsligo

let eprint = (s: string) => unit

Prints an string to stderr.

cameligo

val nl : string

jsligo

let nl : string

String consisting of only a newline.

cameligo

val chr : nat -> string option

jsligo

let chr = (c: nat) => option<string>

String consisting of the character represented by a nat in the interval [0, 255].

cameligo

val reset_state : nat -> tez list -> unit

jsligo

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.

cameligo

val reset_state_at : timestamp -> nat -> tez list -> unit

jsligo

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.

cameligo

val get_time : unit -> timestamp

jsligo

let get_time = (_u: unit) => timestamp

Gets the current time (to be used in test mode).

cameligo

val baker_account : (string * key) -> tez option -> unit

jsligo

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.

cameligo

val register_delegate : key_hash -> unit

jsligo

let register_delegate = (account : key_hash) => unit

Registers a key_hash corresponding to an account as a delegate.

cameligo

val register_constant : michelson_program -> string

jsligo

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.

cameligo

val constant_to_michelson_program : string -> michelson_program

jsligo

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.

cameligo

val parse_michelson : string -> michelson_program

jsligo

let parse_michelson = (constant : string) => michelson_program

Parses Michelson (as string) into a michelson_program.

cameligo

val register_file_constants : string -> string list

jsligo

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.

cameligo

val bake_until_n_cycle_end : nat -> unit

jsligo

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

cameligo

val new_account : unit -> (string * key)

jsligo

let new_account = (_: unit) => (string, key)

Creates and returns secret key & public key of a new account.

cameligo

val add_account : (string * key) -> unit

jsligo

let add_account = (sk: string, pk: key) => unit

Adds an account specfied by secret key & public key to the test context.

cameligo

val nth_bootstrap_account : int -> address

jsligo

let nth_bootstrap_account = (nth: int) => address

Returns the address of the nth bootstrapped account.

cameligo

val nth_bootstrap_contract : nat -> address

jsligo

let nth_bootstrap_contract = (nth: nat) => address

Returns the address corresponding to the nth bootstrapped contract.

cameligo

val bootstrap_contract : tez -> ('param * 'storage -> operation list * 'storage) -> 'storage -> unit

jsligo

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.

cameligo

val nth_bootstrap_typed_address : int -> ('param, 'storage) typed_address

jsligo

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).

cameligo

val get_bootstrap_account : nat -> address * key * string

jsligo

let get_bootstrap_account = (nth: nat) => [address, key, string]

Returns the address, key and secret key of the nth bootstrapped account.

cameligo

val last_originations : unit -> (address * address list) map

jsligo

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.

cameligo

val compile_value : 'a -> michelson_program

jsligo

let compile_value = (value: 'a) => michelson_program

Compile a LIGO value to Michelson.

cameligo

val eval : 'a -> michelson_program

jsligo

let eval = (value: 'a) => michelson_program

Compile a LIGO value to Michelson. Currently it is a renaming of compile_value.

cameligo

val run : ('a -> 'b) -> 'a -> michelson_program

jsligo

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 = (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]);

cameligo

val decompile : michelson_program -> 'a

jsligo

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.

cameligo

val mutate_value : nat -> 'a -> ('a * mutation) option

jsligo

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.

cameligo

val mutation_test : 'a -> ('a -> 'b) -> ('b * mutation) option

jsligo

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.

cameligo

val mutation_test_all : 'a -> ('a -> 'b) -> ('b * mutation) list

jsligo

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.

cameligo

val originate_from_file_and_mutate : string -> string -> string list -> michelson_program -> tez -> (address * michelson_contract * int -> 'b) -> ('b * mutation) option

jsligo

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.

cameligo

val originate_from_file_and_mutate_all : string -> string -> string list -> michelson_program -> tez -> (address * michelson_contract * int -> 'b) -> ('b * mutation) list

jsligo

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.

cameligo

val originate_module_and_mutate : (('param, 'storage) module_contract) -> 'storage -> tez -> (('param, 'storage) typed_address -> michelson_contract -> int -> b) -> ('b * mutation) option

jsligo

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.

cameligo

val originate_module_and_mutate_all : (('param, 'storage) module_contract) -> 'storage -> tez -> (('param, 'storage) typed_address -> michelson_contract -> int -> b) -> ('b * mutation) list

jsligo

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.

cameligo

val save_mutation : string -> mutation -> string option

jsligo

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.

cameligo

val random : unit -> 'a

jsligo

let random : (u: unit) => 'a

This function creates a random value for a chosen type.

cameligo

val cast_address : address -> ('param,'storage) typed_address

jsligo

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.

cameligo

val set_big_map : int -> ('key, 'value) big_map  -> unit

jsligo

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.

cameligo

val save_context : unit -> unit

jsligo

let save_context: (u: unit) => unit

Takes current testing framework context and saves it, pushing it into a stack of contexts.

cameligo

val restore_context : unit -> unit

jsligo

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.

cameligo

val drop_context : unit -> unit

jsligo

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.

cameligo

val sign : string -> bytes -> signature

jsligo

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.

cameligo

val set_print_values : unit -> unit

jsligo

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.

cameligo

val unset_print_values : unit -> unit

jsligo

let unset_print_values = (u: unit) => unit

Turns off the printing of test prefixed values at the end of tests.

cameligo

val get_last_events_from : ('p,'s) typed_address -> string -> 'a list

jsligo

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

cameligo

val failwith : 'a -> unit

jsligo

let failwith: (message: 'a) => unit

Cause the testing framework to fail.

cameligo

val assert : bool -> unit

jsligo

let assert: (condition: bool) => unit

Check if a certain condition has been met. If not the testing framework will fail.

cameligo

val assert_with_error : bool -> string -> unit

jsligo

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

cameligo

val create_chest : bytes -> nat -> chest * chest_key

jsligo

let create_chest: (payload: bytes, time: nat) => [chest, chest_key]

Function which given a payload and time, generates a chest and chest_key.

cameligo

val create_chest_key : chest -> nat -> chest_key

jsligo

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