Author: David Spickett Date: 2026-07-01T10:10:02+01:00 New Revision: b0ab92a214fb488b03b8c3cb394bd41909e495e5
URL: https://github.com/llvm/llvm-project/commit/b0ab92a214fb488b03b8c3cb394bd41909e495e5 DIFF: https://github.com/llvm/llvm-project/commit/b0ab92a214fb488b03b8c3cb394bd41909e495e5.diff LOG: [lldb][docs] Document how to test specific layers (#205581) This is motivated by the fact that we have the ability to test almost any component of the debug session on its own, but it's hard to find those tests. If we put AI aside, you can't look for "test that lldb doesn't fault when qProcessInfo contains foo". Even though that is a thing we can test. So in this change I'm adding a section to the testing docs with some starting points that people can search for. It will be incomplete but we can add to it over time. I will need someone to write the DAP part in a follow up PR, as I'm not familiar with the layers there. Added: Modified: lldb/docs/resources/test.md Removed: ################################################################################ diff --git a/lldb/docs/resources/test.md b/lldb/docs/resources/test.md index 0f07744bb0dd3..9b6d3912659a5 100644 --- a/lldb/docs/resources/test.md +++ b/lldb/docs/resources/test.md @@ -403,6 +403,69 @@ The 'child_send1.txt' file gets generated during the test run, so it makes sense TestSTTYBeforeAndAfter.py file to do the cleanup instead of artificially adding it as part of the default cleanup action which serves to cleanup those intermediate and a.out files. +## How To Test Different Parts of LLDB + +Below is a breakdown of the diff erent components involved in an LLDB debug session, +with hints for the type of tests you can use to test these steps in isolation. + +Testing a change in isolation is preferred, but if that is not possible, the +fallback is always a Shell or API test that works at a higher level. For these, +try to be sure that the behaviour you are checking for is not going to be +generated by code other than the code in question, now, or in the future. + +### Interactive User Interface Elements + +Like the text user interface, or tab completion in the command line interface. + +Use a `PExpectTest` or call the SBAPI equivalent of what the user's input is +doing. In completion's case, `SBCommandInterpreter::HandleCompletion`. + +### Internal Components of `lldb` And the Debug Server + +Use a unit test. It is justified to refactor code in order for it to be unit +tested. + +### `lldb`'s Handling of Specific Packets and Sequences of Packets + +Use an API test that creates a mock debug server. Look for +`MockGDBServer` and `MockGDBServerResponder` in the existing test suite. + +If you need to fake part of the debug server but forward the rest to a real +debug server, start by looking at the reverse execution tests which use +`ReverseTestBase`. + +### The debug server's handling of specific packets or sequences of packets + +Use an API test that sends fake traffic to a real `lldb-server`. The existing +tests in `lldb/test/API/tools/lldb-server` are your starting point. + +### The Debug Server’s Handling of Specific Packets or Sequences of Packets + +Generally you can check this using `lldb`'s own commands in a Shell or API +test. + +However if you do not trust enough of the implementation yet to do that, +you can have the inferior process check things for you. + +For example, to test register access the API test might: +1. Launch the inferior, which writes a known pattern to the register using + inline assembly or operating system APIs. Then hits a breakpoint. +2. Read the register using `register read` and check for that pattern. +3. Write a diff erent pattern to the register using `register write`. +4. Continue the inferior. +5. The inferior reads the register by whatever means, and checks that it got + the new pattern. If it did not, exit with some obvious non-zero code. +6. Finally the test checks the inferior's exit code to see if there was + a failure. + +By assuming that the architecture and operating system work, and using it +as the start end end point, you are protecting yourself from a mistake like +writing the register value to a buffer inside `lldb` but never to the hardware +itself. + +An example of this style is +`lldb/test/API/linux/aarch64/tls_registers/TestAArch64LinuxTLSRegisters.py`. + ## CI LLVM Buildbot is the place where volunteers provide machines for building and _______________________________________________ lldb-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
