diff --git a/docs/internal/running_tests.rst b/docs/internal/running_tests.rst index 54757ba59c..1aed0790da 100644 --- a/docs/internal/running_tests.rst +++ b/docs/internal/running_tests.rst @@ -46,12 +46,14 @@ If it was built as static libraries add ``-ExeSubDir Static_Debug`` or ``-ExeSub Manual Configuration ==================== -Manual configuration is done by passing ``-Config``, ``-Exclude``, and test list files arguments to the script. +Manual configuration is done by passing ``-Config`` and test list files arguments to the script. To manually configure what tests to run: * See the ``--list-all-configs`` or ``--show-all-configs`` options to see the existing configurations used by all test list files. * See the ``--list-configs`` or ``--show-configs`` options to see the existing configurations used by specific test list files. +* ``--list-tests`` lists the tests that would run for the current options. + ``--list-all-tests`` is the same but includes all the known list files. * See the test list files for the tests themselves: * :ghfile:`tests/dcps_tests.lst` @@ -74,9 +76,6 @@ To manually configure what tests to run: * In a test list file each of the-space delimited words after the colon determines when the test is ran. * Passing ``-Config RTPS`` will run tests that have ``RTPS`` and leave out tests with ``!RTPS``. -* Passing ``-Exclude RTPS`` will exclude all tests that have ``RTPS`` in the entry. - This option matches using RegEx, so a test with ``SUPER_DUPER_RTPS`` will also be excluded. - It also ignores inverse entries, so it will not exclude a test with ``!SUPER_DUPER_RTPS``. * There are ``-Config`` options that are added automatically if ``--no-auto-config`` wasn't passed: * ``-Config RTPS`` @@ -87,11 +86,14 @@ To manually configure what tests to run: * ``-Config macOS`` * ``-Config Linux`` +* ``-Exclude`` excludes test paths and arguments (but not the configurations) that match the argument. + Passing ``-Exclude tests/DCPS`` will exclude all tests in :ghfile:`tests/DCPS`. + This option uses RegEx, so passing ``-Exclude tests/(DCPS|FACE)`` will also exclude tests in :ghfile:`tests/FACE`. * Assuming they were built, CMake tests are ran if ``--cmake`` is passed. This uses CTest, which is a system that is separate from the one previously described. * See ``--help`` for all the available options. .. note:: For those editing and creating test list files: - The ``ConfigList`` code in ACE can't properly handle mutiple test list entries with the same command. + The ``ConfigList`` code in ACE can't properly handle multiple test list entries with the same command. It will run all those entries if the last one will run, even if based on the configs only one entry should run. ``auto_run_tests.pl`` will warn about this if it's using a test list file that has this problem. diff --git a/tests/auto_run_tests.pl b/tests/auto_run_tests.pl index 7d1d742af8..3250a0e21e 100755 --- a/tests/auto_run_tests.pl +++ b/tests/auto_run_tests.pl @@ -152,17 +152,16 @@ sub print_help { # These two are processed by PerlACE/ConfigList.pm " -Config Include tests with configuration\n" . - " -Exclude Exclude tests with configuration\n" . - " This is parsed as a Perl regex and will always\n" . - " override -Config regardless of the order\n" . + " -Exclude Excludes tests paths and arguments that match this\n" . + " regex.\n" . # This one is processed by PerlACE/Process.pm " -ExeSubDir Subdirectory for finding the executables\n" . " --sandbox | -s Runs each program using a sandbox program\n" . " --dry-run | -z Do everything except run the tests\n" . - " --show-configs Print possible values for -Config and -Excludes\n" . - " broken down by list file\n" . + " --show-configs Print possible values for -Config broken down by\n" . + " list file\n" . " --show-all-configs Same as --show-configs, but for all list files\n" . " --list-configs Print combined set of the configs from the list\n" . " files\n" .