Merge pull request #1486 from nunit/issue-1359

Add info about @file to help options; refactor ShowHelp()

Author: CharliePoole

src/NUnitConsole/nunit3-console/ColorConsole.cs

@@ -39,6 +39,11 @@ public static ConsoleColor GetColor(ColorStyle style)
             return color;
         }
 
+        public static void SetForeground(ColorStyle style)
+        {
+            Console.ForegroundColor = GetColorForStyle(style);
+        }
+
         private static ConsoleColor GetColorForStyle(ColorStyle style)
         {
             switch (Console.BackgroundColor)

src/NUnitConsole/nunit3-console/Options/Options.cs

@@ -1352,8 +1352,9 @@ public void WriteOptionDescriptions(TextWriter o)
                     o.Write(new string(' ', OptionWidth));
                 }
 
-                WriteDescription(o, p.Description, new string(' ', OptionWidth + 2),
+                WriteDescription(o, p.Description, new string(' ', OptionWidth),
                         Description_FirstWidth, Description_RemWidth);
+                o.WriteLine();
             }
 
             foreach (ArgumentSource s in sources)
@@ -1406,7 +1407,7 @@ void WriteDescription(TextWriter o, string value, string prefix, int firstWidth,
             {
                 if (indent)
                     o.Write(prefix);
-                o.WriteLine(line);
+                o.WriteLine(line.Trim());
                 indent = true;
             }
         }

src/NUnitConsole/nunit3-console/Program.cs

@@ -2,9 +2,11 @@
 
 using System;
 using System.Diagnostics;
+using System.Drawing;
 using System.Globalization;
 using System.IO;
 using System.Linq;
+using System.Linq.Expressions;
 using System.Reflection;
 using System.Text;
 
@@ -189,102 +191,115 @@ private static void WriteHelpText()
             OutWriter.WriteLine(ColorStyle.Header, "NUNIT3-CONSOLE [inputfiles] [options]");
             OutWriter.WriteLine();
             OutWriter.WriteLine(ColorStyle.SectionHeader, "Description:");
-            using (new ColorConsole(ColorStyle.Default))
-            {
 #if NETFRAMEWORK
-                OutWriter.WriteLine("      The standard NUnit Console Runner runs a set of NUnit tests from the");
-                OutWriter.WriteLine("      console command-line. By default, all tests are run using separate agents");
-                OutWriter.WriteLine("      for each test assembly. This allows each assembly to run independently");
-                OutWriter.WriteLine("      and allows each assembly to run under the appropriate target runtime.");
+            OutWriter.WriteLine(ColorStyle.Default, """
+                  The standard NUnit Console Runner runs a set of NUnit tests from the
+                  console command-line. By default, all tests are run using separate agents
+                  for each test assembly. This allows each assembly to run independently
+                  and allows each assembly to run under the appropriate target runtime.
+
+            """);
 #else
-                OutWriter.WriteLine("      The NetCore Console Runner runs a set of NUnit tests from the console");
-                OutWriter.WriteLine("      command-line. All tests are run in-process and therefore execute under");
-                OutWriter.WriteLine("      the same runtime as the runner itself. A number of options supported by");
-                OutWriter.WriteLine("      the standard console runner are not available using the NetCore runner.");
-                OutWriter.WriteLine("      See \"Limitations\" below for more information.");
+            OutWriter.WriteLine(ColorStyle.Default, """
+                  The NetCore Console Runner runs a set of NUnit tests from the console
+                  command-line. All tests are run in-process and therefore execute under
+                  the same runtime as the runner itself. A number of options supported by
+                  the standard console runner are not available using the NetCore runner.
+                  See \"Limitations\" below for more information.
+
+            """);
 #endif
-            }
-            OutWriter.WriteLine();
             OutWriter.WriteLine(ColorStyle.SectionHeader, "InputFiles:");
             OutWriter.WriteLine(ColorStyle.Default, "      One or more assemblies or test projects of a recognized type.");
             OutWriter.WriteLine();
             OutWriter.WriteLine(ColorStyle.SectionHeader, "Options:");
             using (new ColorConsole(ColorStyle.Default))
             {
+                OutWriter.WriteLine("""
+                      @FILE                  Specifies the name(or path) of a FILE containing
+                                             additional command-line arguments to be inserted
+                                             at the point where the @FILE expression appears.
+                                             Each line in the file represents one argument
+                                             to the console runner. If an option takes a value,
+                                             that value must appear on the  same line.
+                
+                """);
+
                 Options.WriteOptionDescriptions(Console.Out);
             }
             OutWriter.WriteLine();
             OutWriter.WriteLine(ColorStyle.SectionHeader, "Operation:");
