Test.Cleveland

Michelson contracts testing on a real Tezos network.

See the documentation for usage instructions.

Documentation

data AliasHint

Instances

Show AliasHint

Defined in Morley.Client.TezosClient.Types

Methods

showsPrec :: Int -> AliasHint -> ShowS

show :: AliasHint -> String

showList :: [AliasHint] -> ShowS

IsString AliasHint

Defined in Morley.Client.TezosClient.Types

Methods

fromString :: String -> AliasHint

Semigroup AliasHint

Defined in Morley.Client.TezosClient.Types

Methods

(<>) :: AliasHint -> AliasHint -> AliasHint

sconcat :: NonEmpty AliasHint -> AliasHint

stimes :: Integral b => b -> AliasHint -> AliasHint

Monoid AliasHint

Defined in Morley.Client.TezosClient.Types

Methods

mempty :: AliasHint

mappend :: AliasHint -> AliasHint -> AliasHint

mconcat :: [AliasHint] -> AliasHint

Buildable AliasHint

Defined in Morley.Client.TezosClient.Types

Methods

build :: AliasHint -> Builder

data ContractHandle (cp :: Type) (st :: Type) (vd :: Type)

Handle to a contract.

This is what you get when originating a contract and that allows further operations with the contract within the test framework.

Note that this is part of the testing framework and exists solely in Haskell world, so it has no IsoValue and related instances and cannot be used in Lorentz code.

Constructors

(NiceParameter cp, NiceStorage st, NiceViewsDescriptor vd) => ContractHandle

Fields

• chContractName :: Text
• chAddress :: Address

Instances

(cp' ~ cp, vd ~ vd') => ToTAddress cp' vd' (ContractHandle cp st vd)

Defined in Test.Cleveland.Lorentz.Types

Methods

toTAddress :: ContractHandle cp st vd -> TAddress cp' vd'

ToContractRef arg (TAddress cp vd) => ToContractRef arg (ContractHandle cp st vd)

Defined in Test.Cleveland.Lorentz.Types

Methods

toContractRef :: ContractHandle cp st vd -> ContractRef arg

st ~ st' => ToStorageType st' (ContractHandle cp st vd)

Defined in Test.Cleveland.Lorentz.Types

Methods

