package octez-protocol-alpha-libs

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

This module centralises all modules related to Scenario writing and execution. Most scenario tests would use most if not all of them, so they only need to open Scenario.

include module type of struct include Scenario_base end
type Tezos_base.TzPervasives.error +=
  1. | Unexpected_error

For assert_failure, when expected error does not match the actual error.

type Tezos_base.TzPervasives.error +=
  1. | Unexpected_success

For assert_failure, when scenario actually succeeds when expected to fail.

type t = Block.t * State.t

Usual threaded state for the tests. Contains the current block, pending operations and the known State.t

val log : ?level:Tezt_core.Cli.Logs.level -> ?color:Tezt_core.Log.Color.t -> ('a, Format.formatter, unit, ('b, 'b) Scenario_dsl.scenarios) format4 -> 'c
val set_baker : string -> (t, t) Scenario_dsl.scenarios

Sets the de facto baker for all future blocks

val exclude_bakers : string list -> (t, t) Scenario_dsl.scenarios

Exclude a list of delegates from baking

val unset_baking_policy : (t, t) Scenario_dsl.scenarios

Unsets the baking policy, it returns to default (By_round 0)

Creates a snapshot of the current balances for the given account names. Can be used to check that balances at point A and B in the execution of a test are the same (either nothing happened, or a succession of actions resulted in getting the same values as before

Check balances against a previously defined snapshot

val save_current_rate : (t, t) Scenario_dsl.scenarios

Save the current issuance rate for future use

val check_rate_evolution : (Q.t -> Q.t -> bool) -> (t, t) Scenario_dsl.scenarios

Check that f saved_rate current_rate is true. f is typically a comparison function

val check_failure_aux : ?loc:string -> ?expected_error:('a -> Tezos_base.TzPervasives.tztrace) -> ('a0 -> 'b Tezos_base.TzPervasives.tzresult Lwt.t) -> 'a0 -> 'a0 Tezos_base.TzPervasives.tzresult Lwt.t
val check_fail_and_rollback : ?loc:string -> ?expected_error:('a -> Tezos_base.TzPervasives.tztrace) -> ('a0, 'b) Scenario_dsl.single_scenario -> 'a0 -> 'a0 Tezos_base.TzPervasives.tzresult Lwt.t
val assert_failure : ?loc:string -> ?expected_error:('a -> Tezos_base.TzPervasives.tztrace) -> ('a0, 'b) Scenario_dsl.scenarios -> ('a0, 'a0) Scenario_dsl.scenarios

Useful function to test expected failures: runs the given branch until it fails, then rollbacks to before execution. Fails if the given branch Succeeds

val assert_success : ?loc:string -> ('a, 'b) Scenario_dsl.scenarios -> ('a, 'a) Scenario_dsl.scenarios

Check a scenario does not fail, and rolls back to before the assert

val loop : int -> ('a, 'a) Scenario_dsl.scenarios -> ('a0, 'a1) Scenario_dsl.scenarios

Loop

val loop_action : int -> ('a -> 'a Tezos_base.TzPervasives.tzresult Lwt.t) -> ('a0, 'a1) Scenario_dsl.scenarios
val check_balance_field : Tezos_base.TzPervasives.String.Map.key -> [< `Bonds | `Liquid | `Staked | `Total | `Unstaked_finalizable | `Unstaked_frozen_total ] -> Tezos_protocol_alpha.Protocol.Alpha_context.Tez.t -> (t, t) Scenario_dsl.scenarios

Check a specific balance field for a specific account is equal to a specific amount

include module type of struct include Scenario_op end

Set delegate parameters for the given delegate

Add a new account with the given name

Reveal operation

Set delegate for src. If delegate_name_opt = None, then unset current delegate

val check_pending_slashings : loc:string -> (Block.t * State.t) -> unit Tezos_base.TzPervasives.tzresult Lwt.t
val order_attestations : correct_order:bool -> 'a Tezos_raw_protocol_alpha__Alpha_context.operation -> 'a Tezos_raw_protocol_alpha__Alpha_context.operation -> 'a Tezos_raw_protocol_alpha__Alpha_context.operation * 'a Tezos_raw_protocol_alpha__Alpha_context.operation

Double attestation helpers

val double_bake_op : string list -> (Block.t * State.t) -> (Block.t * State.t, Tezos_base.TzPervasives.tztrace) result Lwt.t

double_bake_op delegate_names (block, state) performs a double baking with the given delegate names. The first delegate in the list bakes the new main branch. All delegates (including the first) will bake two other blocks at the same level/different round.

val double_bake_many : string list -> (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios

double_attest_op ?other_bakers ~op ~op_evidence ~kind delegate_names (block, state) performs a double (pre)attestation with the given delegate names. Starting at block level `n`, it creates two 2-block branches and all delegates will (pre)attest the two blocks at level `n+2`. other_bakers can be used to force using specific bakers to avoid reusing forbidden ones

val double_attest_ : ?other_bakers:(string * string) -> string list -> (Block.t * State.t) -> (Block.t * State.t, Tezos_base.TzPervasives.tztrace) result Lwt.t
val double_attest_many : ?other_bakers:(string * string) -> string list -> (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios
val double_attest : ?other_bakers:(string * string) -> string -> (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios
val double_preattest_ : ?other_bakers:(string * string) -> string list -> (Block.t * State.t) -> (Block.t * State.t, Tezos_base.TzPervasives.tztrace) result Lwt.t
val double_preattest_many : ?other_bakers:(string * string) -> string list -> (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios
val double_preattest : ?other_bakers:(string * string) -> string -> (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios
val cycle_from_level : int32 -> int32 -> Tezos_alpha_test_helpers.State_account.Cycle.cycle
val get_pending_slashed_pct_for_delegate : (Block.t * State.t) -> Tezos_base.TzPervasives.Signature.Public_key_hash.t -> int
val make_denunciations_op : ?single:bool -> ?rev:bool -> ?filter:(State.double_signing_state -> bool) -> (Block.t * State.t) -> (State.t * Tezos_protocol_alpha.Protocol.Alpha_context.packed_operation list, Tezos_base.TzPervasives.tztrace) result Lwt.t

make_denunciations_op ?single ?rev ?filter () denounces all double signers in the state. If single is set, only one denunciation is made. If rev is set, the denunciations are made in reverse order. If filter is set, only the double signers for which the filter returns true are denounced.

val make_denunciations : ?single:bool -> ?rev:bool -> ?filter:(State.double_signing_state -> bool) -> unit -> (Block.t * State.t, Scenario_base.t) Scenario_dsl.scenarios

Create an account and give an initial balance funded by funder

include module type of struct include Scenario_dsl end
exception Test_failed
type ('input, 'output) scenarios = ('input, 'output) Scenario_dsl.scenarios =
  1. | Action : ('input -> 'output Tezos_base.TzPervasives.tzresult Lwt.t) -> ('input, 'output) scenarios
  2. | Empty : ('t, 't) scenarios
  3. | Concat : (('a, 'b) scenarios * ('b, 'c) scenarios) -> ('a, 'c) scenarios
  4. | Branch : (('a, 'b) scenarios * ('a, 'b) scenarios) -> ('a, 'b) scenarios
  5. | Tag : string -> ('t, 't) scenarios
  6. | Slow : ('t, 't) scenarios

A scenario is a succession of actions. We define a branching path as a way to create multiple tests from the same point. This allows easy compositionality of behaviors with minimal code sharing. The Tag allows to give meaningful identifiers to the branches. It is good practice to tag each case in a branch (it's not necessary, but since test names must be unique, at most one branch can remain unnamed, and even then it can create conflicting names.)

type ('input, 'output) single_scenario = ('input, 'output) Scenario_dsl.single_scenario =
  1. | End_scenario : ('t, 't) single_scenario
  2. | Cons : (('input -> 't Tezos_base.TzPervasives.tzresult Lwt.t) * ('t, 'output) single_scenario) -> ('input, 'output) single_scenario

Unfolded scenario type

val cat_ss : 'a 'b 'c. ('a, 'b) single_scenario -> ('b, 'c) single_scenario -> ('a, 'c) single_scenario
val combine : ('a -> 'b -> 'c) -> 'd list -> 'e list -> 'f list
val unfold_scenarios : 'input 'output. ('input, 'output) scenarios -> (('input, 'output) single_scenario * string list * bool) list
val run_scenario : 'input 'output. ('input, 'output) single_scenario -> 'input -> 'output Tezos_base.TzPervasives.tzresult Lwt.t
type test_closure = string * bool * (Tezt_tezos.Protocol.t -> unit Lwt.t)
val unfolded_to_test : ((unit, unit) single_scenario * string list * bool) -> test_closure
val register_test : __FILE__:string -> tags:string list -> test_closure -> unit
val register_tests : __FILE__:string -> tags:string list -> test_closure list -> unit

Useful aliases and operators

val noop : ('a, 'a) scenarios
val no_tag : ('a, 'a) scenarios
val concat : 'a 'b 'c. ('a, 'b) scenarios -> ('b, 'c) scenarios -> ('a, 'c) scenarios
val branch : 'a 'b. ('a, 'b) scenarios -> ('a, 'b) scenarios -> ('a, 'b) scenarios
val (-->) : ('a, 'b) scenarios -> ('b, 'c) scenarios -> ('a, 'c) scenarios

Continuation connector: execute a then b

val (|+) : ('a, 'b) scenarios -> ('a, 'b) scenarios -> ('a, 'b) scenarios

Branching connector: creates two tests with different execution paths

val end_test : ('a, unit) scenarios

Ends the test. Dump the state, returns unit

val tests_of_scenarios : (string * (unit, 't) scenarios) list -> test_closure list

Transforms scenarios into tests

val exec : ('a -> 'b Tezos_base.TzPervasives.tzresult Lwt.t) -> ('a, 'b) scenarios

Arbitrary execution

val exec_state : (('a * 'b) -> ('c, Tezos_base.TzPervasives.tztrace) result Lwt.t) -> ('a * 'b, 'd * 'e) scenarios

Execute a function that does not modify the block, only the state

val exec_unit : ('a -> (unit, Tezos_base.TzPervasives.tztrace) result Lwt.t) -> ('b, 'c) scenarios

Execute a function that does not modify neither the block nor the state. Usually used for checks/asserts

val fold : ('a -> ('b, 'c) scenarios) -> 'a0 list -> ('b0, 'c0) scenarios

fold f l folds f over l, fails on empty list

val fold_tag : ('a -> ('b, 'c) scenarios) -> (string * 'a) list -> ('b, 'c) scenarios

fold_tag f l folds f over l, l has a tag for each of its elements. Fails on empty list.

val fold_tag_f : ('a -> ('b, 'c) scenarios) -> ('a -> string) -> 'a list -> ('b, 'c) scenarios

fold_tag_f f tag l folds f over l, tag returns a tag for each element of l. Fails on empty list.

val unfold : ('a -> ('b, 'b) scenarios) -> 'a0 list -> ('b0, 'b1) scenarios

unfold f l maps f over l, and runs them in order

include module type of struct include Scenario_begin end
type Tezos_base.TzPervasives.error +=
  1. | Inconsistent_number_of_bootstrap_accounts

Returns when the number of bootstrap accounts created by Context.init_n n is not equal to n

type starter_constants = Scenario_begin.starter_constants =
  1. | Mainnet
  2. | Sandbox
  3. | Test
val start_with_list : constants:(string * Scenario_constants.constants) list -> (unit, Scenario_constants.constants) Scenario_dsl.scenarios
val activate_ai : [< `Force | `Force_and_vote_with_threshold of int32 | `No | `With_vote_threshold of int32 | `Zero_threshold ] -> (Scenario_constants.constants, Scenario_constants.constants) Scenario_dsl.scenarios
val init_constants : ?default:starter_constants -> ?reward_per_block:int64 -> ?deactivate_dynamic:bool -> ?blocks_per_cycle:int32 -> ?delegate_parameters_activation_delay:int -> unit -> (unit, Scenario_constants.constants) Scenario_dsl.scenarios

Initializes the constants for testing, with well chosen default values. Recommended over start or start_with

val begin_test : ?burn_rewards:bool -> ?force_attest_all:bool -> Tezos_base.TzPervasives.String.Map.key list -> (Scenario_constants.constants, Scenario_base.t) Scenario_dsl.scenarios

Initialize the test, given some initial parameters

include module type of struct include Scenario_constants end
type constants = Constants_helpers.t
val set_opt : ('a -> constants -> constants) -> 'a option -> (constants, constants) Scenario_dsl.scenarios
val sets : ('a -> constants -> constants) -> (string * 'a) list -> (constants, constants) Scenario_dsl.scenarios
val sets_f : ('a -> constants -> constants) -> ('a -> string) -> 'a list -> (constants, constants) Scenario_dsl.scenarios
val branch_flag : (bool -> constants -> constants) -> (constants, constants) Scenario_dsl.scenarios
val branch_flags : (bool -> constants -> constants) list -> (constants, constants) Scenario_dsl.scenarios
val sets_int : (int -> constants -> constants) -> int list -> (constants, constants) Scenario_dsl.scenarios
include module type of struct include Scenario_bake end

Applies when baking the last block of a cycle

Applies when baking the first block of a cycle. Technically nothing special happens, but we need to update the unslashable unstakes since it's done lazily

val check_all_balances : Block.t -> State.t -> unit Tezos_base.TzPervasives.tzresult Lwt.t

After baking and applying rewards in state

val check_issuance_rpc : Block.t -> unit Tezos_base.TzPervasives.tzresult Lwt.t

Bake a block, with the given baker and the given operations.

Bake until a cycle is reached, using bake instead of Block.bake

Bake all the remaining blocks of the current cycle

Bake a single block

val next_block_with_baker : string -> (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios

Bake a single block with a specific baker

Bake until the end of a cycle

Bake until the end of a cycle

Executes an operation: f should return a new state and a list of operations, which are then applied

Waiting functions

Waits until condition init_t current_t is fulfilled. It is checked on the first block of every cycle. If it returns false, another cycle is baked, until it succeeds.

val wait_cycle_until : [< `AI_activation | `AI_activation_with_votes | `And of 'b * 'b | `delegate_parameters_activation | `right_before_delegate_parameters_activation ] as 'a -> (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios

Wait until we are in a cycle satisfying the given condition. Fails if AI_activation is requested and AI is not set to be activated in the future.

Wait until AI activates. Fails if AI is not set to be activated in the future.

val wait_delegate_parameters_activation : (Scenario_base.t, Scenario_base.t) Scenario_dsl.scenarios

wait delegate_parameters_activation_delay cycles

OCaml

Innovation. Community. Security.