diff -r a4b66e51e0bf Lib/idlelib/idle_test/README.txt --- a/Lib/idlelib/idle_test/README.txt Mon Apr 13 22:11:34 2015 +0200 +++ b/Lib/idlelib/idle_test/README.txt Wed Apr 15 09:31:26 2015 -0400 @@ -1,50 +1,65 @@ README FOR IDLE TESTS IN IDLELIB.IDLE_TEST +0. Instant User's Manual + +The IDLE tests were added in 2.7 for Python 2.x and 3.3 for Python 3.x. Run the +tests from the command line: + + python -m test.test_idle + + 1. Test Files -The idle directory, idlelib, has over 60 xyz.py files. The idle_test -subdirectory should contain a test_xyy.py for each. (For test modules, make -'xyz' lower case, and possibly shorten it.) Each file should start with the -something like the following template, with the blanks after after '.' and 'as', -and before and after '_' filled in. +The idlelib folder has over 60 "xyz.py" files. The idlelib/idle_test folder +should contain a "test_xyz.py" for each. Here is a suggested template (replace +the marks appropriately): + --- -import unittest -from test.support import requires -import idlelib. as + import unittest + from test.support import requires + import idlelib. as -class _Test(unittest.TestCase): + class Test(unittest.TestCase): - def test_(self): + def test_(self): -if __name__ == '__main__': - unittest.main(verbosity=2, exit=2) + if __name__ == '__main__': + unittest.main(verbosity=2, exit=2) --- -Idle tests are run with unittest; do not use regrtest's test_main. -Once test_xyy is written, the following should go at the end of xyy.py, -with xyz (lowercased) added after 'test_'. +Use unittest to run Idle tests, not regrtest's test_main. + +Add the following to the end of xyy.py (with the appropriate name for +"test_xyz"). + --- -if __name__ == "__main__": - import unittest - unittest.main('idlelib.idle_test.test_', verbosity=2, exit=False) + if __name__ == "__main__": + import unittest + unittest.main('idlelib.idle_test.test_xyz', verbosity=2, exit=False) --- 2. Gui Tests -Gui tests need 'requires' from test.support (test.test_support in 2.7). A -test is a gui test if it creates a Tk root or master object either directly -or indirectly by instantiating a tkinter or idle class. For the benefit of -test processes that either have no graphical environment available or are not -allowed to use it, gui tests must be 'guarded' by "requires('gui')" in a -setUp function or method. This will typically be setUpClass. +Gui tests need test.support.requires() (test.test_support in 2.7). A test is a +gui test if it creates a Tk root or master object either directly or indirectly +by instantiating a tkinter or idle class. For the benefit of test processes that +either have no graphical environment available or are not allowed to use it, gui +tests must be 'guarded' by "requires('gui')" in a setUp function or method. This +will typically be setUpClass. -To avoid interfering with other gui tests, all gui objects must be destroyed -and deleted by the end of the test. If a widget, such as a Tk root, is created -in a setUpX function, destroy it in the corresponding tearDownX. For module -and class attributes, also delete the widget. +To avoid interfering with other gui tests, all gui objects must be destroyed and +deleted by the end of the test. If you create a widget, such as a Tk root, in a +setUp()/setUpClass()/setUpModule() function, destroy it in the corresponding +tearDown function. For module and class attributes, also delete the widget. + +For example: + --- + from test.support import requires # (test.test_support in 2.7) + + @classmethod def setUpClass(cls): requires('gui') @@ -56,60 +71,74 @@ del cls.root --- -Support.requires('gui') causes the test(s) it guards to be skipped if any of -a few conditions are met: +requires('gui') causes the test(s) it guards to be skipped if any of these +conditions are met: + - The tests are being run by regrtest.py, and it was started without enabling the "gui" resource with the "-u" command line option. + - The tests are being run on Windows by a service that is not allowed to interact with the graphical environment. + - The tests are being run on Mac OSX in a process that cannot make a window manager connection. + - tkinter.Tk cannot be successfully instantiated for some reason. + - test.support.use_resources has been set by something other than regrtest.py and does not contain "gui". -Since non-gui tests always run, but gui tests only sometimes, tests of non-gui -operations should best avoid needing a gui. Methods that make incidental use of -tkinter (tk) variables and messageboxes can do this by using the mock classes in -idle_test/mock_tk.py. There is also a mock text that will handle some uses of the -tk Text widget. +Non-gui test operations should avoid requiring a gui. Methods with incidental +use of tkinter (e.g. message boxes) can use the mock classes in +idle_test/mock_tk.py. There is also a mock text that will handle some uses of +the tk Text widget. 3. Running Tests -Assume that xyz.py and test_xyz.py end with the "if __name__" statements given -above. In Idle, pressing F5 in an editor window with either loaded will run all -tests in the test_xyz file with the version of Python running Idle. The test -report and any tracebacks will appear in the Shell window. The options in these -"if __name__" statements are appropriate for developers running (as opposed to -importing) either of the files during development: verbosity=2 lists all test -methods in the file; exit=False avoids a spurious sys.exit traceback that would -otherwise occur when running in Idle. The following command lines also run -all test methods, including gui tests, in test_xyz.py. (The exceptions are that -idlelib and idlelib.idle start Idle and idlelib.PyShell should (issue 18330).) +Assume that "xyz.py" and "test_xyz.py" end with the unittest.main() call. Either +.py file can be opened and run from Idle with the version of Python running +Idle. The test report and any tracebacks will appear in the Shell window. The +options in these "if __name__" statements are appropriate for developers running +(as opposed to importing) either of the files during development: verbosity=2 +lists all test methods in the file; exit=False avoids a spurious sys.exit +traceback that would otherwise occur when running in Idle. The following command +lines also run all test methods, including gui tests, in test_xyz.py. (The +exceptions are that idlelib and idlelib.idle start Idle and idlelib.PyShell +should (issue 18330).) -python -m idlelib.xyz # With the capitalization of the xyz module -python -m idlelib.idle_test.test_xyz + python -m idlelib.xyz # With the capitalization of the xyz module + python -m idlelib.idle_test.test_xyz -To run all idle_test/test_*.py tests, either interactively -('>>>', with unittest imported) or from a command line, use one of the -following. (Notes: in 2.7, 'test ' (with the space) is 'test.regrtest '; -where present, -v and -ugui can be omitted.) +To run all idle_test/test_*.py tests from the interactive shell, run the +following: ->>> unittest.main('idlelib.idle_test', verbosity=2, exit=False) -python -m unittest -v idlelib.idle_test -python -m test -v -ugui test_idle -python -m test.test_idle + >>> import unittest + >>> unittest.main('idlelib.idle_test', verbosity=2, exit=False) -The idle tests are 'discovered' by idlelib.idle_test.__init__.load_tests, -which is also imported into test.test_idle. Normally, neither file should be -changed when working on individual test modules. The third command runs -unittest indirectly through regrtest. The same happens when the entire test -suite is run with 'python -m test'. So that command must work for buildbots -to stay green. Idle tests must not disturb the environment in a way that -makes other tests fail (issue 18081). +To run all idle_test/test_*.py tests from the command line, run the following: + + python -m unittest -v idlelib.idle_test + python -m test.test_idle + +Also, in Python 3, you can run the tests from the command line with this: + + python -m test -v -ugui test_idle + +In Python 2.7, you can run the tests from the command line with this: + + python -m test.regrtest -v -ugui test_idle + +The above commands run unittest indirectly through regrtest. The same happens +when the entire test suite is run with 'python -m test'. So that command must +work for buildbots to stay green. Where present, -v and -ugui can be omitted. + +The idle tests are 'discovered' by idlelib.idle_test.__init__.load_tests, which +is also imported into test.test_idle. Normally, neither file should be changed +when working on individual test modules. Idle tests must not disturb the +environment in a way that makes other tests fail (issue 18081). To run an individual Testcase or test method, extend the dotted name given to unittest on the command line. -python -m unittest -v idlelib.idle_test.test_xyz.Test_case.test_meth + python -m unittest -v idlelib.idle_test.test_xyz.Test_case.test_meth