pickNiceStorage :: ContractHandle cp st vd -> Dict (NiceStorage st')

Show (ContractHandle cp st vd)

Defined in Test.Cleveland.Lorentz.Types

Methods

showsPrec :: Int -> ContractHandle cp st vd -> ShowS

show :: ContractHandle cp st vd -> String

showList :: [ContractHandle cp st vd] -> ShowS

Buildable (ContractHandle cp st vd)

Defined in Test.Cleveland.Lorentz.Types

Methods

build :: ContractHandle cp st vd -> Builder

ToAddress (ContractHandle cp st vd)

Defined in Test.Cleveland.Lorentz.Types

Methods

toAddress :: ContractHandle cp st vd -> Address

data OriginateData param st vd

Constructors

OriginateData

Fields

• odName :: AliasHint

  Alias for the originated contract.

• odBalance :: Mutez

  Initial balance.

• odStorage :: st

  Initial storage.

• odContract :: Contract param st vd

  The contract itself.

  We are using Lorentz version here which is convenient. However, keep in mind that if someone wants to test a contract from .tz file, they should use UntypedOriginateData.

data UntypedOriginateData

Untyped version of OriginateData. It can be used for interaction with raw Michelson contracts

Constructors

UntypedOriginateData

Fields

• uodName :: AliasHint

  Alias for the originated contract.

• uodBalance :: Mutez

  Initial balance.

• uodStorage :: Value

  Initial storage.

• uodContract :: Contract

  The contract itself.

data TransferData

Information about transfer operation.

Constructors

forall v addr.(NiceParameter v, ToAddress addr) => TransferData

Fields

• tdTo :: addr

  Receiver address for this transaction.

• tdAmount :: Mutez

  Amount to be transferred.

• tdEntrypoint :: EpName

  An entrypoint to be called. Consider using ep in testing scenarios.

• tdParameter :: v

  Parameter that will be used for a contract call. Set to () for transfers to key addresses.

data Scenario m

A type representing a finalized scenario

data PureM a

Instances

Monad PureM

Defined in Test.Cleveland.Internal.Pure

Methods

(>>=) :: PureM a -> (a -> PureM b) -> PureM b

(>>) :: PureM a -> PureM b -> PureM b

return :: a -> PureM a

Functor PureM

Defined in Test.Cleveland.Internal.Pure

Methods

fmap :: (a -> b) -> PureM a -> PureM b

(<$) :: a -> PureM b -> PureM a

MonadFail PureM

Defined in Test.Cleveland.Internal.Pure

Methods

fail :: String -> PureM a

Applicative PureM

Defined in Test.Cleveland.Internal.Pure

Methods

pure :: a -> PureM a

(<*>) :: PureM (a -> b) -> PureM a -> PureM b

liftA2 :: (a -> b -> c) -> PureM a -> PureM b -> PureM c

(*>) :: PureM a -> PureM b -> PureM b

(<*) :: PureM a -> PureM b -> PureM a

MonadIO PureM

Defined in Test.Cleveland.Internal.Pure

Methods

liftIO :: IO a -> PureM a

MonadCatch PureM

Defined in Test.Cleveland.Internal.Pure

Methods

catch :: Exception e => PureM a -> (e -> PureM a) -> PureM a

MonadThrow PureM

Defined in Test.Cleveland.Internal.Pure

Methods

throwM :: Exception e => e -> PureM a

MonadState PureState PureM

Defined in Test.Cleveland.Internal.Pure

Methods

get :: PureM PureState

put :: PureState -> PureM ()

state :: (PureState -> (a, PureState)) -> PureM a

MonadWriter LogsInfo PureM

Defined in Test.Cleveland.Internal.Pure

Methods

writer :: (a, LogsInfo) -> PureM a

tell :: LogsInfo -> PureM ()

listen :: PureM a -> PureM (a, LogsInfo)

pass :: PureM (a, LogsInfo -> LogsInfo) -> PureM a

MonadReader (IORef PureState) PureM

Defined in Test.Cleveland.Internal.Pure

Methods

ask :: PureM (IORef PureState)

local :: (IORef PureState -> IORef PureState) -> PureM a -> PureM a

reader :: (IORef PureState -> a) -> PureM a

Validation

data TransferFailure

Failures that could be expected in the execution of a transfer. These can be caught and handled with attempt.

Instances

Eq TransferFailure

Defined in Test.Cleveland.Internal.Abstract

Methods

(==) :: TransferFailure -> TransferFailure -> Bool

(/=) :: TransferFailure -> TransferFailure -> Bool

Show TransferFailure

Defined in Test.Cleveland.Internal.Abstract

Methods

showsPrec :: Int -> TransferFailure -> ShowS

show :: TransferFailure -> String

showList :: [TransferFailure] -> ShowS

Exception TransferFailure

Defined in Test.Cleveland.Internal.Abstract

Methods

toException :: TransferFailure -> SomeException

fromException :: SomeException -> Maybe TransferFailure

displayException :: TransferFailure -> String

Buildable TransferFailure

Defined in Test.Cleveland.Internal.Abstract

Methods

build :: TransferFailure -> Builder

Real network implementation based on tezos-client and RPC.

testScenario :: TestName -> (forall m. MonadFail m => Scenario m) -> TestTree

Create a tasty test case from a Scenario.

This will create a test tree with 2 tests: one that runs the Scenario on the Morley.Michelson.Runtime emulator, and another that runs it on a real Tezos network.

The network config is read from the command line/environment variables. Use --help to see the available options.

If a TestTree contains many tests scheduled to run on a real Tezos network, those tests will be run sequentially.

testScenarioOnNetwork :: TestName -> Scenario ClientM -> TestTree

Create a tasty test case from a Scenario.

This will create a test tree with 1 test, which will run the Scenario on real Tezos network.

scenario :: ClevelandT m () -> Scenario m

Finalize a generic cleveland scenario.

Emulation tests

testScenarioOnEmulator :: TestName -> Scenario PureM -> TestTree

Create a tasty test case from an emulated Scenario.

This will create a test tree with 1 test, which will run the Scenario on the Morley.Michelson.Runtime emulator.

scenarioEmulated :: EmulatedT PureM () -> Scenario PureM

Finalize a scenario that needs emulator-only features.

withInitialNow :: Timestamp -> Scenario PureM -> Scenario PureM

Use with an emulated Scenario to configure the initial now value in tests.

Example : > withInitialNow (Timestamp 10000000) $ testScenarioOnEmulator Testname $ scenarioEmulated $ tests > withInitialNow (Timestamp 10000000) $ testScenarioOnEmulator Testname $ scenario $ tests

withInitialLevel :: Natural -> Scenario PureM -> Scenario PureM

Similar to withInitialNow but for the initial level

collectLogs :: LogsInfo -> MorleyLogs

Collect logs produced by all contracts into the single list

logsForAddress :: (Each s s ScenarioLogs ScenarioLogs, ToAddress addr) => addr -> s -> [MorleyLogs]

Get logs for a given address from LogsInfo

Cleveland actions

type MonadCleveland caps m = (m ~ ReaderT caps (ClevelandBaseMonad caps), HasClevelandCaps caps)

Constraint for a monad in which we can do cleveland actions.

class Functor m => MonadOps m

Typeclass for monads where operations-related actions can occur.

This is implemented for MonadCleveland and batch context.

Has Functor as a superclass constraint for convenience, all the related methods require it.

Minimal complete definition

withOpsCap

Instances

MonadOps ClevelandOpsBatch

Defined in Test.Cleveland.Internal.Actions

Methods

withOpsCap :: (ClevelandOpsImpl ClevelandOpsBatch -> ClevelandOpsBatch a) -> ClevelandOpsBatch a

(HasClevelandCaps caps, ClevelandBaseMonad caps ~ m) => MonadOps (ReaderT caps m)

Defined in Test.Cleveland.Internal.Actions

Methods

withOpsCap :: (ClevelandOpsImpl (ReaderT caps m) -> ReaderT caps m a) -> ReaderT caps m a

type MonadEmulated caps m = (MonadCleveland caps m, HasEmulatedCaps caps)

Constraint for a monad in which we can do cleveland actions that can't be run on a real network. It requires the EmulatedImpl capability.

type ClevelandT m = ReaderT (ClevelandCaps m) m

Monad transformer that adds only the ClevelandCaps capabilities.

type EmulatedT m = ReaderT (EmulatedCaps m) m

Monad transformer that adds both ClevelandCaps and EmulatedCaps capabilities.

withSender :: MonadCleveland caps m => Address -> m a -> m a

Update the current sender on whose behalf transfers and originations are invoked.

withMoneybag :: MonadCleveland caps m => Address -> m a -> m a

Update the current moneybag that transfers money on the newly created addresses. For the rare occasions when this is necessary.

runIO :: (HasCallStack, MonadCleveland caps m) => IO res -> m res

Runs an IO action.

resolveAddress :: (HasCallStack, MonadCleveland caps m) => AliasHint -> m Address

Get the address of the implicit account / contract associated with the given alias hint.

refillable :: MonadCleveland caps m => m Address -> m Address

Simple combinator that marks address as "refillable".

If a refillable address lacks funds for the next operation, some funds will automatically be transferred to it.

newAddress :: (HasCallStack, MonadCleveland caps m) => SpecificOrDefaultAliasHint -> m Address

If the given alias is already associated with an existing address, that address will be reused and returned. Otherwise, generate a new secret key and record it with given alias.

If the account has too low of a balance, a small amount of XTZ will be transferred to it.

Notes:

• By default, the XTZ is transferred from the account associated with the moneybag alias. This can be overriden with the --cleveland-moneybag-alias command line option, the TASTY_CLEVELAND_MONEYBAG_ALIAS env var, or withMoneybag.
• Beware that if an "alias prefix" is set, it'll be prepended to the given alias hint. An "alias prefix" can be set using the --cleveland-alias-prefix command line option, the TASTY_CLEVELAND_ALIAS_PREFIX env var, or with setAliasPrefix. > do > addr1 <- newAddress "alias" > addr2 <- resolveAddress $ mkAlias "prefix.alias" > addr1 @== addr2

newFreshAddress :: (HasCallStack, MonadCleveland caps m) => SpecificOrDefaultAliasHint -> m Address

Generate a new secret key and record it with given alias. If the alias is already known, the key will be overwritten. The address is guaranteed to be fresh, i. e. no operations on it have been made.

Notes:

• Beware that if an "alias prefix" is set, it'll be prepended to the given alias. An "alias prefix" can be set using the --cleveland-alias-prefix command line option, the TASTY_CLEVELAND_ALIAS_PREFIX env var, or with setAliasPrefix. > do > addr1 <- newFreshAddress "alias" > addr2 <- resolveAddress $ mkAlias "prefix.alias" > addr1 @== addr2

enumAliasHints :: forall n n'. (SingIPeano n, IsoNatPeano n n') => AliasHint -> SizedList n SpecificOrDefaultAliasHint

