QA: Put UTILITY_PROGRAM in KI_TEST

Also expand some documentation of some other KI_TEST functions.

qa/common_tools/main.cpp

@@ -32,7 +32,7 @@
  * This is a pretty rudimentary way to register, but for a simple purpose,
  * it's effective enough. When you have a new tool, add it to this list.
  */
-const static std::vector<UTILITY_PROGRAM*> known_tools = {
+const static std::vector<KI_TEST::UTILITY_PROGRAM*> known_tools = {
     &coroutine_tool,
     &io_benchmark_tool,
 };
@@ -40,7 +40,7 @@ const static std::vector<UTILITY_PROGRAM*> known_tools = {
 
 int main( int argc, char** argv )
 {
-    COMBINED_UTILITY c_util( known_tools );
+    KI_TEST::COMBINED_UTILITY c_util( known_tools );
 
     return c_util.HandleCommandLine( argc, argv );
 }

qa/common_tools/tools/coroutines/coroutine_tools.h

@@ -5,6 +5,6 @@
 #include <utility_program.h>
 
 /// A tool to test a simple coroutine
-extern UTILITY_PROGRAM coroutine_tool;
+extern KI_TEST::UTILITY_PROGRAM coroutine_tool;
 
 #endif

qa/common_tools/tools/coroutines/coroutines.cpp

@@ -114,7 +114,7 @@ static int coroutine_main_func( int argc, char** argv )
     if( cmd_parsed_ok != 0 )
     {
         // Help and invalid input both stop here
-        return ( cmd_parsed_ok == -1 ) ? RET_CODES::OK : RET_CODES::BAD_CMDLINE;
+        return ( cmd_parsed_ok == -1 ) ? KI_TEST::RET_CODES::OK : KI_TEST::RET_CODES::BAD_CMDLINE;
     }
 
     long count = 5;
@@ -124,14 +124,14 @@ static int coroutine_main_func( int argc, char** argv )
 
     obj.Run();
 
-    return RET_CODES::OK;
+    return KI_TEST::RET_CODES::OK;
 }
 
 
 /*
  * Define the tool interface
  */
-UTILITY_PROGRAM coroutine_tool = {
+KI_TEST::UTILITY_PROGRAM coroutine_tool = {
     "coroutine",
     "Test a simple coroutine",
     coroutine_main_func,

qa/common_tools/tools/io_benchmark/io_benchmark.cpp

@@ -388,7 +388,7 @@ int io_benchmark_func( int argc, char* argv[] )
         os << "Usage: " << argv[0] << " <FILE> <REPS> [" << getBenchFlags() << "]\n\n";
         os << "Benchmarks:\n";
         os << getBenchDescriptions();
-        return RET_CODES::BAD_CMDLINE;
+        return KI_TEST::RET_CODES::BAD_CMDLINE;
     }
 
     wxFileName inFile( argv[1] );
@@ -419,11 +419,11 @@ int io_benchmark_func( int argc, char* argv[] )
             << std::endl;;
     }
 
-    return RET_CODES::OK;
+    return KI_TEST::RET_CODES::OK;
 }
 
 
