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