diff --git a/src/lib_shell/test/assert.ml b/src/lib_shell/test/assert.ml
index 563a53905a8505b8709b7a1414d326e9f8f8ef5e..8c499f1f43af398bc158d629c0ccd5b987453f93 100644
--- a/src/lib_shell/test/assert.ml
+++ b/src/lib_shell/test/assert.ml
@@ -23,6 +23,8 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(* Provides basic constructs for assertions. *)
+
 let fail expected given msg =
   Format.kasprintf
     Stdlib.failwith
diff --git a/src/lib_shell/test/shell_test_helpers.ml b/src/lib_shell/test/shell_test_helpers.ml
index 06def3c2f5eb8fc94cbf924433c0deb61a3d371f..24e70dd0153f2c179e304e026771ca4afe77bb84 100644
--- a/src/lib_shell/test/shell_test_helpers.ml
+++ b/src/lib_shell/test/shell_test_helpers.ml
@@ -23,7 +23,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
-(** Setup mocks for testing shell, notably state and protocol validation *)
+(** Testing
+    -------
+    Component:    Shell
+    Invocation:   dune build @src/lib_shell/runtest
+    Subject:      Setup mocks for testing shell, notably state and protocol
+                  validation.
+*)
 
 open Filename.Infix
 
@@ -65,7 +71,7 @@ let genesis : Genesis.t =
 let chain_id = Chain_id.of_block_hash genesis_block_hash
 
 (** [init_chain base_dir] with working directory [base_dir] returns a new state
-   with a single genesis block *)
+    with a single genesis block *)
 let init_chain base_dir =
   let store_root = base_dir // "store" in
   let context_root = base_dir // "context" in
diff --git a/src/lib_shell/test/test.ml b/src/lib_shell/test/test.ml
index 99b78c30f7e29ac18a4dc3575321c7e846e46fbf..d5e54cc12444530f5b0fd20e02a1c1b922eb8a31 100644
--- a/src/lib_shell/test/test.ml
+++ b/src/lib_shell/test/test.ml
@@ -24,6 +24,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(** Testing
+    -------
+    Component:    Shell
+    Invocation:   dune build @src/lib_shell/runtest
+    Subject:      Entrypoint
+*)
+
 let () =
   Alcotest_lwt.run
     "tezos-shell"
diff --git a/src/lib_shell/test/test_locator.ml b/src/lib_shell/test/test_locator.ml
index 8dc596078cb3c6546c18c277cae1620281398de5..dc50d3ba73064675f1ef9a7245930f7534812abe 100644
--- a/src/lib_shell/test/test_locator.ml
+++ b/src/lib_shell/test/test_locator.ml
@@ -23,6 +23,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(** Testing
+    -------
+    Component:    Shell
+    Invocation:   dune exec src/lib_shell/test/test_locator.exe test_locator
+    Subject:      Checks operations on locators.
+*)
+
 open Filename.Infix
 
 (** Basic blocks *)
@@ -319,10 +326,10 @@ let linear_predecessor_n (chain : State.Chain.t) (bh : Block_hash.t)
     in
     loop bh distance
 
-(* Tests that the linear predecessor defined above and the
-   exponential predecessor implemented in State.predecessor_n
-   return the same block and it is the block at the distance
-   requested *)
+(** Tests that the linear predecessor defined above and the exponential
+    predecessor implemented in State.predecessor_n return the same
+    block and it is the block at the distance requested
+*)
 let test_pred (base_dir : string) : unit tzresult Lwt.t =
   let size_chain = 1000 in
   init_chain base_dir
@@ -394,17 +401,18 @@ let compute_size_chain size_locator =
   let repeats = 10. in
   int_of_float (repeats *. (2. ** float (size_locator + 1)))
 
-(* test if the linear and exponential locator are the same and outputs
-   their timing.
-   Run the test with:
-   $ dune build @runbench_locator
-   Copy the output to a file timing.dat and plot it with:
-   $ generate_locator_plot.sh timing.dat
-*)
 (*
    chain 1 year   518k   covered by locator 150
    chain 2 months 86k    covered by locator 120
 *)
