1*bbb1b6f9SApple OSS Distributions# LLDB macro testing 2*bbb1b6f9SApple OSS Distributions 3*bbb1b6f9SApple OSS DistributionsHow to work with bundled unit test framework. 4*bbb1b6f9SApple OSS Distributions 5*bbb1b6f9SApple OSS DistributionsBe careful when touching common framework code. For larger changes, ask the Platform Triage team to 6*bbb1b6f9SApple OSS Distributionsvalidate that the changes work in their environment before integration. 7*bbb1b6f9SApple OSS Distributions 8*bbb1b6f9SApple OSS DistributionsUnit-test architecture supports two kinds of tests: 9*bbb1b6f9SApple OSS Distributions 10*bbb1b6f9SApple OSS Distributions- Standalone unit test \ 11*bbb1b6f9SApple OSS Distributions `tools/lldbmacros/tests/standalone_tests` 12*bbb1b6f9SApple OSS Distributions- LLDB based unit test \ 13*bbb1b6f9SApple OSS Distributions `tools/lldbmacros/tests/lldb_tests` 14*bbb1b6f9SApple OSS Distributions 15*bbb1b6f9SApple OSS Distributions**Standalone** unit tests replace _lldb_ and _lldbwrap_ modules with _MagicMock_ 16*bbb1b6f9SApple OSS Distributionsinstances. All tests in this location must not depend on LLDB. 17*bbb1b6f9SApple OSS Distributions 18*bbb1b6f9SApple OSS Distributions**LLDB** unit tests are run from LLDB's python interpreter. It is possible to 19*bbb1b6f9SApple OSS Distributionsaccess debugger/process/target from such test or invoke LLDB commands. This 20*bbb1b6f9SApple OSS Distributionsway a test can exercise full stack including SBAPI and expression handlers. 21*bbb1b6f9SApple OSS Distributions 22*bbb1b6f9SApple OSS Distributions## How to run tests 23*bbb1b6f9SApple OSS Distributions 24*bbb1b6f9SApple OSS DistributionsStandalone tests do not need LLDB and can be run with: 25*bbb1b6f9SApple OSS Distributions```sh 26*bbb1b6f9SApple OSS DistributionsPYTHON=tools/lldbmacros python3 tools/lldbmacros/tests/runtest.py <kernel> 27*bbb1b6f9SApple OSS Distributions``` 28*bbb1b6f9SApple OSS Distributions 29*bbb1b6f9SApple OSS DistributionsTo run all tests (including LLDB based ones) a developer has to install 30*bbb1b6f9SApple OSS DistributionsXCode and configure properly Python's path: 31*bbb1b6f9SApple OSS Distributions 32*bbb1b6f9SApple OSS Distributions```sh 33*bbb1b6f9SApple OSS DistributionsPYTHONPATH="tools/lldbmacros:`xcrun --toolchain ios lldb -P`"xcrun --toolchain ios python3 tools/lldbmacros/tests/runtest.py <kernel> 34*bbb1b6f9SApple OSS Distributions``` 35*bbb1b6f9SApple OSS Distributions 36*bbb1b6f9SApple OSS DistributionsDefault runner supports few options: 37*bbb1b6f9SApple OSS Distributions 38*bbb1b6f9SApple OSS Distributions * `-v` enables verbose output from unit test framework 39*bbb1b6f9SApple OSS Distributions * `-d` enables debug logging and more detailed exception reports 40*bbb1b6f9SApple OSS Distributions * `-c <path>` outputus HTML coverage if `coverage` module is installed 41*bbb1b6f9SApple OSS Distributions 42*bbb1b6f9SApple OSS Distributions## Mocking framework 43*bbb1b6f9SApple OSS Distributions 44*bbb1b6f9SApple OSS DistributionsThe goal of the mocking framework is to enhance existing mocking solutions 45*bbb1b6f9SApple OSS Distributionsrather than building completely new framework. A test should still rely on 46*bbb1b6f9SApple OSS Distributions`unittest.mock` and cover specific needs with additional mocks provided by 47*bbb1b6f9SApple OSS Distributionsthis framework. 48*bbb1b6f9SApple OSS Distributions 49*bbb1b6f9SApple OSS DistributionsA test developer has three options how to handle mocking in a test: 50*bbb1b6f9SApple OSS Distributions 51*bbb1b6f9SApple OSS Distributions* `unittest.mock` that covers general purpose Python mocking. 52*bbb1b6f9SApple OSS Distributions* `lldbmock.valuemock` designed to mock away `value` class instances. 53*bbb1b6f9SApple OSS Distributions* `lldbmock.memorymock` designed to provide real object in target's memory. 54*bbb1b6f9SApple OSS Distributions 55*bbb1b6f9SApple OSS DistributionsExamples of usage can be found in: \ 56*bbb1b6f9SApple OSS Distributions `tools/lldbmacros/tests/lldb_tests/test_examples.py` 57*bbb1b6f9SApple OSS Distributions 58*bbb1b6f9SApple OSS Distributions### lldbmock.valuemock 59*bbb1b6f9SApple OSS Distributions 60*bbb1b6f9SApple OSS DistributionsA very simple mocking designed for replacing a `value` class instance or 61*bbb1b6f9SApple OSS Distributionssome similar construct in the code. 62*bbb1b6f9SApple OSS Distributions 63*bbb1b6f9SApple OSS DistributionsThe `ValueMock` class parses given `SBType` and recreates recursively whole 64*bbb1b6f9SApple OSS Distributionshierarchy of `MagicMock` instances. Final result looks like a value class but 65*bbb1b6f9SApple OSS Distributionsit does not implement any value class logic or methods. 66*bbb1b6f9SApple OSS Distributions 67*bbb1b6f9SApple OSS DistributionsIt does not perform any extra logic to handle special types like `union`. 68*bbb1b6f9SApple OSS DistributionsA developer has to correctly populate all members that overlap because this 69*bbb1b6f9SApple OSS Distributionsmock treats all such members as unique. 70*bbb1b6f9SApple OSS Distributions 71*bbb1b6f9SApple OSS DistributionsAuto generating mock specification from kernel under test allows checking that 72*bbb1b6f9SApple OSS Distributionsall referenced members do exist in the final binary. Broken reference will 73*bbb1b6f9SApple OSS Distributionsresult either in test or tested code failure. 74*bbb1b6f9SApple OSS Distributions 75*bbb1b6f9SApple OSS Distributions### lldbmock.memorymock 76*bbb1b6f9SApple OSS Distributions 77*bbb1b6f9SApple OSS DistributionsThe goal of memory mock is to provide easy to use interface for a test developer 78*bbb1b6f9SApple OSS Distributionsto describe object in target's memory. From technical perspective this is a data 79*bbb1b6f9SApple OSS Distributionsserializer that reflects memory location and representation of given SBType's 80*bbb1b6f9SApple OSS Distributionsmembers. 81*bbb1b6f9SApple OSS Distributions 82*bbb1b6f9SApple OSS DistributionsThe framework provides two kinds of mocks: 83*bbb1b6f9SApple OSS Distributions 84*bbb1b6f9SApple OSS Distributions * `RawMock` that is suitable to place unstructured data into target's memory. 85*bbb1b6f9SApple OSS Distributions * `MemoryMock` that mirrors given `SBType` and serializes data into target's 86*bbb1b6f9SApple OSS Distributions memory. 87*bbb1b6f9SApple OSS Distributions 88