Create a list of similarly named SpecificAliasHints.

For example,

>>> enumAliasHints @2 "operator" `isEquivalentTo` "operator-0" :< "operator-1" :< Nil
True

signBytes :: (HasCallStack, MonadCleveland caps m) => ByteString -> Address -> m Signature

Get the signature of the preapplied operation.

signBinary :: (HasCallStack, BytesLike bs, MonadCleveland caps m) => bs -> Address -> m (TSignature bs)

Type-safer version of signBytes.

originate :: forall cp st vd m. (HasCallStack, MonadOps m) => OriginateData cp st vd -> m (ContractHandle cp st vd)

Lorentz version for origination.

By default, the sender is the account associated with the moneybag alias. This can be overriden with the --cleveland-moneybag-alias command line option, the TASTY_CLEVELAND_MONEYBAG_ALIAS env var, or withSender.

originateSimple :: forall cp st vd m. (HasCallStack, MonadOps m) => AliasHint -> st -> Contract cp st vd -> m (ContractHandle cp st vd)

A simplified version of the originate command. The contract will have 0 balance.

originateUntyped :: (HasCallStack, MonadOps m) => UntypedOriginateData -> m Address

Originate a new raw Michelson contract with given data.

originateUntypedSimple :: (HasCallStack, MonadOps m) => AliasHint -> Value -> Contract -> m Address

A simplified version of the originateUntyped command. The contract will have 0 balance.

originateTypedSimple :: forall cp st vd m. (HasCallStack, MonadOps m, NiceParameter cp, NiceStorage st, NiceViewsDescriptor vd) => AliasHint -> st -> Contract (ToT cp) (ToT st) -> m (ContractHandle cp st vd)

Like originateUntypedSimple, but accepts typed contract and initial storage as a Haskell value.

originateLarge :: forall param st vd m caps. (HasCallStack, MonadCleveland caps m) => OriginateData param st vd -> m (ContractHandle param st vd)

Lorentz version for large origination.

originateLargeSimple :: forall param st vd m caps. (HasCallStack, MonadCleveland caps m) => AliasHint -> st -> Contract param st vd -> m (ContractHandle param st vd)

A simplified version of the originateLarge command. The contract will have 0 balance.

originateLargeUntyped :: (HasCallStack, MonadCleveland caps m) => UntypedOriginateData -> m Address

Originate a new Michelson contract that doesn't fit into the origination size limit, by executing multiple operation steps.

This operation cannot be batched (it simply may not fit).

originateLargeUntypedSimple :: (HasCallStack, MonadCleveland caps m) => AliasHint -> Value -> Contract -> m Address

A simplified version of the originateLargeUntyped command. The contract will have 0 balance.

transfer :: (HasCallStack, MonadOps m) => TransferData -> m ()

Base method for making a transfer.

Avoid using this method in favour of transferMoney and call, unless you need the semantics of both in one operation.

transferMoney :: (HasCallStack, MonadOps m, ToAddress addr) => addr -> Mutez -> m ()

Simply transfer money to an address.

This assumes that target address is either an implicit address or has a default entrypoint with a unit argument; otherwise the call fails.

call :: forall param vd addr m epRef epArg. (HasCallStack, MonadOps m, ToTAddress param vd addr, HasEntrypointArg param epRef epArg, IsoValue epArg, Typeable epArg) => addr -> epRef -> epArg -> m ()

Call a certain entrypoint of the given contract.

By default, the sender is the account associated with the moneybag alias. This can be overriden with the --cleveland-moneybag-alias command line option, the TASTY_CLEVELAND_MONEYBAG_ALIAS env var, or withSender.

importUntypedContract :: (HasCallStack, MonadCleveland caps m) => FilePath -> m Contract

Import an untyped contract from file.

importContract :: (HasCallStack, NiceParameter param, NiceStorage st, NiceViewsDescriptor vd, DemoteViewsDescriptor vd, MonadCleveland caps m) => FilePath -> m (Contract param st vd)

Import a contract from file.

The compiler must be able to infer the types of parameter, storage and views. In case there are no views or you don't care, you can use noViews.

noViews :: forall k1 k2 contract (cp :: k1) (st :: k2). contract cp st () -> contract cp st ()

comment :: (HasCallStack, MonadCleveland caps m) => Text -> m ()

Print the given string verbatim as a comment. At the moment, this is a no-op in emulator tests.

getBalance :: (HasCallStack, MonadCleveland caps m, ToAddress addr) => addr -> m Mutez

Get the balance of the given address.

getDelegate :: (HasCallStack, MonadCleveland caps m, ToAddress addr) => addr -> m (Maybe KeyHash)

Get the delegate for the given contract. Fails on implicit contracts.

registerDelegate :: (HasCallStack, MonadCleveland caps m, ToAddress addr) => addr -> m ()

Register the given address as a valid delegate.

getMorleyLogs :: forall a caps m. MonadEmulated caps m => m a -> m (LogsInfo, a)

Returns the result of the action with the logs it produced. Logs are messages printed by the Lorentz instruction printComment.

This function can be combined either with lens-based accessors or helper functions to get more specific information about logs.

Examples:

(logsInfo, _) <- getMorleyLogs scenario
logsInfo ^.. each . logsL == [MorleyLogs ["log"], MorleyLogs ["log2"]]
logsInfo ^.. each . filterLogsByAddrL addr == [MorleyLogs ["log"]]

