Add module description

Author: geo2a

ouroboros-consensus-diffusion/test/consensus-test/Test/Consensus/GSM/QD.hs

@@ -17,8 +17,15 @@
 
 {-# OPTIONS_GHC -Wno-orphans #-}
 
--- | Tests for the Genesis State Machine using the quickcheck-dynamic library
-
+-- | Tests for the Genesis State Machine using the [quickcheck-dynamic](https://hackage.haskell.org/package/quickcheck-dynamic) library.
+--
+--   The instance 'QD.StateModel (Model params)' describes the actions that the model supports,
+--   and their semantics in terms for the model and the system-under-test.
+--
+--   We use the [reflection](https://hackage.haskell.org/package/reflection) library to solve the problem of
+--   injecting user-supplied or quickcheck-generated values into the instance of QD.StateModel.
+--   See the definition of the 'initialState' method, where we access the reflected configuration, and
+--   see 'prop_sequential_iosim' for the construction and reification of the configuration.
 module Test.Consensus.GSM.QD (tests) where
 
 import           Control.Concurrent.Class.MonadSTM.Strict.TVar.Checked
@@ -63,10 +70,10 @@ tests = adhoc <> core
     adhoc = [ testProperty "GSM yield regression" prop_yield_regression
             ]
     core = [
-        adjustQuickCheckTests (* 10) $
-        testProperty ("GSM (" <> coreTestName upstreamPeerBound <> ")") $
-        prop_sequential_iosim upstreamPeerBound
-        | upstreamPeerBound <- Nothing : map Just [minBound .. maxBound :: UpstreamPeer]
+          adjustQuickCheckTests (* 10)
+        $ testProperty ("GSM (" <> coreTestName upstreamPeerBound <> ")")
+        $ prop_sequential_iosim upstreamPeerBound
+      | upstreamPeerBound <- Nothing : map Just [minBound .. maxBound :: UpstreamPeer]
       ]
 
     coreTestName = \case
@@ -97,14 +104,14 @@ prop_yield_regression =
          <> (wrapPositiveAction $ ExtendSelection (S (-4)))
          <> (wrapPositiveAction $ ReadMarker)
 
-prop_sequential_iosim :: Maybe UpstreamPeer -> QC.Property
-prop_sequential_iosim pUpstreamPeerBound =
-  QC.forAll QC.arbitrary $ \pInitialJudgement ->
-  QC.forAll QC.arbitrary $ \(QC.Fun _ pIsHaaSatisfied) ->
+prop_sequential_iosim :: Maybe UpstreamPeer -> LedgerStateJudgement -> QC.Fun (Set.Set UpstreamPeer) Bool -> QC.Property
+prop_sequential_iosim pUpstreamPeerBound pInitialJudgement (QC.Fun _ pIsHaaSatisfied) =
     Reflection.reify (StaticParams{ pUpstreamPeerBound
                                   , pInitialJudgement
                                   , pIsHaaSatisfied
                                   }) $ \(Proxy :: Proxy params) ->
+     -- NOTE: the actions have to be generated with an explicit call, as
+     -- 'generator' relies on reflection for access to the parameters
      QC.forAll QC.arbitrary $ \actions ->
        runIOSimProp $ prop_sequential_iosim1 @_ @params actions