twister: Enhanced Filtering Command Help

Collect filter commands into a single location and sort them in the
order: arch, vendor, platform, pattern, filter, tag. This enhances
the readability of help information and reduces the time spent
searching for filter command options.

Signed-off-by: WenBin Zhang <[email protected]>

Author: Freey0

scripts/pylib/twister/twisterlib/environment.py

@@ -270,40 +270,63 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
         """
     )
 
-    test_or_build.add_argument(
-        "-b",
-        "--build-only",
-        action="store_true",
-        default="--prep-artifacts-for-testing" in sys.argv,
-        help="Only build the code, do not attempt to run the code on targets."
-    )
+    parser.add_argument(
+        "-a", "--arch", action="append",
+        help="Arch filter for testing. Takes precedence over --platform. "
+             "If unspecified, test all arches. Multiple invocations "
+             "are treated as a logical 'or' relationship")
 
-    test_or_build.add_argument(
-        "--prep-artifacts-for-testing", action="store_true",
-        help="Generate artifacts for testing, do not attempt to run the "
-              "code on targets.")
+    parser.add_argument(
+            "--vendor", action="append", default=[],
+            help="Vendor filter for testing")
 
     parser.add_argument(
-        "--package-artifacts",
-        help="Package artifacts needed for flashing in a file to be used with --test-only"
-        )
+        "-p", "--platform", action="append", default=[],
+        help="Platform filter for testing. This option may be used multiple "
+             "times. Test suites will only be built/run on the platforms "
+             "specified. If this option is not used, then platforms marked "
+             "as default in the platform metadata file will be chosen "
+             "to build and test. ")
 
-    test_or_build.add_argument(
-        "--test-only", action="store_true",
-        help="""Only run device tests with current artifacts, do not build
-             the code""")
+    parser.add_argument("-P", "--exclude-platform", action="append", default=[],
+            help="""Exclude platforms and do not build or run any tests
+            on those platforms. This option can be called multiple times.
+            """
+            )
 
-    parser.add_argument("--timeout-multiplier", type=float, default=1,
-        help="""Globally adjust tests timeouts by specified multiplier. The resulting test
-        timeout would be multiplication of test timeout value, board-level timeout multiplier
-        and global timeout multiplier (this parameter)""")
+    parser.add_argument(
+        "--platform-pattern", action="append", default=[],
+        help="""Platform regular expression filter for testing. This option may be used multiple
+        times. Test suites will only be built/run on the platforms
+        matching the specified patterns. If this option is not used, then platforms marked
+        as default in the platform metadata file will be chosen
+        to build and test.
+        """)
 
     parser.add_argument(
         "--test-pattern", action="append",
         help="""Run only the tests matching the specified pattern. The pattern
         can include regular expressions.
         """)
 
+    parser.add_argument(
+        "--filter", choices=['buildable', 'runnable'],
+        default='runnable' if "--device-testing" in sys.argv else 'buildable',
+        help="""Filter tests to be built and executed. By default everything is
+        built and if a test is runnable (emulation or a connected device), it
+        is run. This option allows for example to only build tests that can
+        actually be run. Runnable is a subset of buildable.""")
+
+    parser.add_argument(
+        "-t", "--tag", action="append",
+        help="Specify tags to restrict which tests to run by tag value. "
+             "Default is to not do any tag filtering. Multiple invocations "
+             "are treated as a logical 'or' relationship.")
+
+    parser.add_argument("-e", "--exclude-tag", action="append",
+                        help="Specify tags of tests that should not run. "
+                             "Default is to run all tests with all tags.")
+
     test_xor_subtest.add_argument(
         "-s", "--test", "--scenario", action="append", type = norm_path,
         help="""Run only the specified test suite scenario. These are named by
@@ -326,6 +349,47 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
         Note: With --no-detailed-test-id use only Ztest names without scenario name.
         """)
 
+    parser.add_argument(
+        "-K", "--force-platform", action="store_true",
+        help="""Force testing on selected platforms,
+        even if they are excluded in the test configuration (testcase.yaml)."""
+    )
+
+    parser.add_argument("--ignore-platform-key", action="store_true",
+                        help="Do not filter based on platform key")
+
+    parser.add_argument("--level", action="store",
+        help="Test level to be used. By default, no levels are used for filtering "
+             "and do the selection based on existing filters.")
+
+    test_or_build.add_argument(
+        "-b",
+        "--build-only",
+        action="store_true",
+        default="--prep-artifacts-for-testing" in sys.argv,
+        help="Only build the code, do not attempt to run the code on targets."
+    )
+
+    test_or_build.add_argument(
+        "--prep-artifacts-for-testing", action="store_true",
+        help="Generate artifacts for testing, do not attempt to run the "
+              "code on targets.")
+
+    parser.add_argument(
+        "--package-artifacts",
+        help="Package artifacts needed for flashing in a file to be used with --test-only"
+        )
+
+    test_or_build.add_argument(
+        "--test-only", action="store_true",
+        help="""Only run device tests with current artifacts, do not build
+             the code""")
+
+    parser.add_argument("--timeout-multiplier", type=float, default=1,
+        help="""Globally adjust tests timeouts by specified multiplier. The resulting test
+        timeout would be multiplication of test timeout value, board-level timeout multiplier
+        and global timeout multiplier (this parameter)""")
+
     parser.add_argument(
         "--pytest-args", action="append",
         help="""Pass additional arguments to the pytest subprocess. This parameter