+
+(** Test if the linear and exponential locator are the same and outputs
+    their timing.
+    Run the test with:
+    $ dune build @runbench_locator
+    Copy the output to a file timing.dat and plot it with:
+    $ generate_locator_plot.sh timing.dat
+*)
 let test_locator base_dir =
   let size_chain = 80000 in
   (* timing locators with average over [runs] times *)
@@ -631,7 +639,7 @@ let tests =
   [ wrap "test pred" test_pred;
     wrap "test protocol locator" test_protocol_locator ]
 
-let bench = [wrap "test locator" test_locator]
+let bench = [wrap "locator" test_locator]
 
 let tests =
   try if Sys.argv.(1) = "--no-bench" then tests else tests @ bench
diff --git a/src/lib_shell/test/test_node.ml b/src/lib_shell/test/test_node.ml
index 647336a4b530b159912dc2e8865a3b2ac708fec2..dbef7c1682aef8768ec86d1d0073abd13dd44132 100644
--- a/src/lib_shell/test/test_node.ml
+++ b/src/lib_shell/test/test_node.ml
@@ -23,8 +23,14 @@
 (*                                                                           *)
 (*****************************************************************************)
 
-(** Unit tests for node. Currently only tests that
-   events are emitted. *)
+(** Testing
+    -------
+    Component:    Shell (Node)
+    Invocation:   dune exec src/lib_shell/test/test.exe test "node"
+    Dependencies: src/lib_shell/test/shell_test_helpers.ml
+    Subject:      Unit tests for node. Currently only tests that
+                  events are emitted.
+*)
 
 let section = Some (Internal_event.Section.make_sanitized ["node"])
 
@@ -136,6 +142,8 @@ let test_event msg (level1, section1, status1) (level2, section2, json2) =
            Data_encoding.Json.pp
            json2)
 
+(** Node creation in sandbox. Expects one event with status
+    [p2p_layer_disabled]. *)
 let node_sandbox_initialization_events sandbox_parameters config _switch () =
   Node.create
     ~sandboxed:true
@@ -165,6 +173,8 @@ let node_sandbox_initialization_events sandbox_parameters config _switch () =
   (* End tests *)
   Node.shutdown n
 
+(** Node creation. Expects two events with statuses
+    [bootstrapping] and [p2p_maintain_started]. *)
 let node_initialization_events _sandbox_parameters config _switch () =
   Node.create
     ~sandboxed:false
diff --git a/src/lib_shell/test/test_protocol_validator.ml b/src/lib_shell/test/test_protocol_validator.ml
index b3b8523dc85fe289441bcf930b151fc327510f83..d1be7c4b5af2b636bd046704a001e68c7c067a27 100644
--- a/src/lib_shell/test/test_protocol_validator.ml
+++ b/src/lib_shell/test/test_protocol_validator.ml
@@ -23,13 +23,17 @@
 (*                                                                           *)
 (*****************************************************************************)
 
-(** Unit tests for protocol_validator. Currently only tests that
-   events are emitted. *)
-
+(** Testing
+    -------
+    Component:    Shell
+    Invocation:   dune exec src/lib_shell/test/test.exe test "protocol validator"
+    Subject:      Unit tests for protocol_validator. Currently only tests that
+                  events are emitted.
+*)
 open Shell_test_helpers
 
 (** A [Alcotest_protocol_validator] extends [Test_services] with protocol
-   validator-specific testables and helpers *)
+    validator-specific testables and helpers *)
 module Alcotest_protocol_validator = struct
   include Test_services
 