(logsInfo, _) <- getMorleyLogs scenario
collectLogs logsInfo == MorleyLogs ["log", "log2"]
logsForAddress logsInfo == [MorleyLogs ["log"]]

getMorleyLogs_ :: MonadEmulated caps m => m () -> m LogsInfo

Version of getMorleyLogs for actions that don't return a result.

getStorage :: forall st addr caps m. (HasCallStack, MonadCleveland caps m, ToStorageType st addr, IsoValue (AsRPC st)) => addr -> m (AsRPC st)

Retrieve a contract's storage in its "RPC representation" (i.e., all its big_maps will be replaced by big_map IDs).

If the storage is of a user-defined type, then deriveRPC / deriveManyRPC should be used to create an RPC representation of the storage type.

data MyStorage = MyStorage { field1 :: Natural, field2 :: BigMap Integer MText }
deriveRPC "MyStorage"

getFullStorage :: forall st addr caps m. (HasCallStack, MonadEmulated caps m, ToStorageType st addr) => addr -> m st

Retrieve a contract's full storage, including the contents of its big_maps.

This function can only be used in emulator-only tests.

getSomeStorage :: forall addr caps m. (HasCallStack, MonadCleveland caps m, ToAddress addr) => addr -> m SomeAnnotatedValue

Similar to getStorage, but doesn't require knowing the storage type in advance.

Use the optics in AnnotatedValue to read data from the storage.

getAllBigMapValues :: forall k v caps m. (HasCallStack, MonadCleveland caps m, NiceComparable k, NiceUnpackedValue v) => BigMapId k v -> m [v]

Like getAllBigMapValuesMaybe, but fails the tests instead of returning Nothing.

getAllBigMapValuesMaybe :: forall k v caps m. (HasCallStack, MonadCleveland caps m, NiceComparable k, NiceUnpackedValue v) => BigMapId k v -> m (Maybe [v])

Retrieve all big_map values, given a big_map ID. Returns Nothing when the big_map ID does not exist.

getBigMapSize :: forall k v caps m. (HasCallStack, MonadCleveland caps m, NiceComparable k, NiceUnpackedValue v) => BigMapId k v -> m Natural

Like getBigMapSizeMaybe, but fails the tests instead of returning Nothing.

getBigMapSizeMaybe :: forall k v caps m. (HasCallStack, MonadCleveland caps m, NiceComparable k, NiceUnpackedValue v) => BigMapId k v -> m (Maybe Natural)

Retrieve a big_map size, given a big_map ID. Returns Nothing when the big_map ID does not exist.

O(n), because it's implemented with getBigMapValues.

getBigMapValueMaybe :: forall k v caps m. (HasCallStack, MonadCleveland caps m, NiceComparable k, NicePackedValue k, NiceUnpackedValue v) => BigMapId k v -> k -> m (Maybe v)

Retrieve a big_map value, given a big_map ID and a key. Returns Nothing when the big_map ID does not exist, or it exists but does not contain the given key.

getBigMapValue :: forall k v caps m. (HasCallStack, MonadCleveland caps m, NiceComparable k, NicePackedValue k, NiceUnpackedValue v, Buildable k) => BigMapId k v -> k -> m v

Like getBigMapValueMaybe, but fails the tests instead of returning Nothing.

getPublicKey :: (HasCallStack, MonadCleveland caps m) => Address -> m PublicKey

Get the public key associated with given address. Fail if given address is not an implicit account.

getChainId :: (HasCallStack, MonadCleveland caps m) => m ChainId

Get the chain's ChainId.

advanceTime :: forall unit caps m. (HasCallStack, MonadCleveland caps m, KnownDivRat unit Second) => Time unit -> m ()

Advance at least the given amount of time, or until a new block is baked, whichever happens last.

On a real network, this is implemented using threadDelay, so it's advisable to use small amounts of time only.

advanceLevel :: forall caps m. (HasCallStack, MonadCleveland caps m) => Natural -> m ()

Wait till the provided number of levels is past.

advanceToLevel :: forall caps m. (HasCallStack, MonadCleveland caps m) => Natural -> m ()

Wait till the provided level is reached.

getNow :: (HasCallStack, MonadCleveland caps m) => m Timestamp

Get the timestamp observed by the last block to be baked.

getLevel :: (HasCallStack, MonadCleveland caps m) => m Natural

Get the current level observed by the last block to be baked.

getApproximateBlockInterval :: (HasCallStack, MonadCleveland caps m) => m (Time Second)

Get approximate block interval in seconds. Note, that this value is minimal bound and real intervals can be larger, see http://tezos.gitlab.io/active/consensus.html#minimal-block-delay-function for more information about block delays.

data RunCode cp st vd

The data needed to call the /run_code RPC endpoint.

Constructors

RunCode

Fields

• rcContract :: Contract cp st vd
• rcStorage :: MaybeRPC st
• rcParameter :: MaybeRPC cp
• rcAmount :: Mutez

  The value that will be returned by the AMOUNT instruction.

• rcBalance :: Mutez

  The balance that will be returned by the BALANCE instruction.

• rcSource :: Maybe Address

  The value that will be returned by the SOURCE instruction.

data MaybeRPC v where

Constructors

NotRPC :: forall v. IsoValue v => v -> MaybeRPC v

IsRPC :: forall v. (SingI (ToT v), IsoValue (AsRPC v), HasRPCRepr v) => AsRPC v -> MaybeRPC v

Instances

HasNoOp (ToT v) => ToExpression (MaybeRPC v)

Defined in Morley.AsRPC

Methods

toExpression :: MaybeRPC v -> Expression

runCode :: (HasCallStack, MonadCleveland caps m, HasRPCRepr st, IsoValue (AsRPC st)) => RunCode cp st vd -> m (AsRPC st)

Execute a contract's code without originating it. The chain's state will not be modified.

Notes:

• If the contract's code emits operations, they will not be executed.
• The sender's account won't be debited.
• When running an _originated_ contract, the BALANCE instruction returns the sum of the contract's balance before the transfer operation + the amount of tz being transferred. In other words, this invariant holds: BALANCE >= AMOUNT. However, since runCode allows overriding the BALANCE instruction, then this invariant no longer holds. It's possible that BALANCE < AMOUNT.

branchout :: forall caps m. MonadEmulated caps m => [(Text, m ())] -> m ()

