|
1 | 1 | """Run human tests of Idle's window, dialog, and popup widgets. |
2 | 2 |
|
3 | | -run(*tests) Create a master Tk() htest window. Within that, run each |
4 | | -callable in tests after finding the matching test spec in this file. If |
5 | | -tests is empty, run an htest for each spec dict in this file after |
6 | | -finding the matching callable in the module named in the spec. Close |
7 | | -the master window to end testing. |
8 | | -
|
9 | | -In a tested module, let X be a global name bound to a callable (class or |
10 | | -function) whose .__name__ attribute is also X (the usual situation). The |
11 | | -first parameter of X must be 'parent' or 'master'. When called, the |
12 | | -first argument will be the root window. X must create a child |
13 | | -Toplevel(parent/master) (or subclass thereof). The Toplevel may be a |
14 | | -test widget or dialog, in which case the callable is the corresponding |
15 | | -class. Or the Toplevel may contain the widget to be tested or set up a |
16 | | -context in which a test widget is invoked. In this latter case, the |
17 | | -callable is a wrapper function that sets up the Toplevel and other |
18 | | -objects. Wrapper function names, such as _editor_window', should start |
19 | | -with '_' and be lowercase. |
20 | | -
|
| 3 | +The main function, `run(*tests)`, is defined at the end of this file. |
| 4 | +Argument `tests` is a possibly empty tuple of callables defined in some |
| 5 | +idlelib.abc module (or possibly modules). Its steps: |
| 6 | +1. Create a master Tk() htest window. Within that window ... |
| 7 | +2a. If tuple `tests` is not empty, run was likely called from one |
| 8 | + module. Run each callable in `tests` after finding the matching |
| 9 | + callable_spec test spec in this file. |
| 10 | +2b. If tests is empty, run was likely called from this file. |
| 11 | + Run an htest for each spec dict in this file after finding the |
| 12 | + matching callable in the module named in the spec. |
| 13 | +3. Close the master window to end testing. |
| 14 | +
|
| 15 | +In a tested module, let X be a global name bound to a callable (class |
| 16 | +or function) whose .__name__ attribute (its `class` or `def` definition |
| 17 | +name) is also X. X must expect exactly 1 positional argument, a |
| 18 | +parent toplevel window. Run passes the htest window. X must create a |
| 19 | +child Toplevel(parent/master). The callable may be either a runtime |
| 20 | +object or a wrapper function written just for the test. In the latter |
| 21 | +case, its name should start with '_' and be lowercase (such as '_ttt'). |
21 | 22 |
|
22 | 23 | End the module with |
23 | | -
|
| 24 | +``` |
24 | 25 | if __name__ == '__main__': |
25 | | - <run unittest.main with 'exit=False'> |
| 26 | + from unittest import main |
| 27 | + main("idlelib.idle_test.test_xyz", verbosity=2, exit=False) |
| 28 | +
|
26 | 29 | from idlelib.idle_test.htest import run |
27 | | - run(callable) # There could be multiple comma-separated callables. |
| 30 | + run(callable) |
| 31 | +``` |
| 32 | +Replace 'xyz' as appropriate and 'callable' with the callable name or |
| 33 | +comma-separated names (multiple names is rare). 'exit=False' is needed |
| 34 | +for the htest to run. |
28 | 35 |
|
29 | 36 | To have wrapper functions ignored by coverage reports, tag the def |
30 | | -header like so: "def _wrapper(parent): # htest #". Use the same tag |
31 | | -for htest lines in widget code. Make sure that the 'if __name__' line |
32 | | -matches the above. Then have make sure that .coveragerc includes the |
33 | | -following: |
34 | | -
|
| 37 | +header like so: "def _wrapper(root): # htest #". Use the same tag |
| 38 | +for htest-only lines in the main code. To ignore the 'if __name__' |
| 39 | +statement, match the example above. Add the below to coveragerc. |
| 40 | +``` |
35 | 41 | [report] |
36 | 42 | exclude_lines = |
37 | 43 | .*# htest # |
38 | 44 | if __name__ == .__main__.: |
39 | | -
|
40 | | -(The "." instead of "'" is intentional and necessary.) |
41 | | -
|
| 45 | +``` |
42 | 46 |
|
43 | 47 | To run any X, this file must contain a matching instance of the |
44 | 48 | following template, with X.__name__ prepended to '_spec'. |
45 | | -When all tests are run, the prefix is use to get X. |
46 | 49 |
|
47 | 50 | callable_spec = { |
48 | 51 | 'file': '', |
|
51 | 54 | } |
52 | 55 |
|
53 | 56 | file (no .py): run() imports file.py. |
54 | | -kwds: augmented with {'parent':root} and passed to X as **kwds. |
| 57 | +kwds: run() augments with {'parent':root} and passes to X as **kwds. |
55 | 58 | title: an example kwd; some widgets need this, delete line if not. |
56 | 59 | msg: master window hints about testing the widget. |
57 | 60 |
|
58 | | -
|
59 | 61 | TODO test these modules and classes: |
60 | 62 | autocomplete_w.AutoCompleteWindow |
61 | 63 | debugger.Debugger |
|
0 commit comments