← Back to branch summary

~pygame/pygame/trunk

« back to all changes in this revision

Viewing changes to docs/reST/ref/tests.rst

  • Committer: pygame
  • Date: 2017-01-10 00:31:42 UTC
  • Revision ID: git-v1:2eea4f299a2e791f884608d7ed601558634af73c
commit 1639c41a8cb3433046882ede92c80ce69d59016b
Author: Thomas Kluyver <takowl@gmail.com>
Date:   Sun Jan 8 18:46:46 2017 +0000

    Build newer versions of libogg and libvorbis into Linux base images

    Closes #317
    Closes #323

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reST/ref/tests.rst
 
1
.. include:: common.txt
 
2
 
 
3
:mod:`pygame.tests`
 
4
===================
 
5
 
 
6
.. module:: pygame.tests
 
7
   :synopsis: Pygame unit test suite package
 
8
 
 
9
| :sl:`Pygame unit test suite package`
 
10
 
 
11
A quick way to run the test suite package from the command line is to import
 
12
the go submodule with the Python -m option:
 
13
 
 
14
::
 
15
 
 
16
  python -m pygame.tests [<test options>]
 
17
 
 
18
Command line option --help displays a usage message. Available options
 
19
correspond to the :func:`pygame.tests.run` arguments.
 
20
 
 
21
The xxxx_test submodules of the tests package are unit test suites for
 
22
individual parts of Pygame. Each can also be run as a main program. This is
 
23
useful if the test, such as cdrom_test, is interactive.
 
24
 
 
25
For Pygame development the test suite can be run from a Pygame distribution
 
26
root directory. Program ``run_tests.py`` is provided for convenience, though
 
27
test/go.py can be run directly.
 
28
 
 
29
Module level tags control which modules are included in a unit test run. Tags
 
30
are assigned to a unit test module with a corresponding <<ame>_tags.py module.
 
31
The tags module has the global __tags__, a list of tag names. For example,
 
32
``cdrom_test.py`` has a tag file ``cdrom_tags.py`` containing a tags list that
 
33
has the 'interactive' string. The 'interactive' tag indicates ``cdrom_test.py``
 
34
expects user input. It is excluded from a ``run_tests.py`` or
 
35
``pygame.tests.go`` run. Two other tags that are excluded are 'ignore' and
 
36
'subprocess_ignore'. These two tags indicate unit tests that will not run on a
 
37
particular platform, or for which no corresponding Pygame module is available.
 
38
The test runner will list each excluded module along with the tag responsible.
 
39
 
 
40
.. function:: run
 
41
 
 
42
   | :sl:`Run the Pygame unit test suite`
 
43
   | :sg:`run(*args, **kwds) -> tuple`
 
44
 
 
45
   Positional arguments (optional):
 
46
 
 
47
   ::
 
48
 
 
49
       The names of tests to include. If omitted then all tests are run. Test names
 
50
       need not include the trailing '_test'.
 
51
 
 
52
   Keyword arguments:
 
53
 
 
54
   ::
 
55
 
 
56
       incomplete - fail incomplete tests (default False)
 
57
       nosubprocess - run all test suites in the current process
 
58
                      (default False, use separate subprocesses)
 
59
       dump - dump failures/errors as dict ready to eval (default False)
 
60
       file - if provided, the name of a file into which to dump failures/errors
 
61
       timings - if provided, the number of times to run each individual test to
 
62
                 get an average run time (default is run each test once)
 
63
       exclude - A list of TAG names to exclude from the run
 
64
       show_output - show silenced stderr/stdout on errors (default False)
 
65
       all - dump all results, not just errors (default False)
 
66
       randomize - randomize order of tests (default False)
 
67
       seed - if provided, a seed randomizer integer
 
68
       multi_thread - if provided, the number of THREADS in which to run
 
69
                      subprocessed tests
 
70
       time_out - if subprocess is True then the time limit in seconds before
 
71
                  killing a test (default 30)
 
72
       fake - if provided, the name of the fake tests package in the
 
73
              run_tests__tests subpackage to run instead of the normal
 
74
              Pygame tests
 
75
       python - the path to a python executable to run subprocessed tests
 
76
                (default sys.executable)
 
77
 
 
78
   Return value:
 
79
 
 
80
   ::
 
81
 
 
82
       A tuple of total number of tests run, dictionary of error information.
 
83
       The dictionary is empty if no errors were recorded.
 
84
 
 
85
   By default individual test modules are run in separate subprocesses. This
 
86
   recreates normal Pygame usage where ``pygame.init()`` and ``pygame.quit()``
 
87
   are called only once per program execution, and avoids unfortunate
 
88
   interactions between test modules. Also, a time limit is placed on test
 
89
   execution, so frozen tests are killed when there time allotment expired. Use
 
90
   the single process option if threading is not working properly or if tests
 
91
   are taking too long. It is not guaranteed that all tests will pass in single
 
92
   process mode.
 
93
 
 
94
   Tests are run in a randomized order if the randomize argument is True or a
 
95
   seed argument is provided. If no seed integer is provided then the system
 
96
   time is used.
 
97
 
 
98
   Individual test modules may have a __tags__ attribute, a list of tag strings
 
99
   used to selectively omit modules from a run. By default only 'interactive'
 
100
   modules such as cdrom_test are ignored. An interactive module must be run
 
101
   from the console as a Python program.
 
102
 
 
103
   This function can only be called once per Python session. It is not
 
104
   reentrant.
 
105
 
 
106
   .. ## pygame.tests.run ##
 
107
 
 
108
.. ## pygame.tests ##