Testing LLDB
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 todotest.py
. These parameters correspond to theplatform select
andplatform 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.