Execute multiple testing scenarios independently.

• Actions performed before branchout will be observed by all branches.
• Actions performed in branches will _not_ be observed by any actions performed after branchout.
• Actions performed in one branch will _not_ be observed by another branch.
• The test succeeds IFF all branches succeed.
• If any branch fails, the test ends immediately and the remaining branches won't be executed.

The following property holds:

pre >> branchout [a, b, c] = branchout [pre >> a, pre >> b, pre >> c]

The list of branches must be non-empty.

offshoot :: forall caps m. MonadEmulated caps m => Text -> m () -> m ()

Execute one or more actions and roll them back afterwards. Actions performed in offshoot will _not_ be observed by any actions performed after offshoot.

Similar to branchout, but accepts one single branch.

setVotingPowers :: MonadEmulated caps m => VotingPowers -> m ()

Updates voting power accessible via VOTING_POWER and similar instructions.

whenEmulation :: MonadCleveland caps m => (forall caps1 m1. (EqBaseMonad caps caps1, MonadEmulated caps1 m1) => m1 ()) -> m ()

Perform an action if we are currently in emulation mode. See also ifEmulation note on constraints.

whenNetwork :: MonadCleveland caps m => (forall caps1 m1. (EqBaseMonad caps caps1, MonadCleveland caps1 m1) => m1 ()) -> m ()

Perform an action if we are currently in network mode. See also ifEmulation note on constraints.

ifEmulation :: forall a caps m. MonadCleveland caps m => (forall caps1 m1. (EqBaseMonad caps caps1, MonadEmulated caps1 m1) => m1 a) -> (forall caps1 m1. (EqBaseMonad caps caps1, MonadCleveland caps1 m1) => m1 a) -> m a

Perform one action if we are currently in emulation mode, another otherwise

Functions passed as the first two arguments are universally quantified over the outer monad, so if additional constraints are required beyond MonadEmulated or MonadCleveland, those constraints have to go on the base monad, e.g.

someFunction :: (MonadCleveland caps m, MonadFail (ClevelandBaseMonad caps)) => m ()
someFunction = whenEmulation do
  Just x <- pure (Just 1 :: Maybe Int) -- this would error without MonadFail
  runIO $ print x

inBatch :: (HasCallStack, MonadCleveland caps m) => ClevelandOpsBatch a -> m a

Run operations in a batch. Best used with the ApplicativeDo GHC extension.

Example:

contract <- inBatch $ do
  contract <- originate ...
  for_ [1..3] i ->
    transfer ...
  return contract

Batched operations should be applied to chain faster, but note that batches have their own limits. For instance, at the moment of writing, the gas limit on a batch is 10x of gas limit applied to a single operation.

A context of a batch is only Applicative, not Monad. This means that:

• Return values of one function cannot be passed to another function in the same batch, it can only be returned;
• Sometimes the compiler does not recognize that only Applicative context is required, in case of any issues with that - follow the error messages.

Primitives re-exports

data EntrypointRef (mname :: Maybe Symbol) where

Constructors

