Test.Serialization.Symbiote

As an example, say you have some data type TypeA, and some encoding / decoding instance with Aeson for that data type. Now, you've also got a few functions that work with that data type - f :: TypeA -> TypeA and g :: TypeA -> TypeA -> TypeA, and you've also taken the time to write a proper Arbitrary instance for TypeA.

Your first order of business in making TypeA a symbiote, is to first demonstrate what operations are supported by it:

instance SymbioteOperation TypeA where
  data Operation TypeA
    = F
    | G TypeA
  perform op x = case op of
    F -> f x
    G y -> g y x

You're also going to need to make sure your new data-family has appropriate serialization instances, as well:

instance ToJSON (Operation TypeA) where
  toJSON op = case op of
    F -> toJSON "f"
    G x -> "g" .: x

instance FromJSON (Operation TypeA) where
  parseJSON json = getF <|> getG
    where
      getF = do
        s <- parseJSON json
        if s == "f"
          then pure F
          else fail "Not F"
      getG = do
        x <- json .: "g"
        pure (G x)

Next, let's make TypeA an instance of Symbiote:

instance Symbiote TypeA Value where
  encode = Aeson.toJSON
  decode = Aeson.parseMaybe Aeson.parseJSON
  encodeOp = Aeson.toJSON
  decodeOp = Aeson.parseMaybe Aeson.parseJSON

this instance above actually works for any type that implements ToJSON and FromJSON - there's an orphan definition in Test.Serialization.Symbiote.Aeson.

Next, you're going to need to actually use this, by registering the type in a test suite:

myFancyTestSuite :: SymbioteT Value IO ()
myFancyTestSuite = register "TypeA" 100 (Proxy :: Proxy TypeA)

Lastly, you're going to need to actually run the test suite by attaching it to a network. The best way to do that, is decide whether this peer will be the first or second peer to start the protocol, then use the respective firstPeer and secondPeer functions - they take as arguments functions that define "how to send" and "how to receive" messages, and likewise how to report status.

Documentation

class SymbioteOperation a where

A type-level relation between a type and appropriate, testable operations on that type.

Associated Types

data Operation a :: *

Methods

perform :: Operation a -> a -> a

class SymbioteOperation a => Symbiote a s where

A serialization format for a particular type, and serialized data type.

Methods

encode :: a -> s

decode :: s -> Maybe a

encodeOp :: Operation a -> s

decodeOp :: s -> Maybe (Operation a)

Instances

(Serialize a, Serialize (Operation a), SymbioteOperation a) => Symbiote a ByteString

Defined in Test.Serialization.Symbiote.Cereal.Lazy

Methods

encode :: a -> ByteString

decode :: ByteString -> Maybe a

encodeOp :: Operation a -> ByteString

decodeOp :: ByteString -> Maybe (Operation a)

(Serialize a, Serialize (Operation a), SymbioteOperation a) => Symbiote a ByteString

Defined in Test.Serialization.Symbiote.Cereal

Methods

encode :: a -> ByteString

decode :: ByteString -> Maybe a

encodeOp :: Operation a -> ByteString

decodeOp :: ByteString -> Maybe (Operation a)

(ToJSON a, FromJSON a, ToJSON (Operation a), FromJSON (Operation a), SymbioteOperation a) => Symbiote a Value

Defined in Test.Serialization.Symbiote.Aeson

Methods

encode :: a -> Value

decode :: Value -> Maybe a

encodeOp :: Operation a -> Value

decodeOp :: Value -> Maybe (Operation a)

SymbioteOperation a => Symbiote a (EitherOp a)

Defined in Test.Serialization.Symbiote

Methods

encode :: a -> EitherOp a

decode :: EitherOp a -> Maybe a

encodeOp :: Operation a -> EitherOp a

decodeOp :: EitherOp a -> Maybe (Operation a)

newtype EitherOp a

The most trivial serialization medium for any a.

Constructors

EitherOp (Either a (Operation a))

Instances

SymbioteOperation a => Symbiote a (EitherOp a)

Defined in Test.Serialization.Symbiote

Methods

encode :: a -> EitherOp a

decode :: EitherOp a -> Maybe a

encodeOp :: Operation a -> EitherOp a

decodeOp :: EitherOp a -> Maybe (Operation a)

(Eq a, Eq (Operation a)) => Eq (EitherOp a)

Defined in Test.Serialization.Symbiote

Methods

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

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

(Show a, Show (Operation a)) => Show (EitherOp a)

Defined in Test.Serialization.Symbiote

Methods

showsPrec :: Int -> EitherOp a -> ShowS

show :: EitherOp a -> String

showList :: [EitherOp a] -> ShowS

data Topic

Unique name of a type, for a suite of tests

Instances

Eq Topic

Defined in Test.Serialization.Symbiote.Core

Methods

(==) :: Topic -> Topic -> Bool

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

Ord Topic

Defined in Test.Serialization.Symbiote.Core

Methods

compare :: Topic -> Topic -> Ordering

(<) :: Topic -> Topic -> Bool

(<=) :: Topic -> Topic -> Bool

(>) :: Topic -> Topic -> Bool

(>=) :: Topic -> Topic -> Bool

max :: Topic -> Topic -> Topic

min :: Topic -> Topic -> Topic

Show Topic

Defined in Test.Serialization.Symbiote.Core

Methods

showsPrec :: Int -> Topic -> ShowS

show :: Topic -> String

showList :: [Topic] -> ShowS

IsString Topic

Defined in Test.Serialization.Symbiote.Core

Methods

fromString :: String -> Topic

