[3.11] gh-66819: More IDLE htest updates (GH-112574) (#112576)

Revise htest.py docstring and move 2 specs to alphabetical position.
(cherry picked from commit e44f1940bd)

Co-authored-by: Terry Jan Reedy <tjreedy@udel.edu>

Lib/idlelib/idle_test/htest.py

@@ -1,38 +1,35 @@
-'''Run human tests of Idle's window, dialog, and popup widgets.
+"""Run human tests of Idle's window, dialog, and popup widgets.
 
-run(*tests)
+run(*tests) Create a master Tk() htest window.  Within that, run each
-Create a master Tk window.  Within that, run each callable in tests
+callable in tests after finding the matching test spec in this file.  If
-after finding the matching test spec in this file.  If tests is empty,
+tests is empty, run an htest for each spec dict in this file after
-run an htest for each spec dict in this file after finding the matching
+finding the matching callable in the module named in the spec.  Close
-callable in the module named in the spec.  Close the window to skip or
+the master window to end testing.
-end the test.
 
-In a tested module, let X be a global name bound to a callable (class
+In a tested module, let X be a global name bound to a callable (class or
-or function) whose .__name__ attribute is also X (the usual situation).
+function) whose .__name__ attribute is also X (the usual situation). The
-The first parameter of X must be 'parent'.  When called, the parent
+first parameter of X must be 'parent'.  When called, the parent argument
-argument will be the root window.  X must create a child Toplevel
+will be the root window.  X must create a child Toplevel(parent) window
-window (or subclass thereof).  The Toplevel may be a test widget or
+(or subclass thereof).  The Toplevel may be a test widget or dialog, in
-dialog, in which case the callable is the corresponding class.  Or the
+which case the callable is the corresponding class.  Or the Toplevel may
-Toplevel may contain the widget to be tested or set up a context in
+contain the widget to be tested or set up a context in which a test
-which a test widget is invoked.  In this latter case, the callable is a
+widget is invoked.  In this latter case, the callable is a wrapper
-wrapper function that sets up the Toplevel and other objects.  Wrapper
+function that sets up the Toplevel and other objects.  Wrapper function
-function names, such as _editor_window', should start with '_'.
+names, such as _editor_window', should start with '_' and be lowercase.
 
 
 End the module with
 
 if __name__ == '__main__':
-    <unittest, if there is one>
+    <run unittest.main with 'exit=False'>
     from idlelib.idle_test.htest import run
-    run(X)
+    run(callable)  # There could be multiple comma-separated callables.
 
-To have wrapper functions and test invocation code ignored by coveragepy
+To have wrapper functions ignored by coverage reports, tag the def
-reports, put '# htest #' on the def statement header line.
+header like so: "def _wrapper(parent):  # htest #".  Use the same tag
-
+for htest lines in widget code.  Make sure that the 'if __name__' line
-def _wrapper(parent):  # htest #
+matches the above.  Then have make sure that .coveragerc includes the
-
+following:
-Also make sure that the 'if __name__' line matches the above.  Then have
-make sure that .coveragerc includes the following.
 
 [report]
 exclude_lines =
@@ -46,7 +43,7 @@ def _wrapper(parent):  # htest #
 following template, with X.__name__ prepended to '_spec'.
 When all tests are run, the prefix is use to get X.
 
-_spec = {
+callable_spec = {
     'file': '',
     'kwds': {'title': ''},
     'msg': ""
@@ -54,16 +51,16 @@ def _wrapper(parent):  # htest #
 
 file (no .py): run() imports file.py.
 kwds: augmented with {'parent':root} and passed to X as **kwds.
-title: an example kwd; some widgets need this, delete if not.
+title: an example kwd; some widgets need this, delete line if not.
 msg: master window hints about testing the widget.
 
 
-Modules and classes not being tested at the moment:
+TODO test these modules and classes:
-pyshell.PyShellEditorWindow
+  autocomplete_w.AutoCompleteWindow
-debugger.Debugger
+  debugger.Debugger
-autocomplete_w.AutoCompleteWindow
+  outwin.OutputWindow (indirectly being tested with grep test)
-outwin.OutputWindow (indirectly being tested with grep test)
+  pyshell.PyShellEditorWindow
-'''
+"""
 
 import idlelib.pyshell  # Set Windows DPI awareness before Tk().
 from importlib import import_module
@@ -91,15 +88,6 @@ def _wrapper(parent):  # htest #
            "Force-open-calltip does not work here.\n"
     }
 
-_module_browser_spec = {
-    'file': 'browser',
-    'kwds': {},
-    'msg': "Inspect names of module, class(with superclass if "
-           "applicable), methods and functions.\nToggle nested items.\n"
-           "Double clicking on items prints a traceback for an exception "
-           "that is ignored."
-    }
-
 _color_delegator_spec = {
     'file': 'colorizer',
     'kwds': {},
@@ -109,16 +97,6 @@ def _wrapper(parent):  # htest #
            "The default color scheme is in idlelib/config-highlight.def"
     }
 
-CustomRun_spec = {
-    'file': 'query',
-    'kwds': {'title': 'Customize query.py Run',
-             '_htest': True},
-    'msg': "Enter with <Return> or [Run].  Print valid entry to Shell\n"
-           "Arguments are parsed into a list\n"
-           "Mode is currently restart True or False\n"
-           "Close dialog with valid entry, <Escape>, [Cancel], [X]"
-    }
-
 ConfigDialog_spec = {
     'file': 'configdialog',
     'kwds': {'title': 'ConfigDialogTest',
@@ -135,6 +113,16 @@ def _wrapper(parent):  # htest #
            "changes made have persisted."
     }
 
+CustomRun_spec = {
+    'file': 'query',
+    'kwds': {'title': 'Customize query.py Run',
+             '_htest': True},
+    'msg': "Enter with <Return> or [Run].  Print valid entry to Shell\n"
+           "Arguments are parsed into a list\n"
+           "Mode is currently restart True or False\n"
+           "Close dialog with valid entry, <Escape>, [Cancel], [X]"
+    }
+
 # TODO Improve message
 _dyn_option_menu_spec = {
     'file': 'dynoption',
@@ -236,6 +224,15 @@ def _wrapper(parent):  # htest #
            "focusing out of the window\nare sequences to be tested."
     }
 
+_module_browser_spec = {
+    'file': 'browser',
+    'kwds': {},
+    'msg': "Inspect names of module, class(with superclass if "
+           "applicable), methods and functions.\nToggle nested items.\n"
+           "Double clicking on items prints a traceback for an exception "
+           "that is ignored."
+    }
+
 _multistatus_bar_spec = {
     'file': 'statusbar',
     'kwds': {},