@@ -64,8 +68,8 @@ let section =
 let filter = Some section
 
 (** [wrap f _switch] wraps a test function [f] by setting up a Mock_sink if
-   necessary, initializing a mock p2p network, an empty chain state and a
-   validator.  It passes the validator to the test function [f] *)
+    necessary, initializing a mock p2p network, an empty chain state and a
+    validator. It passes the validator to the test function [f]. *)
 let wrap f _switch () =
   with_empty_mock_sink (fun _ ->
       Lwt_utils_unix.with_tempdir "tezos_test_" (fun test_dir ->
@@ -88,9 +92,9 @@ let wrap f _switch () =
 
 (** Start tests *)
 
-(** [pushing_validator_protocol] tests that requesting the validation of a
-   protocol emits a pushing_validation_request event *)
-let pushing_validator_protocol vl _switch () =
+(** Requesting the validation of a protocol emits a
+    pushing_validation_request event. *)
+let test_pushing_validator_protocol vl _switch () =
   (* Let's validate a phony protocol *)
   let pt = Protocol.{expected_env = V0; components = []} in
   Protocol_validator.validate vl Protocol_hash.zero pt
@@ -112,10 +116,10 @@ let pushing_validator_protocol vl _switch () =
     ) ;
   Lwt.return_unit
 
-(** [previously_validated_protocol] tests that requesting the validation of a
-   protocol that is already validated (e.g. the genesis protocol) emits a
-   previously_validated_protocol event *)
-let previously_validated_protocol vl _switch () =
+(** [previously_validated_protocol] tests that requesting the
+    validation of a protocol that is already validated (e.g. the
+    genesis protocol) emits a previously_validated_protocol event. *)
+let test_previously_validated_protocol vl _switch () =
   (* Let's request the re-validation of the genesis protocol *)
   let phony_pt = Protocol.{expected_env = V0; components = []} in
   Protocol_validator.validate vl genesis_protocol_hash phony_pt
@@ -135,9 +139,9 @@ let previously_validated_protocol vl _switch () =
     ) ;
   Lwt.return_unit
 
-(** [fetching_protocol] tests that requesting the fetch of a protocol emits a
-   fetching_protocol event *)
-let fetching_protocol vl _switch () =
+(** [fetching_protocol] tests that requesting the fetch of a protocol
+    emits a fetching_protocol event. *)
+let test_fetching_protocol vl _switch () =
   (* Let's
    fetch a phony protocol, and timeout immediately *)
   Protocol_validator.fetch_and_compile_protocol
@@ -164,10 +168,12 @@ let tests =
   [ Alcotest_lwt.test_case
       "pushing_validator_protocol"
       `Quick
-      (wrap pushing_validator_protocol);
+      (wrap test_pushing_validator_protocol);
     Alcotest_lwt.test_case
       "previously_validated_protocol"
       `Quick
-      (wrap previously_validated_protocol);
-    Alcotest_lwt.test_case "fetching_protocol" `Quick (wrap fetching_protocol)
-  ]
+      (wrap test_previously_validated_protocol);
+    Alcotest_lwt.test_case
+      "fetching_protocol"
+      `Quick
+      (wrap test_fetching_protocol) ]
diff --git a/src/lib_shell/test/test_state.ml b/src/lib_shell/test/test_state.ml
index c8408298c1fbb4142e6063c862753fdc643eb91c..294b04cc6dfce044570471278cb973c57927b79e 100644
--- a/src/lib_shell/test/test_state.ml
+++ b/src/lib_shell/test/test_state.ml
@@ -23,6 +23,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(** Testing
+    -------
+    Component:    Shell (state)
+    Invocation:   dune exec src/lib_shell/test/test.exe test "state"
+    Subject:      On states.
+*)
+
 module Proto = Shell_test_helpers.Genesis_proto
 
 let incr_fitness fitness =
@@ -230,6 +237,7 @@ let wrap_state_init f base_dir =
   >>=? fun (state, chain, _index, _history_mode) ->
   build_example_tree chain >>= fun vblock -> f {state; chain; vblock}
 
+(** Initializes the store. *)
 let test_init (_ : state) = return_unit
 
 (** State.Block.read *)
@@ -434,6 +442,8 @@ let rec compare_path p1 p2 =
   | _ ->
       false
 
+(** Various path traversal checks on [chain_store] (using
+    [Store.Chain_traversal.path]). *)
 let test_path (s : state) =
   let check_path h1 h2 p2 =
     Chain_traversal.path (vblock s h1) (vblock s h2)
@@ -459,8 +469,8 @@ let test_path (s : state) =
 
 (****************************************************************************)
 
-(** Chain_traversal.common_ancestor *)
-
+(** Checks that two blocks admits some same ancestor (using
+    [Store.Chain_traversal.common_ancestor]). *)
 let test_ancestor s =
   let check_ancestor h1 h2 expected =
     Chain_traversal.common_ancestor (vblock s h1) (vblock s h2)
@@ -508,8 +518,8 @@ let seed =
   in
   {Block_locator.receiver_id; sender_id}
 
-(** Chain_traversal.block_locator *)
-
+(** Checks that the locator of some block (i.e., a number of
+    predecessors) corresponds to an expected length and value. *)
 let test_locator s =
   let check_locator length h1 expected =
     State.compute_locator s.chain ~max_size:length (vblock s h1) seed
@@ -566,6 +576,8 @@ let compare s name heads l =
       then Assert.fail_msg "missing block in known_heads (%s: %s)" name bname)
     l
 
+(** Asserts that the initial chain heads of the example chain are A8
+    and B8, (using [Store.Chain.known_heads]). *)
 let test_known_heads s =
   Chain.known_heads s.chain
   >>= fun heads ->
@@ -574,8 +586,9 @@ let test_known_heads s =
 
 (****************************************************************************)
 
-(** Chain.head/set_head *)
-
+(** First, verifies that the chain head is set to genesis. Then, sets
+    chain head to A6 then checks if head is A6 (using
+    [Chain.head/set_head]). *)
 let test_head s =
   Chain.head s.chain
   >>= fun head ->
@@ -599,8 +612,13 @@ let test_head s =
 
 (****************************************************************************)
 
-(** Chain.mem *)
+(** Checks whether some block belongs (or not) to the current mainchain
+    (using Store.Chain.is_in_chain).
 
+    Genesis - A1 - A2 - A3 - A4 - A5 - A6 - A7 - A8
+                             \
+                              B1 - B2 - B3 - B4 - B5 - B6 - B7 - B8
+*)
 let test_mem s =
   let mem s x = Chain.mem s.chain (State.Block.hash @@ vblock s x) in
   let test_mem s x =
@@ -685,8 +703,9 @@ let test_mem s =
 
 (****************************************************************************)
 
-(** Chain_traversal.new_blocks *)
-
+(** Asserts the expected common ancestor and path as obtained by
+    [Store.Chain_traversal.new_blocks] for a series of block pairs in
+    the example chain. *)
 let test_new_blocks s =
   let test s head h expected_ancestor expected =
     let to_block = vblock s head and from_block = vblock s h in
diff --git a/src/lib_shell/test/test_state_checkpoint.ml b/src/lib_shell/test/test_state_checkpoint.ml
index 8a2d74eaab8e353393ac708d71c6bb6338284bc9..3c743c2ee716588513db298bb5a50f5d3450c59e 100644
--- a/src/lib_shell/test/test_state_checkpoint.ml
+++ b/src/lib_shell/test/test_state_checkpoint.ml
@@ -23,6 +23,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(** Testing
+    -------
+    Component:    Shell (state checkpoint)
+    Invocation:   dune exec src/lib_shell/test/test.exe test "state checkpoint"
+    Subject:      On checkpoint handling through the state.
+*)
+
 open Filename.Infix
 
 (** Basic blocks *)
@@ -265,6 +272,9 @@ block and remove any concurrent branch
 does not prevent a future good block from correctly being reached
 - There are no bad quadratic behaviours *)
 
