https://github.com/DavidSpickett updated https://github.com/llvm/llvm-project/pull/205581
>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 1/3] [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 >From 9343e3c85270da1a88c0869e03c64f956dbf3768 Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Wed, 1 Jul 2026 08:54:49 +0000 Subject: [PATCH 2/3] address review comments --- lldb/docs/resources/test.md | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/lldb/docs/resources/test.md b/lldb/docs/resources/test.md index 8cbd0e1681a11..a7cd43bdae84c 100644 --- a/lldb/docs/resources/test.md +++ b/lldb/docs/resources/test.md @@ -403,15 +403,15 @@ 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 +## How To Test Different Parts of LLDB -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. +Below is a breakdown of the different components involved in an LLDB debug 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. +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 @@ -420,7 +420,6 @@ 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 @@ -448,15 +447,15 @@ 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 +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. -* 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 +2. Read the register using `register read` and check for that pattern. +3. Write a different 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. -* Finally the test checks the inferior's exit code to see if there was +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 >From 0b1100ffac7cc154992335757c9292416fa26dd4 Mon Sep 17 00:00:00 2001 From: David Spickett <[email protected]> Date: Wed, 1 Jul 2026 09:01:25 +0000 Subject: [PATCH 3/3] titles --- lldb/docs/resources/test.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/lldb/docs/resources/test.md b/lldb/docs/resources/test.md index a7cd43bdae84c..9b6d3912659a5 100644 --- a/lldb/docs/resources/test.md +++ b/lldb/docs/resources/test.md @@ -413,19 +413,19 @@ 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 +### 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 +### 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 +### `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. @@ -439,7 +439,7 @@ debug server, start by looking at the reverse execution tests which use 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 +### 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. _______________________________________________ lldb-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
