Michelson.Doc.Test

Utilities for testing documentations sanity.

These tests serve to ensure that documentation generation is not broken and that user follows sane documentation structure (e.g. contract should be named, some entities require description, e.t.c).

Documentation

data DocTest

Test case for contract documentation.

Constructors

DocTest

Fields

• dtDeclLoc :: SrcLoc

  Declaration location, used to distinguish different test predicates. This is primarily used in excludeDocTest.

• dtDesc :: String

  Description of predicate, which you put to testCase.

• dtSuite :: HasCallStack => ContractDoc -> Assertion

  Test itself.

Instances

Eq DocTest

Defined in Michelson.Doc.Test

Methods

(==) :: DocTest -> DocTest -> Bool

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

Show DocTest

Defined in Michelson.Doc.Test

Methods

showsPrec :: Int -> DocTest -> ShowS

show :: DocTest -> String

showList :: [DocTest] -> ShowS

Buildable DocTest

Defined in Michelson.Doc.Test

Methods

build :: DocTest -> Builder

mkDocTest :: HasCallStack => String -> (HasCallStack => ContractDoc -> Assertion) -> DocTest

Construct DocTest.

Note: you should not declare helpers with this function rather use it directly in every test suite.

excludeDocTest :: HasCallStack => DocTest -> [DocTest] -> [DocTest]

Exclude given test suite.

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

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

runDocTests :: HasCallStack => [DocTest] -> ContractDoc -> [TestTree]

Finalize test suites.

expectDocTestFailure :: DocTest -> ContractDoc -> Assertion

Ensure that DocTest check fires on given contract. Used in tests on this module.

Test predicates

testDocBasic :: [DocTest]

Base properties which should comply for all documentations.

Individual test predicates

testContractNameAtTop :: DocTest

Check that contract documentation is wrapped with contractName.

testNoGitInfo :: DocTest

Check that contracts themselves do not set the git revision. It is supposed to be filled only in the executable.

testDocNotEmpty :: DocTest

Check that there is at least one non-grouping doc item.

If there is no such, rendered documentation will be empty which signals about most of the documentation pieces being lost.

testNoAdjacentDescriptions :: DocTest

Check that no group contains two DDescription items.

Normally such behaviour is allowed and can be exploited, but often it is not and multiple descriptions appearence under the same group signals about missing grouping wrapper (e.g. use of caseT instead of entryCase).

Utilities

forEachContractLayer :: ContractDoc -> (Maybe SomeDocItem -> DocBlock -> r) -> [r]

Apply given function to each group (created with DocGroup instruction) within a contract recursively. This function will accept grouping doc item itself (unless we are at root) and its subcontents.

forEachContractDocItem :: DocItem d => ContractDoc -> (d -> r) -> [r]

Apply given function to each doc item within a contract.