www/test.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   5   <link href="style.css" rel="stylesheet" type="text/css" />
   6   <title>Testing LLDB</title>
   7 </head>
   8 <body>
   9   <div class="www_title">
  10     The <strong>LLDB</strong> Debugger
  11   </div>
  12
  13   <div id="container">
  14     <div id="content">
  15
  16       <!--#include virtual="sidebar.incl"-->
  17
  18       <div id="middle">
  19         <div class="post">
  20           <h1 class="postheader">Testing LLDB</h1>
  21           <div class="postcontent">
  22             <p>
  23               The LLDB test suite consists of Python scripts located under the
  24               <tt>test</tt> directory. Each script contains a number of test cases and is usually
  25               accompanied by a C (C++, ObjC, etc.) source file. Each test first compiles the
  26               source file and then uses LLDB to debug the resulting executable. The tests verify
  27               both the LLDB command line interface and the scripting API.
  28             </p>
  29
  30             <p>
  31               The easiest way to run the LLDB test suite is to use the <tt>check-lldb</tt> build
  32               target. By default, the <tt>check-lldb</tt> target builds the test programs with
  33               the same compiler that was used to build LLDB. To build the tests with a different
  34               compiler, you can set the <tt>LLDB_TEST_COMPILER</tt> CMake variable. It is possible to
  35               customize the architecture of the test binaries and compiler used by appending -A
  36               and -C options respectively to the CMake variable <tt>LLDB_TEST_USER_ARGS</tt>. For
  37               example, to test LLDB against 32-bit binaries
  38               built with a custom version of clang, do:
  39             </p>
  40             <code>
  41               <br />&gt; cmake -DLLDB_TEST_ARGS="-A i386 -C /path/to/custom/clang" -G Ninja
  42               <br />&gt; ninja check-lldb
  43             </code>
  44             <p>Note that multiple -A and -C flags can be specified to <tt>LLDB_TEST_USER_ARGS</tt>.</p>
  45             <p>Note that on NetBSD you must export <tt>LD_LIBRARY_PATH=$PWD/lib</tt> in your environment. This is due to lack of
  46                the <tt>$ORIGIN</tt> linker feature.</p>
  47             <p>
  48               In addition to running all the LLDB test suites with the "check-lldb" CMake target above, it is possible to
  49               run individual LLDB tests. For example, to run the test cases defined in TestInferiorCrashing.py, run:
  50             </p>
  51             <code>
  52               <br />&gt; cd $lldb/test
  53               <br />&gt; python dotest.py --executable &lt;path-to-lldb&gt;  -p TestInferiorCrashing.py
  54             </code>
  55             <p>
  56               In addition to running a test by name, it is also possible to specify a directory path to <tt>dotest.py</tt>
  57               in order to run all the tests under that directory. For example, to run all the tests under the
  58               'functionalities/data-formatter' directory, run:
  59             </p>
  60             <code>
  61               <br />&gt; python dotest.py --executable &lt;path-to-lldb&gt; functionalities/data-formatter
  62             </code>
  63             <p>
  64               To dump additional information to <tt>stdout</tt> about how the test harness is driving LLDB, run
  65               <tt>dotest.py</tt> with the <tt>-t</tt> flag. Many more options that are available. To see a list of all of them, run:
  66             </p>
  67             <code>
  68               <br />&gt; python dotest.py -h
  69             </code>
  70
  71             <p>
  72               The dotest.py script runs tests in parallel by default.
  73               To disable the parallel test running feature, use the
  74               <code>--no-multiprocess</code> flag. The number of
  75               concurrent tests is controlled by
  76               the <code>LLDB_TEST_THREADS</code> environment variable
  77               or the <code>--threads</code> command line parameter.
  78               The default value is the number of CPU cores on your
  79               system.
  80             </p>
  81             <p>
  82               The parallel test running feature will handle an
  83               additional <code>--test-subdir SUBDIR</code> arg.  When
  84               specified, SUBDIR is relative to the root test directory
  85               and will limit all parallel test running to that
  86               subdirectory's tree of tests.
  87             </p>
  88             <p>
  89               The parallel test runner will run all tests within a
  90               given directory serially, but will run multiple
  91               directories concurrently.  Thus, as a test writer, we
  92               provide serialized test run semantics within a
  93               directory.  Note child directories are considered
  94               entirely separate, so two child directories could be
  95               running in parallel with a parent directory.
  96             </p>
  97
  98             <h3>Running the test-suite remotely</h3>
  99
 100             <p>
 101               Running the test-suite remotely is similar to the process of running a local test
 102               suite, but there are two things to have in mind:
 103             </p>
 104             <ul>
 105               <li>
 106                 You must have the <code>lldb-server</code> running on the remote system, ready to
 107                 accept multiple connections. For more information on how to setup remote
 108                 debugging see the <a href="remote.html">Remote debugging</a> page.
 109               </li>
 110               <li>
 111                 You must tell the test-suite how to connect to the remote system. This is
 112                 achieved using the <code>--platform-name</code>, <code>--platform-url</code> and
 113                 <code>--platform-working-dir</code> parameters to <code>dotest.py</code>. These
 114                 parameters correspond to the <code>platform select</code> and <code>platform
 115                 connect</code> LLDB commands. You will usually also need to specify the compiler and
 116                 architecture for the remote system.
 117               </li>
 118             </ul>
 119             <p>
 120               Currently, running the remote test suite is supported only with
 121               <code>dotest.py</code> (or <code>dosep.py</code> with a single thread), but we
 122               expect this issue to be addressed in the near future.
 123             </p>
 124
 125           </div>
 126           <div class="postfooter"></div>
 127         </div>
 128       </div>
 129     </div>
 130   </div>
 131 </body>
 132 </html>