@@ -375,12 +439,6 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
         help="Allow to use pytest plugin installed by pip for pytest tests."
     )
 
-    parser.add_argument(
-        "-a", "--arch", action="append",
-        help="Arch filter for testing. Takes precedence over --platform. "
-             "If unspecified, test all arches. Multiple invocations "
-             "are treated as a logical 'or' relationship")
-
     parser.add_argument(
         "-B", "--subset",
         help="Only run a subset of the tests, 1/4 for running the first 25%%, "
@@ -461,20 +519,12 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
         help="Path to file with plans and test configurations."
     )
 
-    parser.add_argument("--level", action="store",
-        help="Test level to be used. By default, no levels are used for filtering "
-             "and do the selection based on existing filters.")
-
     parser.add_argument(
         "--disable-suite-name-check", action="store_true", default=False,
         help="Disable extended test suite name verification at the beginning "
              "of Ztest test. This option could be useful for tests or "
              "platforms, which from some reasons cannot print early logs.")
 
-    parser.add_argument("-e", "--exclude-tag", action="append",
-                        help="Specify tags of tests that should not run. "
-                             "Default is to run all tests with all tags.")
-
     parser.add_argument(
         "--enable-lsan", action="store_true",
         help="""Enable leak sanitizer to check for heap memory leaks.
@@ -491,14 +541,6 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
         binaries such as those generated for the native_sim configuration.
         """)
 
-    parser.add_argument(
-        "--filter", choices=['buildable', 'runnable'],
-        default='runnable' if "--device-testing" in sys.argv else 'buildable',
-        help="""Filter tests to be built and executed. By default everything is
-        built and if a test is runnable (emulation or a connected device), it
-        is run. This option allows for example to only build tests that can
-        actually be run. Runnable is a subset of buildable.""")
-
     parser.add_argument("--force-color", action="store_true",
                         help="Always output ANSI color escape sequences "
                              "even when the output is redirected (not a tty)")
@@ -587,20 +629,11 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
         help="Upon test failure, print relevant log data to stdout "
              "instead of just a path to it.")
 
-    parser.add_argument("--ignore-platform-key", action="store_true",
-                        help="Do not filter based on platform key")
-
     parser.add_argument(
         "-j", "--jobs", type=int,
         help="Number of jobs for building, defaults to number of CPU threads, "
              "overcommitted by factor 2 when --build-only.")
 
-    parser.add_argument(
-        "-K", "--force-platform", action="store_true",
-        help="""Force testing on selected platforms,
-        even if they are excluded in the test configuration (testcase.yaml)."""
-    )
-
     parser.add_argument(
         "-l", "--all", action="store_true",
         help="Build/test on all platforms. Any --platform arguments "
@@ -696,32 +729,6 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
     parser.add_argument("--report-filtered", action="store_true",
                         help="Include filtered tests in the reports.")
 
-    parser.add_argument("-P", "--exclude-platform", action="append", default=[],
-            help="""Exclude platforms and do not build or run any tests
-            on those platforms. This option can be called multiple times.
-            """
-            )
-
-    parser.add_argument(
-            "--vendor", action="append", default=[],
-            help="Vendor filter for testing")
-
-    parser.add_argument(
-        "-p", "--platform", action="append", default=[],
-        help="Platform filter for testing. This option may be used multiple "
-             "times. Test suites will only be built/run on the platforms "
-             "specified. If this option is not used, then platforms marked "
-             "as default in the platform metadata file will be chosen "
-             "to build and test. ")
-    parser.add_argument(
-        "--platform-pattern", action="append", default=[],
-        help="""Platform regular expression filter for testing. This option may be used multiple
-        times. Test suites will only be built/run on the platforms
-        matching the specified patterns. If this option is not used, then platforms marked
-        as default in the platform metadata file will be chosen
-        to build and test.
-        """)
-
     parser.add_argument(
         "--platform-reports", action="store_true",
         help="""Create individual reports for each platform.
@@ -808,12 +815,6 @@ def add_parse_arguments(parser = None) -> argparse.ArgumentParser:
              "example on Windows OS. This option can be used only with "
              "'--ninja' argument (to use Ninja build generator).")
 
-    parser.add_argument(
-        "-t", "--tag", action="append",
-        help="Specify tags to restrict which tests to run by tag value. "
-             "Default is to not do any tag filtering. Multiple invocations "
-             "are treated as a logical 'or' relationship.")
-
     parser.add_argument("--timestamps",
                         action="store_true",
                         help="Print all messages with time stamps.")