CallDefault :: EntrypointRef ('Nothing :: Maybe Symbol)

Call :: forall (name :: Symbol). NiceEntrypointName name => EntrypointRef ('Just name)

Instances

(GetEntrypointArgCustom cp mname ~ arg, ParameterDeclaresEntrypoints cp) => HasEntrypointArg (cp :: Type) (EntrypointRef mname) arg

Defined in Lorentz.Entrypoints.Core

Methods

useHasEntrypointArg :: EntrypointRef mname -> (Dict (ParameterScope (ToT arg)), EpName)

data VotingPowers

Instances

Eq VotingPowers

Defined in Morley.Michelson.Runtime.GState

Methods

(==) :: VotingPowers -> VotingPowers -> Bool

(/=) :: VotingPowers -> VotingPowers -> Bool

Show VotingPowers

Defined in Morley.Michelson.Runtime.GState

Methods

showsPrec :: Int -> VotingPowers -> ShowS

show :: VotingPowers -> String

showList :: [VotingPowers] -> ShowS

ToJSON VotingPowers

Defined in Morley.Michelson.Runtime.GState

Methods

toJSON :: VotingPowers -> Value

toEncoding :: VotingPowers -> Encoding

toJSONList :: [VotingPowers] -> Value

toEncodingList :: [VotingPowers] -> Encoding

FromJSON VotingPowers

Defined in Morley.Michelson.Runtime.GState

Methods

parseJSON :: Value -> Parser VotingPowers

parseJSONList :: Value -> Parser [VotingPowers]

mkVotingPowers :: [(KeyHash, Natural)] -> VotingPowers

mkVotingPowersFromMap :: Map KeyHash Natural -> VotingPowers

Assertions

failure :: forall a caps m. (HasCallStack, MonadCleveland caps m) => Builder -> m a

Fails the test with the given error message.

assert :: (HasCallStack, MonadCleveland caps m) => Bool -> Builder -> m ()

Fails the test with the given error message if the given condition is false.

(@==) infix 1

Arguments

:: (HasCallStack, MonadCleveland caps m, Eq a, Buildable a)

=> a

The actual value.

-> a

The expected value.

-> m ()

x @== expected fails the test if x is not equal to expected.

(@/=) :: (HasCallStack, MonadCleveland caps m, Eq a, Buildable a) => a -> a -> m () infix 1

Fails the test if the two given values are equal.

(@@==) infix 1

Arguments

:: (HasCallStack, MonadCleveland caps m, Eq a, Buildable a)

=> m a

The actual value.

-> a

The expected value.

-> m ()

Monadic version of @==.

getBalance addr @@== 10

(@@/=) :: (HasCallStack, MonadCleveland caps m, Eq a, Buildable a) => m a -> a -> m () infix 1

Monadic version of @/=.

getBalance addr @@/= 10

checkCompares :: forall a b caps m. (HasCallStack, MonadCleveland caps m, Buildable a, Buildable b) => a -> (a -> b -> Bool) -> b -> m ()

Fails the test if the comparison operator fails when applied to the given arguments. Prints an error message with both arguments.

Example:

checkCompares 2 (>) 1

checkComparesWith :: forall a b caps m. (HasCallStack, MonadCleveland caps m) => (a -> Text) -> a -> (a -> b -> Bool) -> (b -> Text) -> b -> m ()

Like checkCompares, but with an explicit show function. This function does not have any constraint on the type parameters a and b.

For example, to print with pretty:

checkComparesWith pretty a (<) pretty b

evalJust :: (HasCallStack, MonadCleveland caps m) => Builder -> Maybe a -> m a

Fails the test if the Maybe is Nothing, otherwise returns the value in the Just.

evalRight :: (HasCallStack, MonadCleveland caps m) => (a -> Builder) -> Either a b -> m b

Fails the test if the Either is Left, otherwise returns the value in the Right.

newtype Showing a

Derive a Buildable instance for a type using show.

Constructors

Showing a

Instances

Eq a => Eq (Showing a)

Defined in Test.Cleveland.Util

Methods

(==) :: Showing a -> Showing a -> Bool

(/=) :: Showing a -> Showing a -> Bool

Show a => Show (Showing a)

Defined in Test.Cleveland.Util

Methods

showsPrec :: Int -> Showing a -> ShowS

show :: Showing a -> String

showList :: [Showing a] -> ShowS

Show a => Buildable (Showing a)

Defined in Test.Cleveland.Util

Methods

build :: Showing a -> Builder

Exception handling

attempt :: forall e caps m a. (HasCallStack, MonadCleveland caps m, Exception e) => m a -> m (Either e a)

Attempt to run an action and return its result or, if interpretation fails, an error.

catchTransferFailure :: (HasCallStack, MonadCleveland caps m) => m a -> m TransferFailure

Asserts that a transfer should fail, and returns the exception.

checkTransferFailure :: (HasCallStack, MonadCleveland caps m) => TransferFailure -> TransferFailurePredicate -> m ()

Check whether a given predicate holds for a given TransferFailure.

expectTransferFailure :: (HasCallStack, MonadCleveland caps m) => TransferFailurePredicate -> m a -> m ()

Asserts that a transfer should fail, and runs some TransferFailurePredicates over the exception.

expectTransferFailure (failedWith (constant @MText "NOT_ADMIN")) $
  call contractAddr (Call @"Ep") arg

call contractAddr (Call @"Ep") arg & expectTransferFailure
  ( failedWith (customError #tag 3) &&
    addressIs contractAddr
  )

expectFailedWith :: forall err a caps m. (HasCallStack, MonadCleveland caps m, NiceConstant err) => err -> m a -> m ()

Asserts that interpretation of a contract ended with FAILWITH, returning the given constant value.

expectError :: forall err a caps m. (HasCallStack, MonadCleveland caps m, IsError err) => err -> m a -> m ()

Asserts that interpretation of a contract ended with FAILWITH, returning the given lorentz error.

expectCustomError :: forall arg a tag caps m. (HasCallStack, MonadCleveland caps m, IsError (CustomError tag), MustHaveErrorArg tag (MText, arg)) => Label tag -> arg -> m a -> m ()

Asserts that interpretation of a contract ended with FAILWITH, returning the given custom lorentz error.

expectCustomError_ :: (HasCallStack, MonadCleveland caps m, IsError (CustomError tag), MustHaveErrorArg tag (MText, ())) => Label tag -> m a -> m ()

Version of expectCustomError for error with unit argument.

expectCustomErrorNoArg :: (HasCallStack, MonadCleveland caps m, IsError (CustomError tag), MustHaveErrorArg tag MText) => Label tag -> m a -> m ()

Version of expectCustomError specialized for expecting NoErrorArgs.

expectNumericError :: forall err a caps m. (HasCallStack, MonadCleveland caps m, IsError err) => ErrorTagMap -> err -> m a -> m ()

Asserts that interpretation of a contract ended with FAILWITH, returning the given lorentz numeric error.

clarifyErrors :: forall caps m a. MonadCleveland caps m => Builder -> m a -> m a

Prefix scenario-custom error messages (i.e. CustomTestError either from pure or non-pure implementation), potentially thrown from the given code block.

The prefix will be put at a separate line before the main text, if text is multiline, otherwise it will be separated from the main text with : .

This affects errors produced by functions like failure, assert, @==, etc. Errors related to events in the chain will not be touched.

Example:

for [1..10] \i -> clarifyErrors ("For i=" +| i |+ "") $
  askContract i @@== i * 2

Exception predicates

data TransferFailurePredicate

A predicate that checks whether a transfer operation failed for the expected reason.

Predicates can be combined using the && and || operators.

Instances

Boolean TransferFailurePredicate

Defined in Test.Cleveland.Internal.Actions

Methods

(&&) :: TransferFailurePredicate -> TransferFailurePredicate -> TransferFailurePredicate

(||) :: TransferFailurePredicate -> TransferFailurePredicate -> TransferFailurePredicate

shiftOverflow :: TransferFailurePredicate

Asserts that interpretation of a contract failed due to an overflow error.

emptyTransaction :: TransferFailurePredicate

Asserts that an action failed due to an attempt to transfer 0tz towards a simple address.

badParameter :: TransferFailurePredicate

Asserts that an action failed due to an attempt to call a contract with an invalid parameter.

gasExhaustion :: TransferFailurePredicate

Asserts that interpretation of a contract failed due to gas exhaustion.

failedWith :: SomeConstant -> TransferFailurePredicate

Asserts that interpretation of a contract ended with FAILWITH, throwing the given error.

This function should be used together with one of the "FAILWITH constructors" (e.g. constant, customError).

addressIs

Arguments

:: ToAddress addr

=> addr

The expected address.

-> TransferFailurePredicate

Asserts that the error occurred while interpreting the contract with the given address.

FAILWITH errors

Convert the many error formats available in morley and lorentz to SomeConstant.

constant :: forall err. NiceConstant err => err -> SomeConstant

A constant michelson value that a contract threw with FAILWITH.

lerror :: forall err. IsError err => err -> SomeConstant

A lorentz error.

customError :: forall arg tag. (IsError (CustomError tag), MustHaveErrorArg tag (MText, arg)) => Label tag -> arg -> SomeConstant

A custom lorentz error.

customError_ :: (IsError (CustomError tag), MustHaveErrorArg tag (MText, ())) => Label tag -> SomeConstant

A custom lorentz error with a unit argument.

customErrorNoArg :: (IsError (CustomError tag), MustHaveErrorArg tag MText) => Label tag -> SomeConstant

A custom lorentz error with no argument.

numericError :: forall err. IsError err => ErrorTagMap -> err -> SomeConstant

A lorentz numeric error.

Helpers

auto :: SpecificOrDefaultAliasHint

Helper to use automatically determined unique alias.

pattern DefEpName :: EpName

ep :: HasCallStack => Text -> EpName

A short partial constructor for EpName. It is supposed to be applied to string constants, so programmer is responsible for validity. And this code is for tests anyway, so each failure is a programmer mistake.

It is intentionally here and not in some deeper module because the name is really short and more suitable for writing scenarios.

(?-) :: Text -> a -> (Text, a) infixr 0

Make a tuple with name without extra syntactic noise.

Integration with hedgehog

testScenarioProps :: (HasCallStack, MonadIO m, MonadTest m) => Scenario PureM -> m ()

Run an Scenario via the Morley.Michelson.Runtime emulator, inside an hedgehog property.

Config (reexports)

data TezosClientEnv

Constructors

TezosClientEnv

Fields

• tceAliasPrefix :: Maybe Text
• tceEndpointUrl :: BaseUrl
• tceTezosClientPath :: FilePath
• tceMbTezosClientDataDir :: Maybe FilePath

type MorleyClientEnv = MorleyClientEnv' MorleyClientM

data MorleyClientEnv' (m :: Type -> Type)

Constructors

MorleyClientEnv

Fields

• mceTezosClient :: TezosClientEnv
• mceLogAction :: ClientLogAction m
• mceSecretKey :: Maybe SecretKey
• mceClientEnv :: ClientEnv

Instances

MonadReader MorleyClientEnv MorleyClientM

Defined in Morley.Client.Full

Methods

ask :: MorleyClientM MorleyClientEnv

local :: (MorleyClientEnv -> MorleyClientEnv) -> MorleyClientM a -> MorleyClientM a

reader :: (MorleyClientEnv -> a) -> MorleyClientM a

HasLog MorleyClientEnv Message MorleyClientM

Defined in Morley.Client.Full

Methods

getLogAction :: MorleyClientEnv -> LogAction MorleyClientM Message

setLogAction :: LogAction MorleyClientM Message -> MorleyClientEnv -> MorleyClientEnv

overLogAction :: (LogAction MorleyClientM Message -> LogAction MorleyClientM Message) -> MorleyClientEnv -> MorleyClientEnv

logActionL :: Lens' MorleyClientEnv (LogAction MorleyClientM Message)

HasTezosClientEnv (MorleyClientEnv' m)

Defined in Morley.Client.Env

Methods

tezosClientEnvL :: Lens' (MorleyClientEnv' m) TezosClientEnv

data NetworkEnv

Constructors

NetworkEnv

Fields

• neMorleyClientEnv :: MorleyClientEnv
• neSecretKey :: Maybe SecretKey
• neMoneybagAlias :: Alias

data MorleyLogs

Instances

Eq MorleyLogs

Defined in Morley.Michelson.Interpret

Methods

(==) :: MorleyLogs -> MorleyLogs -> Bool

(/=) :: MorleyLogs -> MorleyLogs -> Bool

Show MorleyLogs

Defined in Morley.Michelson.Interpret

Methods

showsPrec :: Int -> MorleyLogs -> ShowS

show :: MorleyLogs -> String

showList :: [MorleyLogs] -> ShowS

Generic MorleyLogs

Defined in Morley.Michelson.Interpret

Associated Types

type Rep MorleyLogs :: Type -> Type

Methods

from :: MorleyLogs -> Rep MorleyLogs x

to :: Rep MorleyLogs x -> MorleyLogs

Semigroup MorleyLogs

Defined in Morley.Michelson.Interpret

Methods

(<>) :: MorleyLogs -> MorleyLogs -> MorleyLogs

sconcat :: NonEmpty MorleyLogs -> MorleyLogs

stimes :: Integral b => b -> MorleyLogs -> MorleyLogs

Monoid MorleyLogs

Defined in Morley.Michelson.Interpret

Methods

mempty :: MorleyLogs

mappend :: MorleyLogs -> MorleyLogs -> MorleyLogs

mconcat :: [MorleyLogs] -> MorleyLogs

NFData MorleyLogs

Defined in Morley.Michelson.Interpret

Methods

rnf :: MorleyLogs -> ()

Buildable MorleyLogs

Defined in Morley.Michelson.Interpret

Methods

build :: MorleyLogs -> Builder

type Rep MorleyLogs

Defined in Morley.Michelson.Interpret

type Rep MorleyLogs = D1 ('MetaData "MorleyLogs" "Morley.Michelson.Interpret" "morley-1.16.4-inplace" 'True) (C1 ('MetaCons "MorleyLogs" 'PrefixI 'True) (S1 ('MetaSel ('Just "unMorleyLogs") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 [Text])))

Config utilities

mkMorleyOnlyRpcEnvNetwork

Arguments

:: NetworkEnv

-> [SecretKey]

Extra secrets that should be known

-> MorleyOnlyRpcEnv

Construct MorleyOnlyRpcEnv from NetworkEnv.

AsRPC

class TAsRPC (ToT t) ~ ToT (AsRPC t) => HasRPCRepr t

Associated Types

type AsRPC t

Instances

HasRPCRepr Bool

Defined in Morley.AsRPC

Associated Types

type AsRPC Bool

HasRPCRepr Integer

Defined in Morley.AsRPC

Associated Types

type AsRPC Integer

HasRPCRepr Natural

Defined in Morley.AsRPC

Associated Types

type AsRPC Natural

HasRPCRepr ()

Defined in Morley.AsRPC

Associated Types

type AsRPC ()

HasRPCRepr ByteString

Defined in Morley.AsRPC

Associated Types

type AsRPC ByteString

HasRPCRepr MText

Defined in Morley.AsRPC

Associated Types

type AsRPC MText

HasRPCRepr KeyHash

Defined in Morley.AsRPC

Associated Types

type AsRPC KeyHash

HasRPCRepr PublicKey

Defined in Morley.AsRPC

Associated Types

type AsRPC PublicKey

HasRPCRepr Signature

Defined in Morley.AsRPC

Associated Types

type AsRPC Signature

HasRPCRepr Bls12381Fr

Defined in Morley.AsRPC

Associated Types

type AsRPC Bls12381Fr

HasRPCRepr Bls12381G1

Defined in Morley.AsRPC

Associated Types

type AsRPC Bls12381G1

HasRPCRepr Bls12381G2

Defined in Morley.AsRPC

Associated Types

type AsRPC Bls12381G2

HasRPCRepr Chest

Defined in Morley.AsRPC

Associated Types

type AsRPC Chest

HasRPCRepr ChestKey

Defined in Morley.AsRPC

Associated Types

type AsRPC ChestKey

HasRPCRepr Address

Defined in Morley.AsRPC

Associated Types

type AsRPC Address

HasRPCRepr ChainId

Defined in Morley.AsRPC

Associated Types

type AsRPC ChainId

HasRPCRepr Mutez

Defined in Morley.AsRPC

Associated Types

type AsRPC Mutez

HasRPCRepr Timestamp

Defined in Morley.AsRPC

Associated Types

type AsRPC Timestamp

HasRPCRepr Empty

Defined in Lorentz.Empty

Associated Types

type AsRPC Empty

HasRPCRepr Never

Defined in Lorentz.Value

Associated Types

type AsRPC Never

HasRPCRepr OpenChest

Defined in Lorentz.Value

Associated Types

type AsRPC OpenChest

HasRPCRepr Operation

Defined in Morley.AsRPC

Associated Types

type AsRPC Operation

HasRPCRepr EpAddress

Defined in Morley.AsRPC

Associated Types

type AsRPC EpAddress

HasRPCRepr a => HasRPCRepr [a]

Defined in Morley.AsRPC

Associated Types

type AsRPC [a]

HasRPCRepr a => HasRPCRepr (Maybe a)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Maybe a)

HasRPCRepr (Set a)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Set a)

HasRPCRepr a => HasRPCRepr (Identity a)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Identity a)

HasRPCRepr (FutureContract p)

Defined in Lorentz.Address

Associated Types

type AsRPC (FutureContract p)

HasRPCRepr (ChestT a)

Defined in Lorentz.Bytes

Associated Types

type AsRPC (ChestT a)

HasRPCRepr a => HasRPCRepr (OpenChestT a)

Defined in Lorentz.Bytes

Associated Types

type AsRPC (OpenChestT a)

HasRPCRepr (Packed a)

Defined in Lorentz.Bytes

Associated Types

type AsRPC (Packed a)

HasRPCRepr (TSignature a)

Defined in Lorentz.Bytes

Associated Types

type AsRPC (TSignature a)

HasRPCRepr a => HasRPCRepr (ShouldHaveEntrypoints a)

Defined in Lorentz.Entrypoints.Helpers

Associated Types

type AsRPC (ShouldHaveEntrypoints a)

HasRPCRepr (UParam entries)

Defined in Lorentz.UParam

Associated Types

type AsRPC (UParam entries)

HasRPCRepr (Value t)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Value t)

HasRPCRepr (ContractRef arg)

Defined in Morley.AsRPC

Associated Types

type AsRPC (ContractRef arg)

(HasRPCRepr l, HasRPCRepr r) => HasRPCRepr (Either l r)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Either l r)

(HasRPCRepr a, HasRPCRepr b) => HasRPCRepr (a, b)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b)

