[SPARK-54450][INFRA] Allow run-tests to accept unittest style string for test names

### What changes were proposed in this pull request?

Allow `run-tests` to take unittest style string like `test_module.TestClass.test_case`, in addition to `test_module TestClass.test_case`.

Also some extra check is added for the existence of the test module - we are not sending it to `bin/pyspark` if we can't find the module.

### Why are the changes needed?

It's extra work to split the string when copy/paste directly from unittest output (CI failures for example).

### Does this PR introduce _any_ user-facing change?

No

### How was this patch tested?

Manually confirmed the `.` connection works and the original way is not impacted (except that we have some new checks for the module).

### Was this patch authored or co-authored using generative AI tooling?

No.

Closes #53157 from gaogaotiantian/improve-run-test.

Authored-by: Tian Gao <[email protected]>
Signed-off-by: Ruifeng Zheng <[email protected]>

Author: gaogaotiantian

python/docs/source/development/testing.rst

@@ -36,6 +36,13 @@ After that, the PySpark test cases can be run via using ``python/run-tests``. Fo
 
     python/run-tests --python-executable=python3
 
+You can run individual tests by using ``--testnames`` option. For example,
+
+.. code-block:: bash
+
+    python/run-tests --testnames pyspark.sql.tests.test_dataframe
+    python/run-tests --testnames pyspark.sql.tests.test_dataframe.DataFrameTests.test_range
+
 Note that you may set ``OBJC_DISABLE_INITIALIZE_FORK_SAFETY`` environment variable to ``YES`` if you are running tests on Mac OS.
 
 Please see the guidance on how to |building_spark|_,

python/run-tests.py

@@ -20,6 +20,7 @@
 import logging
 from argparse import ArgumentParser
 import os
+import importlib
 import platform
 import re
 import shutil
@@ -224,6 +225,42 @@ def get_default_python_executables():
     return python_execs
 
 
+def split_and_validate_testnames(testnames):
+    testnames_to_test = []
+
+    def module_exists(module):
+        try:
+            return importlib.util.find_spec(module) is not None
+        except ModuleNotFoundError:
+            return False
+
+    for testname in testnames.split(','):
+        if " " in testname:
+            # "{module} {class.testcase_name}"
+            module, testcase = testname.split(" ")
+            if not module_exists(module):
+                print(f"Error: Can't find module '{module}'.")
+                sys.exit(-1)
+            testnames_to_test.append(f"{module} {testcase}")
+        else:
+            if module_exists(testname):
+                # "{module}"
+                testnames_to_test.append(testname)
+            else:
+                # "{module.class.testcase_name}"
+                index = len(testname)
+                while (index := testname.rfind(".", 0, index)) != -1:
+                    module, testcase = testname[:index], testname[index + 1:]
+                    if module_exists(module):
+                        testnames_to_test.append(f"{module} {testcase}")
+                        break
+                else:
+                    print(f"Error: Invalid testname '{testname}'.")
+                    sys.exit(-1)
+
+    return testnames_to_test
+
+
 def parse_opts():
     parser = ArgumentParser(
         prog="run-tests"
@@ -256,6 +293,7 @@ def parse_opts():
             "For example, 'pyspark.sql.foo' to run the module as unittests or doctests, "
             "'pyspark.sql.tests FooTests' to run the specific class of unittests, "
             "'pyspark.sql.tests FooTests.test_foo' to run the specific unittest in the class. "
+            "'pyspark.sql.tests.FooTests.test_foo' will work too. "
             "'--modules' option is ignored if they are given.")
     )
     group.add_argument(
@@ -312,7 +350,7 @@ def main():
                 sys.exit(-1)
         LOGGER.info("Will test the following Python modules: %s", [x.name for x in modules_to_test])
     else:
-        testnames_to_test = opts.testnames.split(',')
+        testnames_to_test = split_and_validate_testnames(opts.testnames)
         LOGGER.info("Will test the following Python tests: %s", testnames_to_test)
 
     task_queue = Queue.PriorityQueue()