README.txt
1 README FOR IDLE TESTS IN IDLELIB.IDLE_TEST 2 3 0. Quick Start 4 5 Automated unit tests were added in 3.3 for Python 3.x. 6 To run the tests from a command line: 7 8 python -m test.test_idle 9 10 Human-mediated tests were added later in 3.4. 11 12 python -m idlelib.idle_test.htest 13 14 15 1. Test Files 16 17 The idle directory, idlelib, has over 60 xyz.py files. The idle_test 18 subdirectory should contain a test_xyz.py for each, where 'xyz' is 19 lowercased even if xyz.py is not. Here is a possible template, with the 20 blanks after '.' and 'as', and before and after '_' to be filled in. 21 22 import unittest 23 from test.support import requires 24 import idlelib. as 25 26 class _Test(unittest.TestCase): 27 28 def test_(self): 29 30 if __name__ == '__main__': 31 unittest.main(verbosity=2) 32 33 Add the following at the end of xyy.py, with the appropriate name added 34 after 'test_'. Some files already have something like this for htest. 35 If so, insert the import and unittest.main lines before the htest lines. 36 37 if __name__ == "__main__": 38 import unittest 39 unittest.main('idlelib.idle_test.test_', verbosity=2, exit=False) 40 41 42 43 2. GUI Tests 44 45 When run as part of the Python test suite, Idle GUI tests need to run 46 test.support.requires('gui'). A test is a GUI test if it creates a 47 tkinter.Tk root or master object either directly or indirectly by 48 instantiating a tkinter or idle class. GUI tests cannot run in test 49 processes that either have no graphical environment available or are not 50 allowed to use it. 51 52 To guard a module consisting entirely of GUI tests, start with 53 54 from test.support import requires 55 requires('gui') 56 57 To guard a test class, put "requires('gui')" in its setUpClass function. 58 59 To avoid interfering with other GUI tests, all GUI objects must be destroyed and 60 deleted by the end of the test. The Tk root created in a setUpX function should 61 be destroyed in the corresponding tearDownX and the module or class attribute 62 deleted. Others widgets should descend from the single root and the attributes 63 deleted BEFORE root is destroyed. See https://bugs.python.org/issue20567. 64 65 @classmethod 66 def setUpClass(cls): 67 requires('gui') 68 cls.root = tk.Tk() 69 cls.text = tk.Text(root) 70 71 @classmethod 72 def tearDownClass(cls): 73 del cls.text 74 cls.root.update_idletasks() 75 cls.root.destroy() 76 del cls.root 77 78 The update_idletasks call is sometimes needed to prevent the following warning 79 either when running a test alone or as part of the test suite (#27196). 80 can't invoke "event" command: application has been destroyed 81 ... 82 "ttk::ThemeChanged" 83 84 Requires('gui') causes the test(s) it guards to be skipped if any of 85 these conditions are met: 86 87 - The tests are being run by regrtest.py, and it was started without 88 enabling the "gui" resource with the "-u" command line option. 89 90 - The tests are being run on Windows by a service that is not allowed 91 to interact with the graphical environment. 92 93 - The tests are being run on Linux and X Windows is not available. 94 95 - The tests are being run on Mac OSX in a process that cannot make a 96 window manager connection. 97 98 - tkinter.Tk cannot be successfully instantiated for some reason. 99 100 - test.support.use_resources has been set by something other than 101 regrtest.py and does not contain "gui". 102 103 Tests of non-GUI operations should avoid creating tk widgets. Incidental 104 uses of tk variables and messageboxes can be replaced by the mock 105 classes in idle_test/mock_tk.py. The mock text handles some uses of the 106 tk Text widget. 107 108 109 3. Running Unit Tests 110 111 Assume that xyz.py and test_xyz.py both end with a unittest.main() call. 112 Running either from an Idle editor runs all tests in the test_xyz file 113 with the version of Python running Idle. Test output appears in the 114 Shell window. The 'verbosity=2' option lists all test methods in the 115 file, which is appropriate when developing tests. The 'exit=False' 116 option is needed in xyx.py files when an htest follows. 117 118 The following command lines also run all test methods, including 119 GUI tests, in test_xyz.py. (Both '-m idlelib' and '-m idlelib.idle' 120 start Idle and so cannot run tests.) 121 122 python -m idlelib.xyz 123 python -m idlelib.idle_test.test_xyz 124 125 The following runs all idle_test/test_*.py tests interactively. 126 127 >>> import unittest 128 >>> unittest.main('idlelib.idle_test', verbosity=2) 129 130 The following run all Idle tests at a command line. Option '-v' is the 131 same as 'verbosity=2'. 132 133 python -m unittest -v idlelib.idle_test 134 python -m test -v -ugui test_idle 135 python -m test.test_idle 136 137 The idle tests are 'discovered' by 138 idlelib.idle_test.__init__.load_tests, which is also imported into 139 test.test_idle. Normally, neither file should be changed when working on 140 individual test modules. The third command runs unittest indirectly 141 through regrtest. The same happens when the entire test suite is run 142 with 'python -m test'. So that command must work for buildbots to stay 143 green. Idle tests must not disturb the environment in a way that makes 144 other tests fail (issue 18081). 145 146 To run an individual Testcase or test method, extend the dotted name 147 given to unittest on the command line. 148 149 python -m unittest -v idlelib.idle_test.test_xyz.Test_case.test_meth 150 151 152 4. Human-mediated Tests 153 154 Human-mediated tests are widget tests that cannot be automated but need 155 human verification. They are contained in idlelib/idle_test/htest.py, 156 which has instructions. (Some modules need an auxiliary function, 157 identified with "# htest # on the header line.) The set is about 158 complete, though some tests need improvement. To run all htests, run the 159 htest file from an editor or from the command line with: 160 161 python -m idlelib.idle_test.htest 162