HasRPCRepr v => HasRPCRepr (Map k v)

Defined in Morley.AsRPC

Associated Types

type AsRPC (Map k v)

HasRPCRepr (TAddress cp vd)

Defined in Lorentz.Address

Associated Types

type AsRPC (TAddress cp vd)

HasRPCRepr (Hash alg a)

Defined in Lorentz.Bytes

Associated Types

type AsRPC (Hash alg a)

HasRPCRepr cp => HasRPCRepr (ParameterWrapper deriv cp)

Defined in Lorentz.Entrypoints.Manual

Associated Types

type AsRPC (ParameterWrapper deriv cp)

HasRPCRepr a => HasRPCRepr (View_ a r)

Defined in Lorentz.Macro

Associated Types

type AsRPC (View_ a r)

HasRPCRepr a => HasRPCRepr (Void_ a r)

Defined in Lorentz.Macro

Associated Types

type AsRPC (Void_ a r)

HasRPCRepr (BigMap k v)

Defined in Morley.AsRPC

Associated Types

type AsRPC (BigMap k v)

Each '[HasRPCRepr] '[a, b, c] => HasRPCRepr (a, b, c)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c)

HasRPCRepr a => HasRPCRepr (NamedF Maybe a name)

Defined in Morley.AsRPC

Associated Types