+(** Set the checkpoint at A1 using [Store.Chain.set_checkpoint]. Then
+    check that the chain's checkpoint is A1 using
+    [Store.Chain.checkpoint]. *)
 let test_basic_checkpoint s =
   let block = vblock s "A1" in
   let header = State.Block.header block in
@@ -288,9 +298,10 @@ let test_basic_checkpoint s =
                    B1 - B2 - B3 - B4 - B5
   *)
 
-(* State.Chain.acceptable_block:
-   will the block is compatible with the current checkpoint? *)
-
+(** Sets the checkpoint to A2 and the head to A1.
+    Then verifies that A2 is compatible with the checkpoint using
+    [Store.Chain.acceptable_block], which it should be since it is
+    the checkpoint. *)
 let test_acceptable_block s =
   let block = vblock s "A2" in
   let header = State.Block.header block in
@@ -314,9 +325,8 @@ let test_acceptable_block s =
                    B1 - B2 - B3 - B4 - B5
   *)
 
-(* State.Block.is_valid_for_checkpoint :
-   is the block still valid for a given checkpoint ? *)
-
+(** State.Block.is_valid_for_checkpoint:
+    Is the block still valid for a given checkpoint? *)
 let test_is_valid_checkpoint s =
   let block = vblock s "A2" in
   let header = State.Block.header block in
