From 64fb37505b103c5ca773fa990e6f86cea43f779d Mon Sep 17 00:00:00 2001 From: Charlie Poole Date: Thu, 19 Sep 2024 07:46:46 -0700 Subject: [PATCH] Add info about @FILE to help options; refactor ShowHelp() --- .../nunit3-console/ColorConsole.cs | 5 + .../nunit3-console/Options/Options.cs | 5 +- src/NUnitConsole/nunit3-console/Program.cs | 177 ++++++++++-------- 3 files changed, 104 insertions(+), 83 deletions(-) diff --git a/src/NUnitConsole/nunit3-console/ColorConsole.cs b/src/NUnitConsole/nunit3-console/ColorConsole.cs index 84ca437b3..babc890c5 100644 --- a/src/NUnitConsole/nunit3-console/ColorConsole.cs +++ b/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) diff --git a/src/NUnitConsole/nunit3-console/Options/Options.cs b/src/NUnitConsole/nunit3-console/Options/Options.cs index 1d7dc20ce..e85baf5c9 100644 --- a/src/NUnitConsole/nunit3-console/Options/Options.cs +++ b/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; } } diff --git a/src/NUnitConsole/nunit3-console/Program.cs b/src/NUnitConsole/nunit3-console/Program.cs index 827358005..06e8a96b1 100644 --- a/src/NUnitConsole/nunit3-console/Program.cs +++ b/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)