1# Introduction 2XNU's LLDB macros are tools to aid debugging the kernel. 3 4There are several types of tests. 5 6# Types of tests and how to run them 7## ScriptedProcess 8LLDB's ScriptedProcess enables creating a session for a given binary with artificial state. 9For LLDB macros testing, this allows verifying assumptions about structs. 10From the binary, LLDB knows about the fields of a struct, and test attempting to access them will fail if they've been 11renamed or removed. 12Theoretically a ScriptedProcess could be used to validate macros, but getting valid XNU state is an issue. 13 14Run with e.g. 15`PYTHONPATH=tools/lldbmacros xcrun --toolchain macos python3 tools/lldbmacros/tests/runtests.py BUILD/obj/DEVELOPMENT_ARM64_T6031/kernel.development.t6031` 16 17## *Any* LLDB session smoke tests 18 19To run the smoke LLDB tests within a LLDB session anywhere - either at-desk VM (quickest), at-desk machine or a coredump 20(takes much more time). 21 22### Disclaimers 231. There are some macros that are ignored, see `IGNORES` variable (xno/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py) for more information. 242. There are some macros that are skipped for now - we will add at a later time. 253. Validation occurs only for the exit code of the macro run, not for the output. 26 27### Triggering the tests within a LLDB session (Live VM / Tethered device / Coredump) 281. `xcrun --sdk macosx.internal lldb [-c coredump file]` 292. `command script import <xnu_root>/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py` 30----- 31Notice! if you need a gdb-remote session, you will have to enter it manually before running the macros. 32* `gdb <[host=127.0.0.1:]port>` (e.g. 8000 or 1.3.3.7:8000). 33----- 343. `macro_exec [macro_1] [macro_2] [...]` 354. `macro_coverage` 36 37### Triggering the tests from your local machine (at-desk) Live VM / Tethered Device 381. `xcrun --sdk macosx.internal python3 <xnu_root>/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py [[host=127.0.0.1:]<port>]` 39 40### Triggering the tests with customizations (pytest) - Live VM / Tethered Device 411. `xcrun --sdk macosx.internal python3 -m pytest <pytest_options> [--gdb-remote [host=127.0.0.1:]<port>] <xnu_root>/tools/lldbmacros/tests/integration_smoke/test_lldb_macros.py <pytest_arguments>` 42