Test.Cleveland.Michelson

Module containing some utilities for testing Michelson contracts using Haskell testing frameworks. It's Morley testing EDSL. We focus on tasty and hedgehog because that's what we mostly use in our tests, but we also provide helpers for hspec, and defining helpers for other libraries (e. g. QuickCheck) shouldn't be hard. We don't provide helpers for other libraries to have less dependencies.

Importing a contract

specWithContract :: (Each '[SingI] [cp, st], HasCallStack) => FilePath -> (Contract cp st -> Spec) -> Spec

Deprecated: Use testTreesWithContract &c. instead

Import contract and use it in the spec. Both versions of contract are passed to the callback function (untyped and typed).

If contract's import fails, a spec with single failing expectation will be generated (so tests will likely run unexceptionally, but a failing result will notify about problem).

specWithTypedContract :: (Each '[SingI] [cp, st], HasCallStack) => FilePath -> (Contract cp st -> Spec) -> Spec

Deprecated: Use testTreesWithContract &c. instead

A version of specWithContract which passes only the typed representation of the contract.

specWithUntypedContract :: FilePath -> (Contract -> Spec) -> Spec

Deprecated: Use testTreesWithContract &c. instead

testTreesWithContract :: (Each '[SingI] [cp, st], HasCallStack) => FilePath -> (Contract cp st -> IO [TestTree]) -> IO [TestTree]

Import contract and use to create test trees. Both versions of contract are passed to the callback function (untyped and typed).

If contract's import fails, a tree with single failing test will be generated (so test tree will likely be generated unexceptionally, but a failing result will notify about problem).

testTreesWithUntypedContract :: HasCallStack => FilePath -> (Contract -> IO [TestTree]) -> IO [TestTree]

Like testTreesWithContract but supplies only untyped contract.

testTreesWithTypedContract :: (Each '[SingI] [cp, st], HasCallStack) => FilePath -> (Contract cp st -> IO [TestTree]) -> IO [TestTree]

Like testTreesWithContract but supplies only typed contract.

concatTestTrees :: [IO [TestTree]] -> IO [TestTree]

importContract :: forall (cp :: T) (st :: T). Each '[SingI :: T -> Constraint] '[cp, st] => FilePath -> IO (Contract cp st)

importSomeContract :: FilePath -> IO SomeContract

importUntypedContract :: FilePath -> IO Contract

Unit testing

type ContractReturn (st :: T) = (Either MichelsonFailureWithStack ([Operation], Value st), (InterpreterState, MorleyLogs))

type ContractPropValidator st prop = ContractReturn st -> prop

Type for contract execution validation.

It's a function which is supplied with contract execution output (failure or new storage with operation list).

Function returns a property which type is designated by type variable prop and might be Test.QuickCheck.Property or Expectation or anything else relevant.

contractProp :: (IsoValue param, IsoValue storage, ToT param ~ cp, ToT storage ~ st, ParameterScope cp) => Contract cp st -> ContractPropValidator st prop -> ContractEnv -> param -> storage -> prop

ContractCode's property tester against given input. Takes contract environment, initial storage and parameter, interprets contract on this input and invokes validation function.

contractPropVal :: ParameterScope cp => Contract cp st -> ContractPropValidator st prop -> ContractEnv -> Value cp -> Value st -> prop

Version of contractProp which takes Value as arguments instead of regular Haskell values.

This function assumes that contract has no explicit default entrypoints and you always have to construct parameter manually; if you need to test contract calling specific entrypoints, use integrational testing defined by Test.Cleveland.Michelson.Integrational module.

validateSuccess :: HasCallStack => ContractPropValidator st Expectation

ContractPropValidator that expects a successful termination.

validateStorageIs :: IsoValue st => st -> ContractPropValidator (ToT st) Assertion

ContractPropValidator that expects contract execution to succeed and update storage to a particular constant value.

validateMichelsonFailsWith :: forall v st. NiceConstant v => v -> ContractPropValidator st Expectation

ContractPropValidator that expects a given failure.

testContractCoversEntrypoints :: TestName -> Contract -> Map EpName Ty -> TestTree

Assert the contract contains the entrypoints given in spec (with matching types). Ignores any additional entrypoints present in the contract.

Also tests if the same holds after Michelson and Micheline roundtrips of the contract.

testContractMatchesEntrypoints :: TestName -> Contract -> Map EpName Ty -> TestTree

Assert the contract exactly matches the given entrypoints. Will report both missing and extraneous entrypoint names, and type mismatches.

Also tests if the same holds after Michelson and Micheline roundtrips of the contract.

General utilities

failedTest :: (HasCallStack, MonadTest m) => Text -> m ()

A Property that always fails with given message.

succeededTest :: MonadTest m => m ()

A Property that always succeeds.

eitherIsLeft :: (Show b, MonadTest m, HasCallStack) => Either a b -> m ()

The Property holds on `Left a`.

eitherIsRight :: (Show a, MonadTest m, HasCallStack) => Either a b -> m ()

The Property holds on `Right b`.

meanTimeUpperBoundProp :: (KnownDivRat unit Second, KnownUnitName unit, HasCallStack) => Time unit -> (a -> b) -> a -> Property

Benchmarks the given function and checks that the mean time to evaluate to weak head normal form is under the given amount of time.

This test fails if the benchmark takes longer than 30 seconds to run.

meanTimeUpperBoundPropNF :: (KnownDivRat unit Second, KnownUnitName unit, HasCallStack, NFData b) => Time unit -> (a -> b) -> a -> Property

Benchmarks the given function and checks that the mean time to evaluate to normal form is under the given amount of time.

This test aborts and fails if the benchmark takes longer than 120 seconds to run.

Re-exports

These functions from Time are re-exported here to make it convenient to call meanTimeUpperBoundProp and meanTimeUpperBoundPropNF.

mcs :: RatioNat -> Time Microsecond

Creates Microsecond from given Natural.

>>> mcs 42
42mcs

ms :: RatioNat -> Time Millisecond

Creates Millisecond from given Natural.

>>> ms 42
42ms

sec :: RatioNat -> Time Second

Creates Second from given Natural.

>>> sec 42
42s

minute :: RatioNat -> Time Minute

Creates Minute from given Natural.

>>> minute 42
42m

Autodoc testing

runDocTests :: (ContainsDoc code, HasCallStack) => [DocTest] -> code -> [TestTree]

Finalize test suites.

testDocBasic :: [DocTest]

Base properties which should comply for all documentations.

excludeDocTests :: [DocTest] -> [DocTest] -> [DocTest]

Calling excludeDocTests tests toExclude returns all test suites from tests which are not present in toExclude.

Dummy values

dummyContractEnv :: ContractEnv