-            using (new ColorConsole(ColorStyle.Default))
-            {
-                OutWriter.WriteLine("      By default, this command runs the tests contained in the");
-                OutWriter.WriteLine("      assemblies and projects specified. If the --explore option");
-                OutWriter.WriteLine("      is used, no tests are executed but a description of the tests");
-                OutWriter.WriteLine("      is saved in the specified or default format.");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      The --where option is intended to extend or replace the earlier");
-                OutWriter.WriteLine("      --test, --include and --exclude options by use of a selection expression");
-                OutWriter.WriteLine("      describing exactly which tests to use. Examples of usage are:");
-                OutWriter.WriteLine("          --where:cat==Data");
-                OutWriter.WriteLine("          --where \"method =~ /DataTest*/ && cat = Slow\"");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      Care should be taken in combining --where with --test or --testlist.");
-                OutWriter.WriteLine("      The test and where specifications are implicitly joined using &&, so");
-                OutWriter.WriteLine("      that BOTH sets of criteria must be satisfied in order for a test to run.");
-                OutWriter.WriteLine("      See the docs for more information and a full description of the syntax");
-                OutWriter.WriteLine("      information and a full description of the syntax.");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      Several options that specify processing of XML output take");
-                OutWriter.WriteLine("      an output specification as a value. A SPEC may take one of");
-                OutWriter.WriteLine("      the following forms:");
-                OutWriter.WriteLine("          --OPTION:filename");
-                OutWriter.WriteLine("          --OPTION:filename;format=formatname");
-                OutWriter.WriteLine("          --OPTION:filename;transform=xsltfile");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      The --result option may use any of the following formats:");
-                OutWriter.WriteLine("          nunit3 - the native XML format for NUnit 3");
-                OutWriter.WriteLine("          nunit2 - legacy XML format used by earlier releases of NUnit");
-                OutWriter.WriteLine("                   Requires the engine extension NUnitV2ResultWriter.");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      The --explore option may use any of the following formats:");
-                OutWriter.WriteLine("          nunit3 - the native XML format for NUnit 3");
-                OutWriter.WriteLine("          cases  - a text file listing the full names of all test cases.");
-                OutWriter.WriteLine("      If --explore is used without any specification following, a list of");
-                OutWriter.WriteLine("      test cases is output to the writer.");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      If none of the options {--result, --explore, --noresult} is used,");
-                OutWriter.WriteLine("      NUnit saves the results to TestResult.xml in nunit3 format.");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      Any transforms provided must handle input in the native nunit3 format.");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      To be able to load NUnit projects, file type .nunit, the engine");
-                OutWriter.WriteLine("      extension NUnitProjectLoader is required. For Visual Studio projects");
-                OutWriter.WriteLine("      and solutions the engine extension VSProjectLoader is required.");
+            OutWriter.WriteLine(ColorStyle.Default, """
+                    By default, this command runs the tests contained in the");
+                    assemblies and projects specified. If the --explore option");
+                    is used, no tests are executed but a description of the tests");
+                    is saved in the specified or default format.
+
+                    The --where option is intended to extend or replace the earlier
+                    --test, --include and --exclude options by use of a selection expression
+                    describing exactly which tests to use. Examples of usage are:
+                        --where:cat==Data
+                        --where \"method =~ /DataTest*/ && cat = Slow\"
+                
+                    Care should be taken in combining --where with --test or --testlist.
+                    The test and where specifications are implicitly joined using &&, so
+                    that BOTH sets of criteria must be satisfied in order for a test to run.
+                    See the docs for more information and a full description of the syntax
+                    information and a full description of the syntax.
+                
+                    Several options that specify processing of XML output take
+                    an output specification as a value. A SPEC may take one of
+                    the following forms:
+                        --OPTION:filename
+                        --OPTION:filename;format=formatname
+                        --OPTION:filename;transform=xsltfile
+                
+                    The --result option may use any of the following formats
+                        nunit3 - the native XML format for NUnit 3
+                        nunit2 - legacy XML format used by earlier releases of NUnit
+                                Requires the engine extension NUnitV2ResultWriter.
+                
+                    The --explore option may use any of the following formats:
+                        nunit3 - the native XML format for NUnit 3
+                        cases  - a text file listing the full names of all test cases.
+                    If --explore is used without any specification following, a list of
+                    test cases is output to the writer.
+                
+                    If none of the options {--result, --explore, --noresult} is used,
+                    NUnit saves the results to TestResult.xml in nunit3 format.
+                
+                    Any transforms provided must handle input in the native nunit3 format.
+                
+                    To be able to load NUnit projects, file type .nunit, the engine
+                    extension NUnitProjectLoader is required. For Visual Studio projects
+                    and solutions the engine extension VSProjectLoader is required.
+            """);
 #if NETCOREAPP
