https://github.com/DavidSpickett created https://github.com/llvm/llvm-project/pull/205581
For want of a better title. 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. >From 84762571dc8df7054e96c5b937c7ce4c3fb6f039 Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Wed, 24 Jun 2026 15:48:12 +0000 Subject: [PATCH] [lldb][docs] Document how to test specific layers For want of a better title. 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 as I'm not familiar with the layers there. --- lldb/docs/resources/test.md | 64 +++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) diff --git a/lldb/docs/resources/test.md b/lldb/docs/resources/test.md index 0f07744bb0dd3..8cbd0e1681a11 100644 --- a/lldb/docs/resources/test.md +++ b/lldb/docs/resources/test.md @@ -403,6 +403,70 @@ 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 Specific Things + +Below is a breakdown of the layers in an lldb session, with hints for the type of +tests you can use to test these steps in isolation. + +If isolation 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. + +### What the debug server does to the inferior process + +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: +* Launch the inferior, which writes a known pattern to the register using + inline assembly or operating system APIs. Then hits a breakpoint. +* Read the register using `register read` and check for that pattern. +* Write a different pattern to ther register using `register write`. +* Continue the inferior. +* 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. +* 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
