llvm-project/lldb/test/README-TestSuite

102 lines
4.5 KiB
Plaintext
Raw Normal View History

This README file describes the files and directories related to the Python test
suite under the current 'test' directory.
o dotest.py
Provides the test driver for the test suite. To invoke it, cd to the 'test'
directory and issue the './dotest.py' command or './dotest.py -v' for more
verbose output. '.dotest.py -h' prints out the help messge.
A specific naming pattern is followed by the .py script under the 'test'
directory in order to be recognized by 'dotest.py' test driver as a module
which implements a test case, namely, Test*.py.
Some example usages:
1. ./dotest.py -v . 2> ~/Developer/Log/lldbtest.log0
This runs the test suite and directs the run log to a file.
2. LLDB_LOG=/tmp/lldb.log GDB_REMOTE_LOG=/tmp/gdb-remote.log ./dotest.py -v . 2> ~/Developer/Log/lldbtest.log
This runs the test suite, with logging turned on for the lldb as well as
the process.gdb-remote channels and directs the run log to a file.
o lldbtest.py
Provides an abstract base class of lldb test case named 'TestVase', which in
turn inherits from Python's unittest.TestCase. The concrete subclass can
override lldbtest.TestBase in order to inherit the common behavior for
unittest.TestCase.setUp/tearDown implemented in this file.
To provide a test case, the concrete subclass provides methods whose names
start with the letters test. For more details about the Python's unittest
framework, go to http://docs.python.org/library/unittest.html.
./command_source/TestCommandSource.py provides a simple example of test case
which overrides lldbtest.TestBase to exercise the lldb's 'command source'
command. The subclass should override the attribute 'mydir' in order for the
runtime to locate the individual test cases when running as part of a large
test suite or when running each test case as a separate Python invocation.
The doc string provides more details about the setup required for running a
test case on its own. To run the whole test suite, 'dotest.py' is all you
need to do.
o subdirectories of 'test'
Most of them predate the introduction of the python test suite and contain
example C/C++/ObjC source files which get compiled into executables which are
to be exercised by the debugger.
For such subdirectory which has an associated Test*.py file, it was added as
part of the Python-based test suite to test lldb functionality.
Some of the subdirectories, for example, the 'help' subdirectory, do not have
C/C++/ObjC source files; they were created to house the Python test case which
does not involve lldb reading in an executable file at all.
o make directory
Contains Makefile.rules, which can be utilized by test cases to write Makefile
based rules to build native binaries.
o plugins directory
Contains platform specific plugin to build binaries with dsym/dwarf debugging
info. Other platform specific functionalities may be added in the future.
o unittest2 directory
Many new features were added to unittest in Python 2.7, including test
discovery. unittest2 allows you to use these features with earlier versions of
Python.
It currently has unittest2 0.5.1 from http://pypi.python.org/pypi/unittest2.
Version 0.5.1 of unittest2 has feature parity with unittest in Python 2.7
final. If you want to ensure that your tests run identically under unittest2
and unittest in Python 2.7 you should use unittest2 0.5.1.
Later versions of unittest2 include changes in unittest made in Python 3.2 and
onwards after the release of Python 2.7.
o dotest.pl
In case you wonder, there is also a 'dotest.pl' perl script file. It was
created to visit each Python test case under the specified directory and
invoke Python's builtin unittest.main() on each test case.
It does not take advantage of the test runner and test suite functionality
provided by Python's unitest framework. Its existence is because we want a
different way of running the whole test suite. As lldb and the Python test
suite become more reliable, we don't expect to be using 'dotest.pl' anymore.
Note: dotest.pl has been moved to the attic directory.
o Profiling dotest.py runs
I used the following command line thingy to do the profiling on a SnowLeopard
machine:
$ DOTEST_PROFILE=YES DOTEST_SCRIPT_DIR=/Volumes/data/lldb/svn/trunk/test /System/Library/Frameworks/Python.framework/Versions/Current/lib/python2.6/cProfile.py -o my.profile ./dotest.py -v -w 2> ~/Developer/Log/lldbtest.log
After that, I used the pstats.py module to browse the statistics.