-                OutWriter.WriteLine();
-                OutWriter.WriteLine(ColorStyle.SectionHeader, "Limitations:");
-                OutWriter.WriteLine("      The NetCore Runner is primarily intended for use as a dotnet  tool.");
-                OutWriter.WriteLine("      When used in this way, a single assembly is usually being tested and");
-                OutWriter.WriteLine("      the assembly must be compatible with execution under the same runtime");
-                OutWriter.WriteLine("      as the runner itself, normally .NET 6.0.");
-                OutWriter.WriteLine();
-                OutWriter.WriteLine("      Using this runner, the following options are not available. A brief");
-                OutWriter.WriteLine("      rationale is given for each option excluded.");
-                OutWriter.WriteLine("        --configFile              Config of the runner itself is used.");
-                OutWriter.WriteLine("        --process                 Not designed to run out of process.");
-                OutWriter.WriteLine("        --inprocess               Redundant. We always run in process.");
-                OutWriter.WriteLine("        --domain                  Not applicable to .NET Core.");
-                OutWriter.WriteLine("        --framework               Runtime of the runner is used.");
-                OutWriter.WriteLine("        --x86                     Bitness of the runner is used.");
-                OutWriter.WriteLine("        --shadowcopy              Not available.");
-                OutWriter.WriteLine("        --loaduserprofile         Not available.");
-                OutWriter.WriteLine("        --agents                  No agents are used.");
-                OutWriter.WriteLine("        --debug                   Debug in process directly.");
-                OutWriter.WriteLine("        --pause                   Used for debugging agents.");
-                OutWriter.WriteLine("        --set-principal-policy    Not available.");
-                OutWriter.WriteLine("        --debug-agent             No agents are used.");
+            OutWriter.WriteLine();
+            OutWriter.WriteLine(ColorStyle.SectionHeader, "Limitations:");
+            OutWriter.WriteLine(ColorStyle.Default, """
+                    The NetCore Runner is primarily intended for use as a dotnet  tool.
+                    When used in this way, a single assembly is usually being tested and
+                    the assembly must be compatible with execution under the same runtime
+                    as the runner itself, normally .NET 6.0.
+                
+                    Using this runner, the following options are not available. A brief
+                    rationale is given for each option excluded.
+                    --configFile              Config of the runner itself is used.
+                    --process                 Not designed to run out of process.
+                    --inprocess               Redundant. We always run in process.
+                    --domain                  Not applicable to .NET Core.
+                    --framework               Runtime of the runner is used.
+                    --x86                     Bitness of the runner is used.
+                    --shadowcopy              Not available.
+                    --loaduserprofile         Not available.
+                    --agents                  No agents are used.
+                    --debug                   Debug in process directly.
+                    --pause                   Used for debugging agents.
+                    --set-principal-policy    Not available.
+                    --debug-agent             No agents are used.
+            """);
 #endif
-            }
         }
 
         private static void CancelHandler(object sender, ConsoleCancelEventArgs args)