Merge #4248

4248: Move the contents of docs/Testing.md closer to the code r=dnadales a=dnadales

This PR moves part of the content of `docs/Testing.md`  to `scripts/prolog`, and the other part of the content is distributed among the relevant modules.

TODO: 

- [ ] Ask `@nfrisby` where the right ThreadNet tests can be found (see TODOs in the prologue).

Closes #4247 



Co-authored-by: Damian Nadales <damian.only@gmail.com>

Author: iohk-bors[bot]

ouroboros-consensus-byron-test/test/Test/ThreadNet/DualByron.hs

@@ -5,6 +5,9 @@
 
 {-# OPTIONS_GHC -Wno-orphans #-}
 
+-- | This runs the Byron ledger and the Byron specification in lockstep,
+--   verifying that they agree at every point.
+--
 module Test.ThreadNet.DualByron (tests) where
 
 import           Control.Monad.Except

ouroboros-consensus-test/src/Test/Util/Serialisation/Golden.hs

@@ -12,6 +12,34 @@
 {-# LANGUAGE TypeApplications    #-}
 
 {-# OPTIONS_GHC -Wno-orphans #-}
+-- | Golden tests infrastructure.
+--
+-- Golden tests are implemented using
+-- __[tasty-golden](https://github.com/UnkindPartition/tasty-golden)__.
+--
+-- When adding a new golden test, running the test suite locally will generate
+-- the golden files. These files should be checked in as CI will fail if there
+-- are missing golden files.
+--
+-- Failing a golden test suite when the corresponding golden files are not found
+-- is done via the @--no-create@ flag, which surprisingly is opt-in. In our
+-- @nix@ infrastructure, this flag for CI is set in
+-- __[ouroboros-network.nix](/nix/ouroboros-network.nix)__:
+--
+-- >  # Command-line options for test suites:
+-- >  packages.ouroboros-consensus-byron-test.components.tests.test.testFlags =
+-- >    lib.mkForce [ "-- >no-create" ];
+-- >  packages.ouroboros-consensus-shelley-test.components.tests.test.testFlags =
+-- >    lib.mkForce [ "-- >no-create" ];
+-- >  packages.ouroboros-consensus-cardano-test.components.tests.test.testFlags =
+-- >    lib.mkForce [ "-- >no-create" ];
+--
+-- In particular, if we introduce golden tests in different suites, we need to add
+-- a line in the nix configuration above similar to the previous ones, eg:
+--
+-- > packages.some-new-package.components.tests.test.testFlags =
+-- >    lib.mkForce [ "-- >no-create" ];
+--
 module Test.Util.Serialisation.Golden (
     Examples (..)
   , Labelled

ouroboros-consensus-test/test-consensus/Test/Consensus/BlockchainTime/Simple.hs

@@ -10,7 +10,30 @@
 {-# LANGUAGE StandaloneDeriving         #-}
 {-# LANGUAGE TypeFamilies               #-}
 {-# LANGUAGE UndecidableInstances       #-}
-
+-- | Tests for the computation of blockchain time.
+--
+-- The @BlockchainTime@ in consensus used to be ubiquitous throughout the code
+-- base, but is now only used in one place: when we are checking if we should
+-- produce a block. It is a simple abstraction that returns the current slot
+-- number, /if it is known/ (it might be unknown of the current ledger state is
+-- too far behind the wallclock). In addition to the problem of the current slot
+-- being unknown, it must also deal with discontinuities in the system's
+-- wallclock: NTP might adjust the clock forward or backward, or, worse, the
+-- user might change their wallclock by a large amount. We don't try to deal
+-- with all of these cases:
+--
+-- * if the clock jumps forward (so we "skip slots") this is no problem
+-- * if the clock is moved back a small amount so that we are still in the same
+--   slot when we expected to be in the next, also okay
+-- * if the clock is moved back by more than that, so that the current slot
+--   would actually /decrease/, we throw an exception; it's then up to the user
+--   (or the wallet) to restart the node.
+--
+-- Since all our tests run in an IO simulator, we can test this by having the
+-- clock behave very erratically. We then compute (in a model) what we expect
+-- the behaviour of the @BlockchainTime@ to be given a specific erratic
+-- behaviour, and then verify that it matches the model.
+--
 module Test.Consensus.BlockchainTime.Simple (tests) where
 
 import           Control.Applicative (Alternative (..))

ouroboros-consensus-test/test-consensus/Test/Consensus/HardFork/History.hs

@@ -11,6 +11,22 @@
 {-# LANGUAGE StandaloneDeriving        #-}
 {-# LANGUAGE TypeOperators             #-}
 
+-- | Hard fork history tests.
+--
+-- This is the more interesting test of the hard fork history. We construct a
+-- mock chain, consisting of events (events are roughly, but not quite,
+-- "blocks"). For every event we record its slot number, epoch number, wall
+-- clock, etc. Since we are constructing this chain as a whole, from genesis to
+-- its tip, constructing these events is trivial. We then split this chain in
+-- half, and construct a @Summary@ from the first half. We then use that summary
+-- to do conversions for any event on the chain. Since every event records all
+-- information, we can easily verify whether the answers we are getting back are
+-- correct. Moreover, since the summary is constructed from only the first part
+-- of the chain, but is used to do conversions across the entire chain, we
+-- verify that predictions about the "future" also work as correctly (including
+-- that the conversions say "outside range" if and only if the model expects
+-- them to be).
+--
 module Test.Consensus.HardFork.History (tests) where
 
 import           Control.Exception (throw)

ouroboros-consensus-test/test-consensus/Test/Consensus/HardFork/Summary.hs

@@ -7,6 +7,19 @@
 {-# LANGUAGE ScopedTypeVariables       #-}
 {-# LANGUAGE StandaloneDeriving        #-}
 
+-- | Tests for the hard fork summary.
+--
+-- This module verifies the property that /no matter how the summary is
+-- constructed/, as long as it satisfies its invariants, we should have
+-- roundtrip properties:
+--
+-- * Converting time to a slot and then back to time should be an identity
+--   (modulo the time spent in that slot).
+-- * Converting a slot to time and then back should be an identity.
+-- * Converting slot to an epoch and then back to a slot should be an identity
+--   (modulo the time spent in that epoch).
+-- * Converting an epoch to a slot and then back should be an identity.
+--
 module Test.Consensus.HardFork.Summary (tests) where
 
 import           Data.Time

ouroboros-consensus-test/test-consensus/Test/Consensus/Mempool.hs

@@ -9,6 +9,21 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 
 {-# OPTIONS_GHC -Wno-incomplete-uni-patterns #-}
+-- | Property tests for the mempool.
+--
+-- The mempool collects transactions from downstream nodes, makes them
+-- available to upstream nodes, and of course provides the pool of transactions
+-- that we use when forging blocks.
+--
+-- These tests for the mempool are not model based, but instead check various
+-- simple properties and invariants, for instance:
+--
+-- * After adding valid transactions to the mempool, they can be retrieved.
+-- * Adding invalid transactions from the mempool will report them as invalid,
+--   and they are not added.
+-- * Transactions cannot be retrieved after they are removed.
+-- * The mempool capacity is not exceeded
+--
 module Test.Consensus.Mempool (tests) where
 
 import           Control.Exception (assert)

ouroboros-consensus-test/test-consensus/Test/Consensus/MiniProtocol/ChainSync/Client.hs

@@ -6,6 +6,22 @@
 {-# LANGUAGE RecordWildCards     #-}
 {-# LANGUAGE ScopedTypeVariables #-}
 {-# LANGUAGE TypeApplications    #-}
+-- | Tests for the chain sync client.
+--
+-- The chain sync client is a stateful component that tracks the chain of an
+-- upstream peer. It validates the headers that it receives from the peer;
+-- validated headers are then reported to the block fetch client which will
+-- download them and offer them to the chain DB, which makes the final choice
+-- whether or not to adopt those blocks.
+--
+-- The tests mock a series of state changes of the up-stream node as well as the
+-- node's own state (the node's own state is relevant because if the node and the
+-- up-stream peer diverge too much we are not interested in their chain anymore,
+-- and we might not be able to validate their headers). We then check that the
+-- chain sync client is reporting the right exceptions if and only if we expect
+-- them to be thrown based on the mock state changes (exceptions such as
+-- "fork is deep", "up-stream node asked for an invalid rollback", etc.).
+--
 module Test.Consensus.MiniProtocol.ChainSync.Client (tests) where
 
 import           Control.Monad.Class.MonadThrow (Handler (..), catches)

ouroboros-consensus-test/test-consensus/Test/Consensus/MiniProtocol/LocalStateQuery/Server.hs

@@ -3,6 +3,19 @@
 {-# LANGUAGE ScopedTypeVariables #-}
 
 {-# OPTIONS_GHC -Wno-orphans #-}
+-- | Tests for the local state query server.
+--
+-- The local state query protocol allows clients such as wallets to query the
+-- state of the ledger at any point within @k@ blocks from the tip. The test for
+-- this is quite minimal at present: it prepopulates a ledger DB with a bunch of
+-- blocks, and then verifies that requesting the ledger tip corresponding to the
+-- these blocks gives the right answers, and that asking for blocks not on the
+-- chain results in the right error message.
+--
+-- Note that the query protocol is abstract in the ledger, and the query
+-- /language/ we offer (the kinds of queries that can be asked) of course
+-- depends on the ledger. The tests use a mock ledger for this purpose.
+--
 module Test.Consensus.MiniProtocol.LocalStateQuery.Server (tests) where
 
 import           Control.Tracer (nullTracer)

ouroboros-consensus-test/test-consensus/Test/Consensus/Node.hs

@@ -4,6 +4,22 @@
 {-# LANGUAGE OverloadedStrings   #-}
 {-# LANGUAGE RankNTypes          #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+-- | Tests for the DB marker and DB lock.
+--
+-- When the consensus layer is integrated into the main node, it provides two
+-- safe guards to avoid data loss and/or corruption:
+--
+-- * When the database is opened, it locks the database so that there can be no
+--   other processes trying to access it at the same time.
+-- * When we create a database directory, we place a "magic marker" in that
+--   directory. This allows us to distinguish the database directory from other
+--   directories, and avoids that we would try to "truncate" a "chain" in a
+--   directory which doesn't contain a DB at all (due to a misconfiguration),
+--   thereby potentially deleting a user's files.
+--
+-- This module contains a bunch of unit tests to make sure that these locks and
+-- markers are created correctly and behave as expected.
+--
 module Test.Consensus.Node (tests) where
 
 import           Data.Bifunctor (second)

ouroboros-consensus-test/test-consensus/Test/Consensus/ResourceRegistry.hs

@@ -13,7 +13,24 @@
 {-# LANGUAGE StandaloneDeriving         #-}
 {-# LANGUAGE TupleSections              #-}
 {-# LANGUAGE TypeApplications           #-}
-
+-- | Tests for the resource registry
+--
+-- The resource registry is a component throughout the consensus layer that
+-- helps us keep track of resources and makes sure that all resources that we
+-- allocate are eventually also deallocated in the right order.
+--
+-- The tests for the registry are model based. The model records which resources
+-- we expect to be alive and which we expect to have been deallocated. The only
+-- resources we are modelling here are threads; the commands we then execute are
+--
+-- * Fork a thread from some other thread
+-- * Terminate a thread
+-- * Have a thread crash
+-- * Collect all live threads
+--
+-- We then verify that the resource registry behaves like the model, cleaning
+-- up resources as threads terminate or crash.
+--
 module Test.Consensus.ResourceRegistry (tests) where
 
 import           Prelude hiding (elem)