-UTILITY_PROGRAM io_benchmark_tool = {
+KI_TEST::UTILITY_PROGRAM io_benchmark_tool = {
     "io_benchmark",
     "Benchmark various kinds of IO methods",
     io_benchmark_func,

qa/common_tools/tools/io_benchmark/io_benchmark.h

@@ -26,6 +26,6 @@
 
 #include <utility_program.h>
 
-extern UTILITY_PROGRAM io_benchmark_tool;
+extern KI_TEST::UTILITY_PROGRAM io_benchmark_tool;
 
 #endif // IO_BENCHMARK_H

qa/pcbnew_tools/pcbnew_tools.cpp

@@ -33,7 +33,7 @@
  * This is a pretty rudimentary way to register, but for a simple purpose,
  * it's effective enough. When you have a new tool, add it to this list.
  */
-const static std::vector<UTILITY_PROGRAM*> known_tools = {
+const static std::vector<KI_TEST::UTILITY_PROGRAM*> known_tools = {
     &drc_tool,
     &pcb_parser_tool,
     &polygon_generator_tool,
@@ -42,7 +42,7 @@ const static std::vector<UTILITY_PROGRAM*> known_tools = {
 
 int main( int argc, char** argv )
 {
-    COMBINED_UTILITY c_util( known_tools );
+    KI_TEST::COMBINED_UTILITY c_util( known_tools );
 
     return c_util.HandleCommandLine( argc, argv );
 }

qa/pcbnew_tools/tools/drc_tool/drc_tool.cpp

@@ -304,7 +304,7 @@ static const wxCmdLineEntryDesc g_cmdLineDesc[] = {
  */
 enum PARSER_RET_CODES
 {
-    PARSE_FAILED = RET_CODES::TOOL_SPECIFIC,
+    PARSE_FAILED = KI_TEST::RET_CODES::TOOL_SPECIFIC,
 };
 
 
@@ -325,7 +325,7 @@ int drc_main_func( int argc, char** argv )
     if( cmd_parsed_ok != 0 )
     {
         // Help and invalid input both stop here
-        return ( cmd_parsed_ok == -1 ) ? RET_CODES::OK : RET_CODES::BAD_CMDLINE;
+        return ( cmd_parsed_ok == -1 ) ? KI_TEST::RET_CODES::OK : KI_TEST::RET_CODES::BAD_CMDLINE;
     }
 
     const bool verbose = cl_parser.Found( "verbose" );
@@ -380,14 +380,14 @@ int drc_main_func( int argc, char** argv )
         runner.Execute( *board );
     }
 
-    return RET_CODES::OK;
+    return KI_TEST::RET_CODES::OK;
 }
 
 
 /*
  * Define the tool interface
  */
-UTILITY_PROGRAM drc_tool = {
+KI_TEST::UTILITY_PROGRAM drc_tool = {
     "drc",
     "Run selected DRC function on a PCB",
     drc_main_func,

qa/pcbnew_tools/tools/drc_tool/drc_tool.h

@@ -27,6 +27,6 @@
 #include <utility_program.h>
 
 /// A tool to run DRC tools on KiCad PCBs from the command line
-extern UTILITY_PROGRAM drc_tool;
+extern KI_TEST::UTILITY_PROGRAM drc_tool;
 
 #endif //PCBNEW_TOOLS_DRC_TOOL_H

qa/pcbnew_tools/tools/pcb_parser/pcb_parser_tool.cpp

@@ -95,7 +95,7 @@ static const wxCmdLineEntryDesc g_cmdLineDesc[] = {
 
 enum PARSER_RET_CODES
 {
-    PARSE_FAILED = RET_CODES::TOOL_SPECIFIC,
+    PARSE_FAILED = KI_TEST::RET_CODES::TOOL_SPECIFIC,
 };
 
 
@@ -117,7 +117,7 @@ int pcb_parser_main_func( int argc, char** argv )
     if( cmd_parsed_ok != 0 )
     {
         // Help and invalid input both stop here
-        return ( cmd_parsed_ok == -1 ) ? RET_CODES::OK : RET_CODES::BAD_CMDLINE;
+        return ( cmd_parsed_ok == -1 ) ? KI_TEST::RET_CODES::OK : KI_TEST::RET_CODES::BAD_CMDLINE;
     }
 
     const bool verbose = cl_parser.Found( "verbose" );
@@ -157,14 +157,14 @@ int pcb_parser_main_func( int argc, char** argv )
     if( !ok )
         return PARSER_RET_CODES::PARSE_FAILED;
 
-    return RET_CODES::OK;
+    return KI_TEST::RET_CODES::OK;
 }
 
 
 /*
  * Define the tool interface
  */
-UTILITY_PROGRAM pcb_parser_tool = {
+KI_TEST::UTILITY_PROGRAM pcb_parser_tool = {
     "pcb_parser",
     "Parse a KiCad PCB file",
     pcb_parser_main_func,

qa/pcbnew_tools/tools/pcb_parser/pcb_parser_tool.h

@@ -27,6 +27,6 @@
 #include <utility_program.h>
 
 /// A tool to parse kicad PCBs from the command line
-extern UTILITY_PROGRAM pcb_parser_tool;
+extern KI_TEST::UTILITY_PROGRAM pcb_parser_tool;
 
 #endif //PCBNEW_TOOLS_PCB_PARSER_UTILITY_H

qa/pcbnew_tools/tools/polygon_generator/polygon_generator.cpp

@@ -118,7 +118,7 @@ int polygon_gererator_main( int argc, char* argv[] )
 /*
  * Define the tool interface
  */
-UTILITY_PROGRAM polygon_generator_tool = {
+KI_TEST::UTILITY_PROGRAM polygon_generator_tool = {
     "polygon_generator",
     "Dump board geometry as a set of polygons",
     polygon_gererator_main,

qa/pcbnew_tools/tools/polygon_generator/polygon_generator.h

@@ -27,6 +27,6 @@
 #include <utility_program.h>
 
 /// A tool to parse kicad PCBs from the command line
-extern UTILITY_PROGRAM polygon_generator_tool;
+extern KI_TEST::UTILITY_PROGRAM polygon_generator_tool;
 
 #endif //PCBNEW_TOOLS_POLYGON_GENERATOR_UTILITY_H

qa/qa_utils/utility_program.cpp

@@ -24,15 +24,14 @@
 
 #include <wx/msgout.h>
 
+namespace KI_TEST
+{
 
 COMBINED_UTILITY::COMBINED_UTILITY( const UTIL_LIST& aSubUtils ) : m_subUtils( aSubUtils )
 {
 }
 
 
-/**
- * Print the names and descriptions of the registered tools
- */
 void COMBINED_UTILITY::showSubUtilityList( std::ostream& os ) const
 {
     for( const auto& tool : m_subUtils )
@@ -42,11 +41,6 @@ void COMBINED_UTILITY::showSubUtilityList( std::ostream& os ) const
 }
 
 
-/**
- * Get the utility program that matches a tool name
- * @param  aName the name to look for
- * @return       the tool function
- */
 UTILITY_PROGRAM::FUNC* COMBINED_UTILITY::findSubUtility( const std::string& aName ) const
 {
     for( const auto& tool : m_subUtils )
@@ -112,4 +106,6 @@ int COMBINED_UTILITY::HandleCommandLine( int argc, char** argv ) const
 
     // pass on the rest of the commands
     return ( *func )( argc - 1, argv + 1 );
-}
+}
+
+} // namespace KI_TEST

qa/qa_utils/utility_program.h

@@ -29,6 +29,9 @@
 #include <string>
 #include <vector>
 
+namespace KI_TEST
+{
+
 /**
  * Return codes for tools
  */
@@ -127,4 +130,6 @@ private:
     const UTIL_LIST& m_subUtils;
 };
 
+} // namespace KI_TEST
+
 #endif // UTILITY_PROGRAM_H

qa/unit_test_utils/include/unit_test_utils/unit_test_utils.h

@@ -80,6 +80,29 @@
 
 namespace KI_TEST
 {
+
+template <typename EXP_CONT> using EXP_OBJ = typename EXP_CONT::value_type;
+template <typename FOUND_CONT> using FOUND_OBJ = typename FOUND_CONT::value_type;
+
+/**
+ * A match predicate: check that a "found" object is equivalent to or represents
+ * an "expected" object, perhaps of a different type.
+ *
+ * Exactly what "equivalent to" means depends heavily on the context and what
+ * is care about. For example, if you only care about a #MODULE's refdes,
+ * std::string is sufficient to indicate a "match".
+ *
+ * This can be used, for example, for checking a set of results without having
+ * to instantiate a full result object for checking by equality.
+ *
+ * @tparam EXP_OBJ      the "expected" object type
+ * @tparam FOUND_OBJ    the "found" object type
+ *
+ * @return true if the "found" object represents the "expected" object
+ */
+template <typename EXP_OBJ, typename FOUND_OBJ>
+using MATCH_PRED = std::function<bool( const EXP_OBJ&, const FOUND_OBJ& )>;
+
 /**
  * Check that a container of "found" objects matches a container of "expected"
  * objects. This means that:
@@ -91,7 +114,7 @@ namespace KI_TEST
  * and a function to check if a given "found" object corresponds to a given
  * "expected object". Conditions:
  *
- * * The expected object type needs operator<<
+ * * The expected object type needs `operator<<` (for logging)
  * * The expected object container does not contain multiple references to the
  *   same object.
  * * Identical values are also can't be present as the predicate can't tell which
@@ -105,16 +128,15 @@ namespace KI_TEST
  * lists and checking element-by-element matches. However, it can tell you
  * exactly which objects are problematic, as well as a simple go/no-go.
  *
+ * When you have two containers of identical types (or you have a suitable
+ * `operator==`) and ordering is important, you can use `BOOST_CHECK_EQUAL_COLLECTIONS`
+ *
  *@param aExpected  a container of "expected" items, usually from a test case
  *@param aMatched   a container of "found" items, usually the result of some
  *                  routine under test
  *@param aMatchPredicate a predicate that determines if a given "found" object
  *                  matches a given "expected" object.
  */
-template <typename EXP_CONT> using EXP_OBJ = typename EXP_CONT::value_type;
-template <typename FOUND_CONT> using FOUND_OBJ = typename FOUND_CONT::value_type;
-template <typename EXP_OBJ, typename FOUND_OBJ>
-using MATCH_PRED = std::function<bool( const EXP_OBJ&, const FOUND_OBJ& )>;
 template <typename EXP_CONT, typename FOUND_CONT, typename MATCH_PRED>
 void CheckUnorderedMatches(
         const EXP_CONT& aExpected, const FOUND_CONT& aFound, MATCH_PRED aMatchPredicate )