+

+ The LLDB test suite consists of Python scripts located under the + test directory. Each script contains a number of test cases and is usually + accompanied by a C (C++, ObjC, etc.) source file. Each test first compiles the + source file and then uses LLDB to debug the resulting executable. The tests verify + both the LLDB command line interface and the scripting API. +

+ +

+ The easiest way to run the LLDB test suite is to use the check-lldb build + target. By default, the check-lldb target builds the test programs with + the same compiler that was used to build LLDB. To build the tests with a different + compiler, you can set the LLDB_TEST_COMPILER CMake variable. It is possible to + customize the architecture of the test binaries and compiler used by appending -A + and -C options respectively to the CMake variable LLDB_TEST_USER_ARGS. For + example, to test LLDB against 32-bit binaries + built with a custom version of clang, do: +

+ +
> cmake -DLLDB_TEST_ARGS="-A i386 -C /path/to/custom/clang" -G Ninja +
> ninja check-lldb + +

Note that multiple -A and -C flags can be specified to LLDB_TEST_USER_ARGS.

+

+ In addition to running all the LLDB test suites with the "check-lldb" CMake target above, it is possible to + run individual LLDB tests. For example, to run the test cases defined in TestInferiorCrashing.py, run: +

+ +
> cd $lldb/test +
> python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py + +

+ In addition to running a test by name, it is also possible to specify a directory path to dotest.py + in order to run all the tests under that directory. For example, to run all the tests under the + 'functionalities/data-formatter' directory, run: +

+ +
> python dotest.py --executable <path-to-lldb> functionalities/data-formatter + +

+ To dump additional information to stdout about how the test harness is driving LLDB, run + dotest.py with the -t flag. Many more options that are available. To see a list of all of them, run: +

+ +
> python dotest.py -h + + +

+ Besides dotest.py, there is also dosep.py, which runs + multiple instances of dotest.py in parallel, thereby greatly + decreasing the time it takes to run the full testsuite. The number of concurrent + tests is controlled by the LLDB_TEST_THREADS environment variable or + the --threads command line parameter. The default value is the number + of CPUs on your system. To pass additional options to dotest.py, + specify those options as an -o argument to dosep.py. For + example, the command +

+ python dosep.py -o "--executable bin/lldb -C bin/clang" +

+ will specify the lldb and clang executables to test for each dotest invocation. + ninja check-lldb is wrapper around dosep.py. +

+ +

Running the test-suite remotely

+ +

+ Running the test-suite remotely is similar to the process of running a local test + suite, but there are two things to have in mind: +

+
    +
  • + You must have the lldb-server running on the remote system, ready to + accept multiple connections. For more information on how to setup remote + debugging see the Remote debugging page. +
    • +
  • + You must tell the test-suite how to connect to the remote system. This is + achieved using the --platform-name, --platform-url and + --platform-working-dir parameters to dotest.py. These + parameters correspond to the platform select and platform + connect LLDB commands. You will usually also need to specify the compiler and + architecture for the remote system. +
    • +
+

+ Currently, running the remote test suite is supported only with + dotest.py (or dosep.py with a single thread), but we + expect this issue to be adressed in the near future. +

+ +