type AsRPC (NamedF Maybe a name)

HasRPCRepr a => HasRPCRepr (NamedF Identity a name)

Defined in Morley.AsRPC

Associated Types

type AsRPC (NamedF Identity a name)

Each '[HasRPCRepr] '[a, b, c, d] => HasRPCRepr (a, b, c, d)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d)

Each '[HasRPCRepr] '[a, b, c, d, e] => HasRPCRepr (a, b, c, d, e)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d, e)

Each '[HasRPCRepr] '[a, b, c, d, e, f] => HasRPCRepr (a, b, c, d, e, f)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d, e, f)

Each '[HasRPCRepr] '[a, b, c, d, e, f, g] => HasRPCRepr (a, b, c, d, e, f, g)

Defined in Morley.AsRPC

Associated Types

type AsRPC (a, b, c, d, e, f, g)

deriveRPC :: String -> Q [Dec]

deriveRPCWithStrategy :: String -> GenericStrategy -> Q [Dec]

deriveManyRPC :: String -> [String] -> Q [Dec]

deriveManyRPCWithStrategy :: String -> [String] -> GenericStrategy -> Q [Dec]

Utilities

mapEach :: (Each s t a b, Applicative m) => (a -> m b) -> s -> m t

Version of mapM generalized with each.

Example:

(addr1, addr2, addr3) <- mapEach newAddress ("test1", "test2", "test3")

This is more type-safe than simple mapM since lists do not remember their length in types.

forEach :: (Each s t a b, Applicative m) => s -> (a -> m b) -> m t

Version of mapEach with arguments flipped.