Safe Haskell	Safe-Inferred
Language	Haskell2010

Test.Cardano.Ledger.Binary.RoundTrip

Contents

Spec
Expectations
Tripping failure
Tripping definitions
Tripping functions

Description

Defines reusable abstractions for testing RoundTrip properties of CBOR instances

Synopsis

roundTripSpec ∷ ∀ t. (Show t, Eq t, Typeable t, Arbitrary t) ⇒ Trip t t → Spec
roundTripCborSpec ∷ ∀ t. (Show t, Eq t, Arbitrary t, EncCBOR t, DecCBOR t) ⇒ Spec
roundTripAnnCborSpec ∷ ∀ t. (Show t, Eq t, Arbitrary t, ToCBOR t, DecCBOR (Annotator t)) ⇒ Spec
roundTripRangeSpec ∷ ∀ t. (Show t, Eq t, Typeable t, Arbitrary t) ⇒ Trip t t → Version → Version → Spec
roundTripExpectation ∷ (Show t, Eq t, Typeable t, HasCallStack) ⇒ Trip t t → t → Expectation
roundTripRangeExpectation ∷ ∀ t. (Show t, Eq t, Typeable t, HasCallStack) ⇒ Trip t t → Version → Version → t → Expectation
roundTripFailureExpectation ∷ (Typeable t, Eq t, HasCallStack) ⇒ Trip t t → t → Expectation
roundTripRangeFailureExpectation ∷ ∀ t. (Typeable t, Eq t, HasCallStack) ⇒ Trip t t → Version → Version → t → Expectation
roundTripCborExpectation ∷ ∀ t. (Show t, Eq t, EncCBOR t, DecCBOR t, HasCallStack) ⇒ t → Expectation
roundTripCborRangeExpectation ∷ ∀ t. (Show t, Eq t, EncCBOR t, DecCBOR t, HasCallStack) ⇒ Version → Version → t → Expectation
roundTripCborFailureExpectation ∷ ∀ t. (EncCBOR t, DecCBOR t, Eq t, HasCallStack) ⇒ t → Expectation
roundTripCborRangeFailureExpectation ∷ ∀ t. (EncCBOR t, DecCBOR t, Eq t, HasCallStack) ⇒ Version → Version → t → Expectation
roundTripAnnExpectation ∷ (Show t, Eq t, ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ t → Expectation
roundTripAnnRangeExpectation ∷ (Show t, Eq t, ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ Version → Version → t → Expectation
roundTripAnnFailureExpectation ∷ (ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ t → Expectation
roundTripAnnRangeFailureExpectation ∷ (ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ Version → Version → t → Expectation
embedTripSpec ∷ ∀ a b. (Show a, Typeable a, Typeable b, Arbitrary a, Eq b, HasCallStack) ⇒ Version → Version → Trip a b → (b → a → Expectation) → Spec
embedTripExpectation ∷ ∀ a b. (Typeable b, Eq b, HasCallStack) ⇒ Version → Version → Trip a b → (b → a → Expectation) → a → Expectation
embedTripAnnExpectation ∷ ∀ a b. (ToCBOR a, DecCBOR (Annotator b), HasCallStack) ⇒ Version → Version → (b → a → Expectation) → a → Expectation
embedTripFailureExpectation ∷ (Typeable b, Eq b, HasCallStack) ⇒ Trip a b → a → Expectation
embedTripRangeFailureExpectation ∷ ∀ a b. (Typeable b, Eq b, HasCallStack) ⇒ Trip a b → Version → Version → a → Expectation
roundTripTwiddledProperty ∷ (Show t, Eq t, Twiddle t, DecCBOR t) ⇒ Version → t → Property
roundTripAnnTwiddledProperty ∷ ∀ t q. (Twiddle t, DecCBOR (Annotator t), Testable q) ⇒ (t → t → q) → Version → t → Property
data RoundTripFailure = RoundTripFailure {
- rtfEncoderVersion ∷ Version
- rtfDecoderVersion ∷ Version
- rtfEncoding ∷ Encoding
- rtfEncodedBytes ∷ ByteString
- rtfReEncodedBytes ∷ Maybe ByteString
- rtfConformanceError ∷ Maybe String
- rtfDropperError ∷ Maybe DecoderError
- rtfDecoderError ∷ Maybe DecoderError
}
data Trip a b = Trip {
- tripEncoder ∷ a → Encoding
- tripDecoder ∷ ∀ s. Decoder s b
- tripDropper ∷ ∀ s. Decoder s ()
}
mkTrip ∷ ∀ a b. (a → Encoding) → (∀ s. Decoder s b) → Trip a b
cborTrip ∷ ∀ a b. (EncCBOR a, DecCBOR b) ⇒ Trip a b
roundTrip ∷ ∀ t. (Eq t, Typeable t) ⇒ Version → Trip t t → t → Either RoundTripFailure t
roundTripTwiddled ∷ ∀ t. (Twiddle t, DecCBOR t, Eq t) ⇒ Version → t → Gen (Either RoundTripFailure t)
roundTripAnn ∷ (ToCBOR t, DecCBOR (Annotator t)) ⇒ Version → t → Either RoundTripFailure t
roundTripAnnTwiddled ∷ (Twiddle t, DecCBOR (Annotator t)) ⇒ Version → t → Gen (Either RoundTripFailure t)
embedTrip ∷ ∀ a b. (Eq b, Typeable b) ⇒ Version → Version → Trip a b → a → Either RoundTripFailure b
embedTripAnn ∷ ∀ a b. (ToCBOR a, DecCBOR (Annotator b)) ⇒ Version → Version → a → Either RoundTripFailure b
embedTripLabel ∷ ∀ a b. Eq b ⇒ Text → Version → Version → Trip a b → a → Either RoundTripFailure b
embedTripLabelExtra ∷ ∀ a b. Eq b ⇒ Text → Version → Version → Trip a b → a → Either RoundTripFailure (b, Encoding, ByteString)
decodeAnnExtra ∷ ∀ t. Text → Version → Version → (∀ s. Decoder s (Annotator t)) → Encoding → Either RoundTripFailure (t, ByteString)

Spec

roundTripSpec ∷ ∀ t. (Show t, Eq t, Typeable t, Arbitrary t) ⇒ Trip t t → Spec Source #

Tests the roundtrip property using QuickCheck generators for all possible versions starting with shelleyProtVer.

roundTripCborSpec ∷ ∀ t. (Show t, Eq t, Arbitrary t, EncCBOR t, DecCBOR t) ⇒ Spec Source #

Tests the roundtrip property using QuickCheck generators for all possible versions starting with shelleyProtVer.

roundTripAnnCborSpec ∷ ∀ t. (Show t, Eq t, Arbitrary t, ToCBOR t, DecCBOR (Annotator t)) ⇒ Spec Source #

Tests the roundtrip property using QuickCheck generators for all possible versions starting with shelleyProtVer.

roundTripRangeSpec ∷ ∀ t. (Show t, Eq t, Typeable t, Arbitrary t) ⇒ Trip t t → Version → Version → Spec Source #

Tests the roundtrip property using QuickCheck generators for specific range of versions

Expectations

Trip

roundTripExpectation ∷ (Show t, Eq t, Typeable t, HasCallStack) ⇒ Trip t t → t → Expectation Source #

Verify that round triping through the binary form holds for all versions starting with shelleyProtVer.

roundTripRangeExpectation Source #

Arguments

∷ ∀ t. (Show t, Eq t, Typeable t, HasCallStack)
⇒ Trip t t
→ Version	From Version
→ Version	To Version
→ t
→ Expectation

Verify that round triping through the binary form holds for a range of versions.

In other words check that:

deserialize version . serialize version === id
serialize version . deserialize version . serialize version === serialize version

roundTripFailureExpectation ∷ (Typeable t, Eq t, HasCallStack) ⇒ Trip t t → t → Expectation Source #

roundTripRangeFailureExpectation Source #

Arguments

∷ ∀ t. (Typeable t, Eq t, HasCallStack)
⇒ Trip t t
→ Version	From Version
→ Version	To Version
→ t
→ Expectation

Enc/DecCBOR

roundTripCborExpectation ∷ ∀ t. (Show t, Eq t, EncCBOR t, DecCBOR t, HasCallStack) ⇒ t → Expectation Source #

roundTripCborRangeExpectation Source #

Arguments

∷ ∀ t. (Show t, Eq t, EncCBOR t, DecCBOR t, HasCallStack)
⇒ Version	From Version
→ Version	To Version
→ t
→ Expectation

roundTripCborFailureExpectation ∷ ∀ t. (EncCBOR t, DecCBOR t, Eq t, HasCallStack) ⇒ t → Expectation Source #

roundTripCborRangeFailureExpectation Source #

Arguments

∷ ∀ t. (EncCBOR t, DecCBOR t, Eq t, HasCallStack)
⇒ Version	From Version
→ Version	To Version
→ t
→ Expectation

roundTripAnnExpectation ∷ (Show t, Eq t, ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ t → Expectation Source #

roundTripAnnRangeExpectation ∷ (Show t, Eq t, ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ Version → Version → t → Expectation Source #

roundTripAnnFailureExpectation ∷ (ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ t → Expectation Source #

roundTripAnnRangeFailureExpectation ∷ (ToCBOR t, DecCBOR (Annotator t), HasCallStack) ⇒ Version → Version → t → Expectation Source #

Embed

embedTripSpec Source #

Arguments

∷ ∀ a b. (Show a, Typeable a, Typeable b, Arbitrary a, Eq b, HasCallStack)
⇒ Version	Version for the encoder
→ Version	Version for the decoder
→ Trip a b
→ (b → a → Expectation)
→ Spec

Tests the embedtrip property using QuickCheck generators

embedTripExpectation Source #

Arguments

∷ ∀ a b. (Typeable b, Eq b, HasCallStack)
⇒ Version	Version for the encoder
→ Version	Version for the decoder
→ Trip a b
→ (b → a → Expectation)
→ a
→ Expectation

embedTripAnnExpectation Source #

Arguments

∷ ∀ a b. (ToCBOR a, DecCBOR (Annotator b), HasCallStack)
⇒ Version	Version for the encoder
→ Version	Version for the decoder
→ (b → a → Expectation)
→ a
→ Expectation

This is just like roundTripAnnExpectation, except it allows for source and target types to be different. This is very useful to test translation of the same type family from one era to another.

embedTripFailureExpectation ∷ (Typeable b, Eq b, HasCallStack) ⇒ Trip a b → a → Expectation Source #

embedTripRangeFailureExpectation Source #

Arguments

∷ ∀ a b. (Typeable b, Eq b, HasCallStack)
⇒ Trip a b
→ Version	From Version
→ Version	To Version
→ a
→ Expectation

roundTripTwiddledProperty ∷ (Show t, Eq t, Twiddle t, DecCBOR t) ⇒ Version → t → Property Source #

roundTripAnnTwiddledProperty ∷ ∀ t q. (Twiddle t, DecCBOR (Annotator t), Testable q) ⇒ (t → t → q) → Version → t → Property Source #

Tripping failure

data RoundTripFailure Source #

Constructors

RoundTripFailure

Fields

rtfEncoderVersion ∷ Version
Version that was used during encoding
rtfDecoderVersion ∷ Version
Version that was used during decoding
rtfEncoding ∷ Encoding
Produced plain encoding
rtfEncodedBytes ∷ ByteString
Serialized encoding using the version in this failure
rtfReEncodedBytes ∷ Maybe ByteString
Re-serialized bytes, if there was a mismatch between the binary form and the reserialization of the data type.
rtfConformanceError ∷ Maybe String
Roundtripping through FlatTerm
rtfDropperError ∷ Maybe DecoderError
Error received while decoding the produced bytes and dropping the value. Normally it will be Nothing, unless the error produced did not match the rtfDecoderError, in which case it will be Just the error.
rtfDecoderError ∷ Maybe DecoderError
Error received while decoding the produced bytes. It is possible for a dropper to produce an error, while decoder going through successfully, which constitues a test failure. In such a case this field will be Nothing, however rtfDropperError will be set to Just. Whenever both rtfDropperError and rtfDecoderError are Nothing it means that the decoding went though just fine, but there was a mismatch in the binary format, i.e. reserialization produced a mismatched result, in which case rtfReEncodedBytes will be set to Just

Instances

Instances details

Show RoundTripFailure Source #
Instance details Defined in Test.Cardano.Ledger.Binary.RoundTrip Methods showsPrec ∷ Int → RoundTripFailure → ShowS Source # show ∷ RoundTripFailure → String Source # showList ∷ [RoundTripFailure] → ShowS Source #

Tripping definitions

data Trip a b Source #

A definition of a CBOR trip through binary representation of one type to another. In this module this is called an embed. When a source and target type is the exact same one then it would be a dual and is expected to round trip.

Constructors

Trip
Fields tripEncoder ∷ a → Encoding tripDecoder ∷ ∀ s. Decoder s b tripDropper ∷ ∀ s. Decoder s ()

mkTrip ∷ ∀ a b. (a → Encoding) → (∀ s. Decoder s b) → Trip a b Source #

Construct a Trip using encoder and decoder, with dropper set to the decoder which drops the value

cborTrip ∷ ∀ a b. (EncCBOR a, DecCBOR b) ⇒ Trip a b Source #

Tripping functions

roundTrip ∷ ∀ t. (Eq t, Typeable t) ⇒ Version → Trip t t → t → Either RoundTripFailure t Source #

Check that serialization followed by deserialization of the value produces the same value back. We also check that re-serialization is idempotent. In other words, we ensure that deserialization does not modify the decoded value in a way that its binary representation has changed. Dropper is checked as well.

roundTripTwiddled ∷ ∀ t. (Twiddle t, DecCBOR t, Eq t) ⇒ Version → t → Gen (Either RoundTripFailure t) Source #

roundTripAnn ∷ (ToCBOR t, DecCBOR (Annotator t)) ⇒ Version → t → Either RoundTripFailure t Source #

roundTripAnnTwiddled ∷ (Twiddle t, DecCBOR (Annotator t)) ⇒ Version → t → Gen (Either RoundTripFailure t) Source #

embedTrip Source #

Arguments

∷ ∀ a b. (Eq b, Typeable b)
⇒ Version	Version for the encoder
→ Version	Version for the decoder
→ Trip a b
→ a
→ Either RoundTripFailure b

Can we serialise a type, and then deserialise it as something else?

embedTripAnn Source #

Arguments

∷ ∀ a b. (ToCBOR a, DecCBOR (Annotator b))
⇒ Version	Encoder version for test failure reporting
→ Version	Decoder version
→ a
→ Either RoundTripFailure b

embedTripLabel Source #

Arguments

∷ ∀ a b. Eq b
⇒ Text
→ Version	Version for the encoder
→ Version	Version for the decoder
→ Trip a b
→ a
→ Either RoundTripFailure b

embedTripLabelExtra Source #

Arguments

∷ ∀ a b. Eq b
⇒ Text
→ Version	Version for the encoder
→ Version	Version for the decoder
→ Trip a b
→ a
→ Either RoundTripFailure (b, Encoding, ByteString)

decodeAnnExtra Source #

Arguments

∷ ∀ t. Text
→ Version	Version for the encoder
→ Version	Version for the decoder
→ (∀ s. Decoder s (Annotator t))
→ Encoding
→ Either RoundTripFailure (t, ByteString)