lldb/packages/Python/lldbsuite/test/README-TestSuite

   1 This README file describes the files and directories related       -*- rst -*-
   2 to the Python test suite under the current 'test' directory.
   3
   4 - dotest.py
   5
   6   Provides the test driver for the test suite.  To invoke it, cd to the 'test'
   7   directory and issue the './dotest.py' command or './dotest.py -v' for more
   8   verbose output.  '.dotest.py -h' prints out the help messge.
   9
  10   A specific naming pattern is followed by the .py script under the 'test'
  11   directory in order to be recognized by 'dotest.py' test driver as a module
  12   which implements a test case, namely, Test*.py.
  13
  14   Some example usages:
  15
  16   1. ./dotest.py -v . 2> ~/Developer/Log/lldbtest.log0
  17      This runs the test suite and directs the run log to a file.
  18
  19   2. LLDB_LOG=/tmp/lldb.log GDB_REMOTE_LOG=/tmp/gdb-remote.log ./dotest.py -v . 2> ~/Developer/Log/lldbtest.log
  20      This runs the test suite, with logging turned on for the lldb as well as
  21      the process.gdb-remote channels and directs the run log to a file.
  22
  23 - lldbtest.py
  24
  25   Provides an abstract base class of lldb test case named 'TestBase', which in
  26   turn inherits from Python's unittest.TestCase.  The concrete subclass can
  27   override lldbtest.TestBase in order to inherit the common behavior for
  28   unittest.TestCase.setUp/tearDown implemented in this file.
  29
  30   To provide a test case, the concrete subclass provides methods whose names
  31   start with the letters test.  For more details about the Python's unittest
  32   framework, go to http://docs.python.org/library/unittest.html.
  33
  34   ./command_source/TestCommandSource.py provides a simple example of test case
  35   which overrides lldbtest.TestBase to exercise the lldb's 'command source'
  36   command.  The subclass should override the attribute 'mydir' in order for the
  37   runtime to locate the individual test cases when running as part of a large
  38   test suite or when running each test case as a separate Python invocation.
  39
  40   The doc string provides more details about the setup required for running a
  41   test case on its own.  To run the whole test suite, 'dotest.py' is all you
  42   need to do.
  43
  44 - subdirectories of 'test'
  45
  46   Most of them predate the introduction of the python test suite and contain
  47   example C/C++/ObjC source files which get compiled into executables which are
  48   to be exercised by the debugger.
  49
  50   For such subdirectory which has an associated Test*.py file, it was added as
  51   part of the Python-based test suite to test lldb functionality.
  52
  53   Some of the subdirectories, for example, the 'help' subdirectory, do not have
  54   C/C++/ObjC source files; they were created to house the Python test case which
  55   does not involve lldb reading in an executable file at all.
  56
  57   The sample_test directory contains examples of both a full and an "inline"
  58   testcase that run a process to a breakpoint and check a local variable.  These
  59   are convenient starting points for adding new tests.
  60
  61 - make directory
  62
  63   Contains Makefile.rules, which can be utilized by test cases to write Makefile
  64   based rules to build binaries for the inferiors.
  65
  66   By default, the built executable name is a.out, which can be overwritten by
  67   specifying your EXE make variable, via the Makefile under the specific test
  68   directory or via supplying a Python dictionary to the build method in your
  69   Python test script.  An example of the latter can be found in
  70   test/lang/objc/radar-9691614/TestObjCMethodReturningBOOL.py, where:
  71
  72     def test_method_ret_BOOL_with_dsym(self):
  73         """Test that objective-c method returning BOOL works correctly."""
  74         d = {'EXE': self.exe_name}
  75         self.buildDsym(dictionary=d)
  76         self.setTearDownCleanup(dictionary=d)
  77         self.objc_method_ret_BOOL(self.exe_name)
  78
  79     def test_method_ret_BOOL_with_dwarf(self):
  80         """Test that objective-c method returning BOOL works correctly."""
  81         d = {'EXE': self.exe_name}
  82         self.buildDwarf(dictionary=d)
  83         self.setTearDownCleanup(dictionary=d)
  84         self.objc_method_ret_BOOL(self.exe_name)
  85
  86     def setUp(self):
  87         # Call super's setUp().
  88         TestBase.setUp(self)
  89         # We'll use the test method name as the exe_name.
  90         self.exe_name = self.testMethodName
  91         # Find the line number to break inside main().
  92         self.main_source = "main.m"
  93         self.line = line_number(self.main_source, '// Set breakpoint here.')
  94
  95   The exe names for the two test methods are equal to the test method names and
  96   are therefore guaranteed different.
  97
  98 - plugins directory
  99
 100   Contains platform specific plugin to build binaries with dsym/dwarf debugging
 101   info.  Other platform specific functionalities may be added in the future.
 102
 103 - unittest2 directory
 104
 105   Many new features were added to unittest in Python 2.7, including test
 106   discovery. unittest2 allows you to use these features with earlier versions of
 107   Python.
 108
 109   It currently has unittest2 0.5.1 from http://pypi.python.org/pypi/unittest2.
 110   Version 0.5.1 of unittest2 has feature parity with unittest in Python 2.7
 111   final. If you want to ensure that your tests run identically under unittest2
 112   and unittest in Python 2.7 you should use unittest2 0.5.1.
 113
 114   Later versions of unittest2 include changes in unittest made in Python 3.2 and
 115   onwards after the release of Python 2.7.
 116
 117 - dotest.pl
 118
 119   In case you wonder, there is also a 'dotest.pl' perl script file.  It was
 120   created to visit each Python test case under the specified directory and
 121   invoke Python's builtin unittest.main() on each test case.
 122
 123   It does not take advantage of the test runner and test suite functionality
 124   provided by Python's unitest framework.  Its existence is because we want a
 125   different way of running the whole test suite.  As lldb and the Python test
 126   suite become more reliable, we don't expect to be using 'dotest.pl' anymore.
 127
 128   Note: dotest.pl has been moved to the attic directory.
 129
 130 - Profiling dotest.py runs
 131
 132   I used the following command line thingy to do the profiling on a SnowLeopard
 133   machine:
 134
 135     $ 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
 136
 137   After that, I used the pstats.py module to browse the statistics:
 138
 139     $ python /System/Library/Frameworks/Python.framework/Versions/Current/lib/python2.6/pstats.py my.profile
 140
 141 - Writing test cases:
 142
 143   We strongly prefer writing test cases using the SB API's rather than
 144   the runCmd & expect.  Unless you are actually testing some feature
 145   of the command line, please don't write command based tests.  For
 146   historical reasons there are plenty of examples of tests in the test
 147   suite that use runCmd where they shouldn't, but don't copy them,
 148   copy the plenty that do use the SB API's instead.
 149
 150   The reason for this is that our policy is that we will maintain
 151   compatibility with the SB API's.  But we don't make any similar
 152   guarantee about the details of command result format.  If your test
 153   is using the command line, it is going to have to check against the
 154   command result text, and you either end up writing your check
 155   pattern by checking as little as possible so you won't be exposed to
 156   random changes in the text; in which case you can end up missing
 157   some failure, or you test too much and it means irrelevant changes
 158   break your tests.
 159
 160   However, if you use the Python API's it is possible to check all the
 161   results you want to check in a very explicit way, which makes the
 162   tests much more robust.
 163
 164   Even if you are testing that a command-line command does some
 165   specific thing, it is still better in general to use the SB API's to
 166   drive to the point where you want to run the test, then use
 167   SBInterpreter::HandleCommand to run the command.  You get the full
 168   result text from the command in the command return object, and all
 169   the part where you are driving the debugger to the point you want to
 170   test will be more robust.
 171
 172   The sample_test directory contains a standard and an "inline" test
 173   that are good starting points for writing a new test.
 174
 175 - Attaching in test cases:
 176
 177   If you need to attach to inferiors in your tests, you must make sure
 178   the inferior calls lldb_enable_attach(), before the debugger
 179   attempts to attach. This function performs any platform-specific
 180   processing needed to enable attaching to this process (e.g., on
 181   Linux, we execute prctl(PR_SET_TRACER) syscall to disable
 182   protections present in some Linux systems).