Lines Matching +full:docs +full:- +full:lldb +full:- +full:html
5 --------------------
7 The LLDB test suite consists of three different kinds of test:
12 driver or through ``lldb-test`` which is a tool that exposes the internal
13 data structures in an easy-to-parse way for testing. Most people will know
16 <https://llvm.org/docs/CommandGuide/FileCheck.html>`_ is used to verify
19 SB API. These are written in Python and use LLDB's ``dotest.py`` testing
21 <https://docs.python.org/3/library/unittest.html>`_.
24 <https://llvm.org/docs/CommandGuide/lit.html>`_ ) as the test driver. The test
31 Unit tests are located under ``lldb/unittests``. If it's possible to test
42 Shell tests are located under ``lldb/test/Shell``. These tests are generally
43 built around checking the output of ``lldb`` (the command line driver) or
44 ``lldb-test`` using ``FileCheck``. Shell tests are generally small and fast to
47 ``lldb-test`` is a relatively new addition to the test suite. It was the first
50 other things you can use it to query lldb for symbol files, for object files
54 the subcomponents already exposed by lldb-test. But when it comes to LLDB's
62 means that you have to have a well-defined test scenario that you can easily
76 of (some) aspects of handling of binaries with non-native architectures or
90 API tests are located under ``lldb/test/API``. They are run with the
92 compiled with Make. The majority of API tests are end-to-end tests that compile
95 As mentioned before, ``dotest.py`` is LLDB's testing framework. The
96 implementation is located under ``lldb/packages/Python/lldbsuite``. We have
98 `unittest <https://docs.python.org/3/library/unittest.html>`_. Those can be
100 `lldbtest.py <https://github.com/llvm/llvm-project/blob/main/lldb/packages/Python/lldbsuite/test/lldbtest.py>`_.
103 <https://github.com/llvm/llvm-project/tree/main/lldb/test/API/sample_test>`_.
128 <https://github.com/llvm/llvm-project/blob/main/lldb/packages/Python/lldbsuite/test/lldbutil.py>`_
134 <https://ftp.gnu.org/old-gnu/Manuals/dejagnu-1.3/html_node/dejagnu_6.html>`_
137 version etc. LLDB comes with a range of predefined decorators for these
164 CFLAGS_EXTRAS := -std=c99
169 `Makefile.rules <https://github.com/llvm/llvm-project/blob/main/lldb/packages/Python/lldbsuite/test/make/Makefile.rules>`_
198 arguments -- without any modifications to the code. You can create a focused
219 of LLDB's functionality is available directly after creating an `SBTarget`
228 the `SBType`-related parts of the API. With those languages it's also
235 Languages such as Objective-C that have a dependency on a runtime
243 **Avoid specifying test-specific compiler flags when including system headers.**
249 in your test (e.g., adding ``-DFOO`` to the ``Makefile`` or ``self.build``
275 **Prefer LLDB testing utilities over directly working with the SB API.**
287 the output of LLDB commands and instead try calling into the SB API. Relying
288 on LLDB commands makes changing (and improving) the output/syntax of
299 When running the same command in LLDB the reason for the unexpected success
304 (lldb) expr 2 + 2
308 A better way to write the test above would be using LLDB's testing function
317 last option as they give non-descriptive error messages. The test class has
321 asserts are available. LLDB also has a few custom asserts that are tailored
324 +-----------------------------------------------+-----------------------------------------------------------------+
326 +-----------------------------------------------+-----------------------------------------------------------------+
327 | ``assertSuccess`` | Assert that an ``lldb.SBError`` is in the "success" state. |
328 +-----------------------------------------------+-----------------------------------------------------------------+
329 | ``assertState`` | Assert that two states (``lldb.eState*``) are equal. |
330 +-----------------------------------------------+-----------------------------------------------------------------+
331 | ``assertStopReason`` | Assert that two stop reasons (``lldb.eStopReason*``) are equal. |
332 +-----------------------------------------------+-----------------------------------------------------------------+
345 **Do not use hard-coded line numbers in your test case.**
353 .. code-block:: c
359 .. code-block:: c
369 These features can be use to properly mark your test class or method for platform-specific tests, compiler specific, version specific.
373 .. code-block:: python
383 self.do_test(dict(CFLAGS_EXTRAS="-gdwarf-5 -gpubnames"))
387 **Class-wise cleanup after yourself.**
389 TestBase.tearDownClass(cls) provides a mechanism to invoke the platform-specific cleanup after finishing with a test class. A test
398 .. code-block:: python
411 --
414 testing. Everyone can `add a buildbot for LLDB <https://llvm.org/docs/HowToAddABuilder.html>`_.
416 An overview of all LLDB builders can be found here:
418 `https://lab.llvm.org/buildbot/#/builders?tags=lldb <https://lab.llvm.org/buildbot/#/builders?tags=lldb>`_
421 has a dedicated tab for LLDB: `https://green.lab.llvm.org/job/llvm.org/view/LLDB/
422 <https://green.lab.llvm.org/job/llvm.org/view/LLDB/>`_
426 -----------------
432 LLDB.
442 The easiest way to run the LLDB test suite is to use the ``check-lldb`` build
447 $ ninja check-lldb
452 By default, the ``check-lldb`` target builds the test programs with the same
453 compiler that was used to build LLDB. To build the tests with a different
461 used by appending ``-A`` and ``-C`` options respectively. For example, to test
462 LLDB against 32-bit binaries built with a custom version of clang, do:
466 $ cmake -DLLDB_TEST_USER_ARGS="-A;i386;-C;/path/to/custom/clang" -G Ninja
467 $ ninja check-lldb
469 Note that multiple ``-A`` and ``-C`` flags can be specified to
472 If you want to change the LLDB settings that tests run with then you can set
473 the ``--setting`` option of the test runner via this same variable. For example
474 ``--setting;target.disable-aslr=true``.
477 ``<build-dir>/bin/lldb-dotest --help``.
483 with ``check-lldb``.
485 * Use ``check-lldb-unit`` to run just the unit tests.
486 * Use ``check-lldb-api`` to run just the SB API tests.
487 * Use ``check-lldb-shell`` to run just the shell tests.
491 target ``check-lldb-shell-objectfile``. However, because the unit tests and API
492 tests don't actually live under ``lldb/test``, this convenience is only
504 $ ./bin/llvm-lit -sv <llvm-project-root>/lldb/test --filter <test>
512 $ ./bin/llvm-lit -sv <llvm-project-root>/lldb/test/Shell/Commands/CommandScriptImmediateOutput
516 passing ``--param`` to lit and setting a value for ``dotest-args``.
520 $ ./bin/llvm-lit -sv <llvm-project-root>/lldb/test --param dotest-args='-C gcc'
529 In addition to running all the LLDB test suites with the ``check-lldb`` CMake
530 target above, it is possible to run individual LLDB tests. If you have a CMake
531 build you can use the ``lldb-dotest`` binary, which is a wrapper around
535 one-off with a different configuration.
541 $ ./bin/lldb-dotest -p TestInferiorCrashing.py
545 $ cd $lldb/test
546 $ python dotest.py --executable <path-to-lldb> -p TestInferiorCrashing.py ../packages/Python/lldbsuite/test
548 If the test is not specified by name (e.g. if you leave the ``-p`` argument
554 $ ./bin/lldb-dotest functionalities/data-formatter
558 $ python dotest.py --executable <path-to-lldb> functionalities/data-formatter
564 $ python dotest.py -h
570 The unit tests are simple executables, located in the build directory under ``tools/lldb/unittests``.
576 $ ./tools/lldb/unittests/Host/HostTests
583 $ ./tools/lldb/unittests/Host/HostTests --gtest_filter=SocketTest.DomainListenConnectAccept
589 Running the test-suite remotely is similar to the process of running a local
592 1. You must have the lldb-server running on the remote system, ready to accept
595 2. You must tell the test-suite how to connect to the remote system. This is
597 flags to cmake, and ``--platform-name`` parameter to ``dotest.py``.
599 LLDB commands. You will usually also need to specify the compiler and
611 QEMU can be used to test LLDB in an emulation environment in the absence of
612 actual hardware. :doc:`/resources/qemu-testing` describes how to setup an
614 ``llvm-project/lldb/scripts/lldb-test-qemu``. These scripts currently
618 -----------------------
620 On non-Windows platforms, you can use the ``-d`` option to ``dotest.py`` which
622 until a debugger is attached. Then run ``lldb -p <pid>`` to attach.
624 To instead debug a test's python source, edit the test and insert ``import pdb; pdb.set_trace()`` or ``breakpoint()`` (Python 3 only) at the point you want to start debugging. The ``breakpoint()`` command can be used for any LLDB Python script, not just for API tests.
626 In addition to pdb's debugging facilities, lldb commands can be executed with the
627 help of a pdb alias. For example ``lldb bt`` and ``lldb v some_var``. Add this
632 alias lldb self.dbg.HandleCommand("%*")
640 then into the LLDB code that backs the operations the test is performing.
646 #. Go to File -> New -> Project -> Python -> From Existing Python Code.
647 #. Choose llvm/tools/lldb as the directory containing the Python code.
648 #. When asked where to save the .pyproj file, choose the folder ``llvm/tools/lldb/pyproj``. This is a special folder that is ignored by the ``.gitignore`` file, since it is not checked in.
651 #. Go to Tools -> Options -> Python Tools -> Environment Options
656 #. In Debug/Search Paths, enter the path to your ninja/lib/site-packages directory.
658 #. If you want to enabled mixed mode debugging, check Enable native code debugging (this slows down debugging, so enable it only on an as-needed basis.)
666 --arch=i686
667 # Path to debug lldb.exe
668 --executable D:/src/llvmbuild/ninja/bin/lldb.exe
670 -s D:/src/llvmbuild/ninja/lldb-test-traces
671 -u CXXFLAGS -u CFLAGS
673 --enable-crash-dialog
675 -C d:\src\llvmbuild\ninja_release\bin\clang.exe
677 -p TestPaths.py
679 D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test
683 --arch=i686 --executable D:/src/llvmbuild/ninja/bin/lldb.exe -s D:/src/llvmbuild/ninja/lldb-test-traces -u CXXFLAGS -u CFLAGS --enable-crash-dialog -C d:\src\llvmbuild\ninja_release\bin\clang.exe -p TestPaths.py D:\src\llvm\tools\lldb\packages\Python\lldbsuite\test --no-multiprocess
685 .. [#] `https://lldb.llvm.org/python_reference/lldb.SBTarget-class.html#BreakpointCreateByName <https://lldb.llvm.org/python_reference/lldb.SBTarget-class.html#BreakpointCreateByName>`_