@@ -334,9 +344,8 @@ let test_is_valid_checkpoint s =
   >>= fun is_valid ->
   if is_valid then return_unit else Assert.fail_msg "invalid checkpoint"
 
-(* return a block with the best fitness amongst the known blocks which
-    are compatible with the given checkpoint *)
-
+(** Return a block with the best fitness amongst the known blocks
+    which are compatible with the given checkpoint. *)
 let test_best_know_head_for_checkpoint s =
   let block = vblock s "A2" in
   let checkpoint = State.Block.header block in
diff --git a/src/lib_shell/test/test_store.ml b/src/lib_shell/test/test_store.ml
index 83ddb61c34edb3b0f6956177a93f8f2de784b59f..789bf6096a7e9602307e045ad202cf2ca3f82848 100644
--- a/src/lib_shell/test/test_store.ml
+++ b/src/lib_shell/test/test_store.ml
@@ -23,6 +23,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(** Testing
+    -------
+    Component:    Shell (store)
+    Invocation:   dune exec src/lib_shell/test/test.exe test "store"
+    Subject:      On the store.
+*)
+
 open Store
 
 let ( >>= ) = Lwt.bind
diff --git a/src/lib_shell/test/test_validator.ml b/src/lib_shell/test/test_validator.ml
index e16a1da24cc4c585531e313355f6e5a4c11f6232..4e5f4d69b10b5b748bf350e8551ac9276f4ef6a3 100644
--- a/src/lib_shell/test/test_validator.ml
+++ b/src/lib_shell/test/test_validator.ml
@@ -23,11 +23,16 @@
 (*                                                                           *)
 (*****************************************************************************)
 
