docs: update help message about unit test-suite pattern matching (#4846)

Update the "rippled --help" message for the "-u" parameter. This
documents the unit test name pattern matching rule implemented by #4634.

Fix #4800

Author: ckeshava

CONTRIBUTING.md

@@ -125,6 +125,25 @@ pip3 install pre-commit
 pre-commit install
 ```
 
+## Unit Tests
+To execute all unit tests:
+
+```rippled --unittest --unittest-jobs=<number of cores>```
+
+(Note: Using multiple cores on a Mac M1 can cause spurious test failures. The 
+cause is still under investigation. If you observe this problem, try specifying fewer jobs.)
+
+To run a specific set of test suites:
+
+```
+rippled --unittest TestSuiteName
+```
+Note: In this example, all tests with prefix `TestSuiteName` will be run, so if
+`TestSuiteName1` and `TestSuiteName2` both exist, then both tests will run. 
+Alternatively, if the unit test name finds an exact match, it will stop 
+doing partial matches, i.e. if a unit test with a title of `TestSuiteName` 
+exists, then no other unit test will be executed, apart from `TestSuiteName`.
+
 ## Avoid
 
 1. Proliferation of nearly identical code.

src/ripple/app/main/Main.cpp

@@ -431,9 +431,8 @@ run(int argc, char** argv)
         po::value<std::string>()->implicit_value(""),
         "Perform unit tests. The optional argument specifies one or "
         "more comma-separated selectors. Each selector specifies a suite name, "
-        "full-name (lib.module.suite), module, or library "
-        "(checked in that "
-        "order).")(
+        "suite name prefix, full-name (lib.module.suite), module, or library "
+        "(checked in that order).")(
         "unittest-arg",
         po::value<std::string>()->implicit_value(""),
         "Supplies an argument string to unit tests. If provided, this argument "

src/test/app/NFTokenBurn_test.cpp

@@ -26,7 +26,7 @@
 
 namespace ripple {
 
-class NFTokenBurn0_test : public beast::unit_test::suite
+class NFTokenBurnBaseUtil_test : public beast::unit_test::suite
 {
     // Helper function that returns the owner count of an account root.
     static std::uint32_t
@@ -815,39 +815,39 @@ class NFTokenBurn0_test : public beast::unit_test::suite
     }
 };
 
-class NFTokenBurn1_test : public NFTokenBurn0_test
+class NFTokenBurnWOfixFungTokens_test : public NFTokenBurnBaseUtil_test
 {
 public:
     void
     run() override
     {
-        NFTokenBurn0_test::run(1);
+        NFTokenBurnBaseUtil_test::run(1);
     }
 };
 
-class NFTokenBurn2_test : public NFTokenBurn0_test
+class NFTokenBurnWOFixTokenRemint_test : public NFTokenBurnBaseUtil_test
 {
 public:
     void
     run() override
     {
-        NFTokenBurn0_test::run(2);
+        NFTokenBurnBaseUtil_test::run(2);
     }
 };
 
-class NFTokenBurn3_test : public NFTokenBurn0_test
+class NFTokenBurnAllFeatures_test : public NFTokenBurnBaseUtil_test
 {
 public:
     void
     run() override
     {
-        NFTokenBurn0_test::run(3, true);
+        NFTokenBurnBaseUtil_test::run(3, true);
     }
 };
 
-BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurn0, tx, ripple, 3);
-BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurn1, tx, ripple, 3);
-BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurn2, tx, ripple, 3);
-BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurn3, tx, ripple, 3);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurnBaseUtil, tx, ripple, 3);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurnWOfixFungTokens, tx, ripple, 3);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurnWOFixTokenRemint, tx, ripple, 3);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBurnAllFeatures, tx, ripple, 3);
 
 }  // namespace ripple

src/test/app/NFToken_test.cpp

@@ -27,7 +27,7 @@
 
 namespace ripple {
 
-class NFToken0_test : public beast::unit_test::suite
+class NFTokenBaseUtil_test : public beast::unit_test::suite
 {
     FeatureBitset const disallowIncoming{featureDisallowIncoming};
 
@@ -6863,46 +6863,46 @@ class NFToken0_test : public beast::unit_test::suite
     }
 };
 
-class NFToken1_test : public NFToken0_test
+class NFTokenDisallowIncoming_test : public NFTokenBaseUtil_test
 {
     void
     run() override
     {
-        NFToken0_test::run(1);
+        NFTokenBaseUtil_test::run(1);
     }
 };
 
-class NFToken2_test : public NFToken0_test
+class NFTokenWOfixV1_test : public NFTokenBaseUtil_test
 {
     void
     run() override
     {
-        NFToken0_test::run(2);
+        NFTokenBaseUtil_test::run(2);
     }
 };
 
-class NFToken3_test : public NFToken0_test
+class NFTokenWOTokenRemint_test : public NFTokenBaseUtil_test
 {
     void
     run() override
     {
-        NFToken0_test::run(3);
+        NFTokenBaseUtil_test::run(3);
     }
 };
 
-class NFToken4_test : public NFToken0_test
+class NFTokenAllFeatures_test : public NFTokenBaseUtil_test
 {
     void
     run() override
     {
-        NFToken0_test::run(4, true);
+        NFTokenBaseUtil_test::run(4, true);
     }
 };
 
-BEAST_DEFINE_TESTSUITE_PRIO(NFToken0, tx, ripple, 2);
-BEAST_DEFINE_TESTSUITE_PRIO(NFToken1, tx, ripple, 2);
-BEAST_DEFINE_TESTSUITE_PRIO(NFToken2, tx, ripple, 2);
-BEAST_DEFINE_TESTSUITE_PRIO(NFToken3, tx, ripple, 2);
-BEAST_DEFINE_TESTSUITE_PRIO(NFToken4, tx, ripple, 2);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenBaseUtil, tx, ripple, 2);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenDisallowIncoming, tx, ripple, 2);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenWOfixV1, tx, ripple, 2);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenWOTokenRemint, tx, ripple, 2);
+BEAST_DEFINE_TESTSUITE_PRIO(NFTokenAllFeatures, tx, ripple, 2);
 
 }  // namespace ripple

src/test/app/Offer_test.cpp

@@ -27,7 +27,7 @@
 namespace ripple {
 namespace test {
 
-class Offer0_test : public beast::unit_test::suite
+class OfferBaseUtil_test : public beast::unit_test::suite
 {
     XRPAmount
     reserve(jtx::Env& env, std::uint32_t count)
@@ -5371,52 +5371,52 @@ class Offer0_test : public beast::unit_test::suite
     }
 };
 
-class Offer1_test : public Offer0_test
+class OfferWOFlowCross_test : public OfferBaseUtil_test
 {
     void
     run() override
     {
-        Offer0_test::run(1);
+        OfferBaseUtil_test::run(1);
     }
 };
 
-class Offer2_test : public Offer0_test
+class OfferWTakerDryOffer_test : public OfferBaseUtil_test
 {
     void
     run() override
     {
-        Offer0_test::run(2);
+        OfferBaseUtil_test::run(2);
     }
 };
 
-class Offer3_test : public Offer0_test
+class OfferWOSmallQOffers_test : public OfferBaseUtil_test
 {
     void
     run() override
     {
-        Offer0_test::run(3);
+        OfferBaseUtil_test::run(3);
     }
 };
 
-class Offer4_test : public Offer0_test
+class OfferWOFillOrKill_test : public OfferBaseUtil_test
 {
     void
     run() override
     {
-        Offer0_test::run(4);
+        OfferBaseUtil_test::run(4);
     }
 };
 
-class Offer5_test : public Offer0_test
+class OfferAllFeatures_test : public OfferBaseUtil_test
 {
     void
     run() override
     {
-        Offer0_test::run(5, true);
+        OfferBaseUtil_test::run(5, true);
     }
 };
 
-class Offer_manual_test : public Offer0_test
+class Offer_manual_test : public OfferBaseUtil_test
 {
     void
     run() override
@@ -5439,12 +5439,12 @@ class Offer_manual_test : public Offer0_test
     }
 };
 
-BEAST_DEFINE_TESTSUITE_PRIO(Offer0, tx, ripple, 4);
-BEAST_DEFINE_TESTSUITE_PRIO(Offer1, tx, ripple, 4);
-BEAST_DEFINE_TESTSUITE_PRIO(Offer2, tx, ripple, 4);
-BEAST_DEFINE_TESTSUITE_PRIO(Offer3, tx, ripple, 4);
-BEAST_DEFINE_TESTSUITE_PRIO(Offer4, tx, ripple, 4);
-BEAST_DEFINE_TESTSUITE_PRIO(Offer5, tx, ripple, 4);
+BEAST_DEFINE_TESTSUITE_PRIO(OfferBaseUtil, tx, ripple, 4);
+BEAST_DEFINE_TESTSUITE_PRIO(OfferWOFlowCross, tx, ripple, 4);
+BEAST_DEFINE_TESTSUITE_PRIO(OfferWTakerDryOffer, tx, ripple, 4);
+BEAST_DEFINE_TESTSUITE_PRIO(OfferWOSmallQOffers, tx, ripple, 4);
+BEAST_DEFINE_TESTSUITE_PRIO(OfferWOFillOrKill, tx, ripple, 4);
+BEAST_DEFINE_TESTSUITE_PRIO(OfferAllFeatures, tx, ripple, 4);
 BEAST_DEFINE_TESTSUITE_MANUAL_PRIO(Offer_manual, tx, ripple, 20);
 
 }  // namespace test

src/test/app/TxQ_test.cpp

@@ -35,7 +35,7 @@ namespace ripple {
 
 namespace test {
 
-class TxQ1_test : public beast::unit_test::suite
+class TxQPosNegFlows_test : public beast::unit_test::suite
 {
     void
     checkMetrics(
@@ -4949,7 +4949,7 @@ class TxQ1_test : public beast::unit_test::suite
     }
 
     void
-    run2()
+    runMetaInfo()
     {
         testAcctInQueueButEmpty();
         testRPC();
@@ -4970,17 +4970,17 @@ class TxQ1_test : public beast::unit_test::suite
     }
 };
 
-class TxQ2_test : public TxQ1_test
+class TxQMetaInfo_test : public TxQPosNegFlows_test
 {
     void
     run() override
     {
-        run2();
+        runMetaInfo();
     }
 };
 
-BEAST_DEFINE_TESTSUITE_PRIO(TxQ1, app, ripple, 1);
-BEAST_DEFINE_TESTSUITE_PRIO(TxQ2, app, ripple, 1);
+BEAST_DEFINE_TESTSUITE_PRIO(TxQPosNegFlows, app, ripple, 1);
+BEAST_DEFINE_TESTSUITE_PRIO(TxQMetaInfo, app, ripple, 1);
 
 }  // namespace test
 }  // namespace ripple