Add docs about the reporter and the code design

Author: alcuadrado

v-next/hardhat-node-test-reporter/src/reporter.ts

@@ -20,23 +20,66 @@ import {
 
 export const SLOW_TEST_THRESHOLD = 75;
 
+/**
+ * This is a node:test reporter that tries to mimic Mocha's default reporter, as
+ * close as possible.
+ *
+ * It is designed to output information about the test runs as soon as possible
+ * and in test defintion order.
+ *
+ * Once the test run ends, it will output global information about it, based on
+ * the diagnostics emitted by node:test, and any custom or unrecognized
+ * diagnostics message.
+ *
+ * Finally, it will output the failure reasons for all the failed tests.
+ *
+ * @param source
+ */
 export default async function* customReporter(
   source: TestEventSource,
 ): TestReporterResult {
-  // This reporter prints the tests in definition order, imitating Mocha's
-  // default reporter as close as possible.
-  //
-  // We use this stack to keep track of the current test hierarchy.
-  //
-  // The output of each test (its context - the describe they belong to -
-  // and if they passed/failed) is printed as soon as the test finishes.
+  /**
+   * The test reporter works by keeping a stack of the currently executing[1]
+   * tests and suites. We use it to keep track of the context of a test, so that
+   * when it passes or fails, we can print that context (if necessary), before
+   * its results.
+   *
+   * Printing the context of a test will normally imply printing all the
+   * describes where it is nested.
+   *
+   * As the context may be shared by more than one test, and we don't want to
+   * repeate it, we keep track of the last printed context element. We do this
+   * by keeping track of its index in the stack.
+   *
+   * We also keep track of any diagnostic message that its reported by node:test
+   * and at the end we try to parse the global diagnostics to gather information
+   * about the test run. If during this parsing we don't recognize or can't
+   * properly parse one of this diagnostics, we will print it at the end.
+   *
+   * Whenever a test fails, we pre-format its failure reason, so that don't need
+   * to keep the failure event in memory, and we can still print the failure
+   * reason at the end.
+   *
+   * This code is structed in the following way:
+   *  - We use an async generator to process the events as they come, printing
+   *  the information as soon as possible.
+   *  - Instead of printing, we yield string.
+   *  - Any formatting that needs to be done is done in the formatting module.
+   *  - The formatting module exports functions that generate strings for the
+   *  different parts of the test run's output. They do not print anything, and
+   *  they never end in a newline. Any newline between different parts of the
+   *  output is added by the generator.
+   *  - The generaor drives the high-level format of the output, and only uses
+   *  the formatting functions to generate repetitive parts of it.
+   *
+   * [1] As reporter by node:test, in defintion order, which may differ from
+   * actual execution order.
+   */
+
   const stack: Array<TestEventData["test:start"]> = [];
 
-  // We use this number to keep track of which elements from the stack have
-  // already been printed (e.g. a describe).
   let lastPrintedIndex: number | undefined;
 
-  // Diagnostics are processed at the end, so we collect them all here
   const diagnostics: Array<TestEventData["test:diagnostic"]> = [];
 
   const preFormattedFailureReasons: string[] = [];
@@ -55,7 +98,7 @@ export default async function* customReporter(
       case "test:fail": {
         if (event.data.details.type === "suite") {
           // If a suite failed for a reason other than a subtest failing, we
-          // want to print its failure, so we push it to the failures array.
+          // want to print its failure.
           if (event.type === "test:fail") {
             if (!isSubtestFailedError(event.data.details.error)) {
               preFormattedFailureReasons.push(
@@ -68,14 +111,11 @@ export default async function* customReporter(
             }
           }
 
-          stack.pop();
-
           // If a suite/describe was already printed, we need to descrease
           // the lastPrintedIndex, as we are removing it from the stack.
           //
           // If its nesting was 0, we print an empty line to separate top-level
           // describes.
-
           if (event.data.nesting === 0) {
             lastPrintedIndex = undefined;
             yield "\n";
@@ -89,11 +129,13 @@ export default async function* customReporter(
             }
           }
 
+          // Remove the current test from the stack, as it was just processed
+          stack.pop();
           continue;
         }
 
         // If we have printed everything except the current element in the stack
-        // all of it's context/hierarchy has been printed (e.g. the describes).\
+        // all of it's context/hierarchy has been printed (e.g. its describes).
         //
         // Otherwise, we print all the unprinted elements in the stack, except
         // for the last one, which is the current test.
@@ -117,24 +159,27 @@ export default async function* customReporter(
             contextStack: stack,
           };
 
+          // We format the failure reason and store it in an array, so that we
+          // can output it at the end.
           preFormattedFailureReasons.push(formatFailureReason(failure));
 
           yield formatTestFailure(failure);
         }
 
+        // If the test was slow, we print a message about it
         if (event.data.details.duration_ms > SLOW_TEST_THRESHOLD) {
           yield formatSlowTestInfo(event.data.details.duration_ms);
         }
 
         yield "\n";
 
-        stack.pop();
-
         // Top-level tests are separated by an empty line
         if (event.data.nesting === 0) {
           yield "\n";
         }
 
+        // Remove the current test from the stack, as it was just processed it
+        stack.pop();
         break;
       }
       case "test:stderr": {