type SymbioteT s m = ReaderT Bool (StateT (Map Topic (SymbioteState s)) m)

register

Arguments

:: Arbitrary a

=> Arbitrary (Operation a)

=> Symbiote a s

=> Eq a

=> MonadIO m

=> Topic

-> Int

Max size

-> Proxy a

-> SymbioteT s m ()

Register a topic in the test suite

firstPeer

Arguments

:: MonadIO m

=> Show s

=> (First s -> m ())

Encode and send first messages

-> m (Second s)

Receive and decode second messages

-> (Topic -> m ())

Report when Successful

-> (Failure Second s -> m ())

Report when Failed

-> (Topic -> Float -> m ())

Report on Progress

-> SymbioteT s m ()

-> m ()

Run the test suite as the first peer

secondPeer

Arguments

:: MonadIO m

=> Show s

=> (Second s -> m ())

Encode and send second messages

-> m (First s)

Receive and decode first messages

-> (Topic -> m ())

Report when Successful

-> (Failure First s -> m ())

Report when Failed

-> (Topic -> Float -> m ())

Report on Progress

-> SymbioteT s m ()

-> m ()

Run the test suite as the second peer

data First s

Messages sent by the first peer

Constructors

AvailableTopics (Map Topic Int)

Mapping of topics to their gen size

FirstGenerating

Fields

• firstGeneratingTopic :: Topic
• firstGenerating :: Generating s

FirstOperating

Fields

• firstOperatingTopic :: Topic
• firstOperating :: Operating s

Instances

Eq s => Eq (First s)

Defined in Test.Serialization.Symbiote

Methods

(==) :: First s -> First s -> Bool

(/=) :: First s -> First s -> Bool

Show s => Show (First s)

Defined in Test.Serialization.Symbiote

Methods

showsPrec :: Int -> First s -> ShowS

show :: First s -> String

showList :: [First s] -> ShowS

data Second s

Messages sent by the second peer

Constructors

BadTopics (Map Topic Int)

Start

SecondOperating

Fields

• secondOperatingTopic :: Topic
• secondOperating :: Operating s

SecondGenerating

Fields

• secondGeneratingTopic :: Topic
• secondGenerating :: Generating s

Instances

Eq s => Eq (Second s)

Defined in Test.Serialization.Symbiote

Methods

(==) :: Second s -> Second s -> Bool

(/=) :: Second s -> Second s -> Bool

Show s => Show (Second s)

Defined in Test.Serialization.Symbiote

Methods

showsPrec :: Int -> Second s -> ShowS

show :: Second s -> String

showList :: [Second s] -> ShowS

data Generating s

Messages sent by a peer during their generating phase

Constructors

Generated

Fields

• genValue :: s
• genOperation :: s

BadResult s

Expected value

YourTurn

ImFinished

GeneratingNoParseOperated s

Instances

Eq s => Eq (Generating s)

Defined in Test.Serialization.Symbiote

Methods

(==) :: Generating s -> Generating s -> Bool

(/=) :: Generating s -> Generating s -> Bool

Show s => Show (Generating s)

Defined in Test.Serialization.Symbiote

Methods

showsPrec :: Int -> Generating s -> ShowS

show :: Generating s -> String

showList :: [Generating s] -> ShowS

data Operating s

Messages sent by a peer during their operating phase

Constructors

Operated s

Serialized value after operation

OperatingNoParseValue s

OperatingNoParseOperation s

Instances

Eq s => Eq (Operating s)

Defined in Test.Serialization.Symbiote

Methods

(==) :: Operating s -> Operating s -> Bool

(/=) :: Operating s -> Operating s -> Bool

Show s => Show (Operating s)

Defined in Test.Serialization.Symbiote

Methods

showsPrec :: Int -> Operating s -> ShowS

show :: Operating s -> String

showList :: [Operating s] -> ShowS

data Failure them s

Constructors

BadTopicsFailure

Fields

• badTopicsFirst :: Map Topic Int
• badTopicsSecond :: Map Topic Int

OutOfSyncFirst (First s)

OutOfSyncSecond (Second s)

TopicNonexistent Topic

WrongTopic

Fields

• wrongTopicExpected :: Topic
• wrongTopicGot :: Topic

CantParseOperated Topic s

CantParseGeneratedValue Topic s

CantParseGeneratedOperation Topic s

CantParseLocalValue Topic s

CantParseLocalOperation Topic s

BadOperating Topic (Operating s)

BadGenerating Topic (Generating s)

BadThem Topic (them s)

SafeFailure

Fields

• safeFailureTopic :: Topic
• safeFailureExpected :: s
• safeFailureGot :: s

Instances

(Eq s, Eq (them s)) => Eq (Failure them s)

Defined in Test.Serialization.Symbiote

Methods

(==) :: Failure them s -> Failure them s -> Bool

(/=) :: Failure them s -> Failure them s -> Bool

(Show s, Show (them s)) => Show (Failure them s)

Defined in Test.Serialization.Symbiote

Methods

showsPrec :: Int -> Failure them s -> ShowS

show :: Failure them s -> String

showList :: [Failure them s] -> ShowS

defaultSuccess :: Topic -> IO ()

Via putStrLn

defaultFailure :: Show (them s) => Show s => Failure them s -> IO ()

Via putStrLn

defaultProgress :: Topic -> Float -> IO ()

Via putStrLn

nullProgress :: Topic -> Float -> IO ()

Do nothing

simpleTest :: MonadBaseControl IO m => MonadIO m => Show s => SymbioteT s m () -> m ()

Prints to stdout and uses a local channel for a sanity-check - doesn't serialize.