-(** Unit tests for validator. Currently only tests that
-   events are emitted. *)
+(** Testing
+    -------
+    Component:    Shell (Validator)
+    Invocation:   dune exec src/lib_shell/test/test.exe test "validator"
+    Subject:      Unit tests for validator. Currently only tests that
+                  events are emitted.
+*)
 
 (** [init_validator f] setups a mock validator, a mock block validator and
- ** mock chain and passes it them to the test function [f]. *)
+    mock chain and passes it them to the test function [f]. *)
 let init_validator
     (f :
       Validator.t ->
@@ -75,8 +80,8 @@ let init_validator
       Lwt.return_unit
 
 (** [wrap f _switch] wraps a test function [f] by setting up a Mock_sink if
-   necessary, initializing a mock p2p network, an empty chain state and a
-   validator. It passes the validator to the test function [f] *)
+    necessary, initializing a mock p2p network, an empty chain state and a
+    validator. It passes the validator to the test function [f] *)
 let wrap f _switch () =
   Shell_test_helpers.with_empty_mock_sink (fun _ ->
       Lwt_utils_unix.with_tempdir "tezos_test_" (fun test_dir ->
@@ -84,8 +89,7 @@ let wrap f _switch () =
 
 (** Start tests *)
 
-(** [validator_events] tests that validator emits activation and shutdown
-   events. *)
+(** Checks that validator emits activation and shutdown events. *)
 let validator_events validator block_validator chain _switch () =
   (* activate validator and check that the corresponding event is emitted *)
   let open Shell_test_helpers in
diff --git a/src/lib_storage/test/test_context.ml b/src/lib_storage/test/test_context.ml
index f217084ae4284e74b9cfb4fa80db5e7e358bf55d..36a4a5b65e7b9ec556ebe3b7ed1591d54e2cbd46 100644
--- a/src/lib_storage/test/test_context.ml
+++ b/src/lib_storage/test/test_context.ml
@@ -23,6 +23,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(* Testing
+   -------
+   Component:    Storage
+   Invocation:   dune build @src/lib_storage/runtest
+   Subject:      On context features.
+*)
+
 open Context
 
 let ( >>= ) = Lwt.bind
@@ -121,6 +128,11 @@ let wrap_context_init f _ () =
 
 let c = function None -> None | Some s -> Some (Bytes.to_string s)
 
+(** Checkout the context applied until [block2]. It is asserted that
+    the following key-values are present:
+    - (["version"], ["0.0"])
+    - (["a"; "b"], ["Novembre"])
+    - (["a; "c""], ["Juin"]) *)
 let test_simple {idx; block2; _} =
   checkout idx block2
   >>= function
@@ -150,6 +162,13 @@ let test_list {idx; block2; _} =
       Assert.equal_string_list ~msg:__LOC__ ["b"; "c"] ls ;
       Lwt.return_unit
 
+(** Checkout the context applied until [block3a]. It is asserted that
+    the following key-values are present:
+    - (["version"], ["0.0"])
+    - (["a"; "c"], ["Juin"])
+    - (["a"; "d"], ["Mars"])
+    Additionally, the key ["a"; "b"] is associated with nothing as it
+    has been removed by block [block3a]. *)
 let test_continuation {idx; block3a; _} =
   checkout idx block3a
   >>= function
@@ -170,6 +189,13 @@ let test_continuation {idx; block3a; _} =
       Assert.equal_string_option ~msg:__LOC__ (Some "Mars") (c mars) ;
       Lwt.return_unit
 
+(** Checkout the context applied until [block3b]. It is asserted that
+    the following key-values are present:
+    - (["version"], ["0.0"])
+    - (["a"; "b"], ["Novembre"])
+    - (["a"; "d"], ["Février"])
+    Additionally, the key ["a"; "c"] is associated with nothing as it
+    has been removed by block [block3b]. *)
 let test_fork {idx; block3b; _} =
   checkout idx block3b
   >>= function
@@ -190,6 +216,8 @@ let test_fork {idx; block3b; _} =
       Assert.equal_string_option ~msg:__LOC__ (Some "Février") (c mars) ;
       Lwt.return_unit
 
+(** Checkout the context at [genesis] and explicitly replay
+    setting/getting key-values. *)
 let test_replay {idx; genesis; _} =
   checkout idx genesis
   >>= function
@@ -309,6 +337,8 @@ let test_fold_keys {idx; genesis; _} =
       Assert.equal_string_list_list ~msg:__LOC__ (List.map fst bindings) bs ;
       Lwt.return_unit
 
+(** Checkout the context at [genesis] and fold upon a context a series
+    of key settings. *)
 let test_fold {idx; genesis; _} =
   checkout idx genesis
   >>= function
@@ -497,6 +527,9 @@ let test_encoding {idx; genesis; _} =
         h ;
       Lwt.return ()
 
+(** Exports to a dump file the context reached at block [block2b].
+    After importing it, it is asserted that the context hash is
+    preserved. *)
 let test_dump {idx; block3b; _} =
   Lwt_utils_unix.with_tempdir "tezos_test_" (fun base_dir2 ->
       let dumpfile = base_dir2 // "dump" in
diff --git a/src/lib_storage/test/test_raw_store.ml b/src/lib_storage/test/test_raw_store.ml
index 9e1ab9205b3982e40b057f63d26346f04ad55b13..44929ab58dc420988e87e3b6d99018288f033c94 100644
--- a/src/lib_storage/test/test_raw_store.ml
+++ b/src/lib_storage/test/test_raw_store.ml
@@ -23,6 +23,13 @@
 (*                                                                           *)
 (*****************************************************************************)
 
+(** Testing
+    -------
+    Component:    Raw Store
+    Invocation:   dune build @src/lib_storage/runtest
+    Subject:      On (key, value) storage.
+*)
+
 open Raw_store
 
 let ( >>= ) = Lwt.bind
@@ -41,6 +48,11 @@ let wrap_store_init f _ () =
 let entries s k =
   fold s k ~init:[] ~f:(fun e acc -> Lwt.return (e :: acc)) >|= List.rev
 
+(** Stores various (key, value) associations from type [string list] to
+    [bytes]. Use function [entries] to filter out keys by prefix. Then,
+    assert that such lists contain the right keys with [`Key] or [`Dir]
+    for key prefixes.
+*)
 let test_fold st =
   store st ["a"; "b"] (Bytes.of_string "Novembre")
   >>= fun _ ->