From 8ccd99a3a9fabceb1a9f298c54f0b9cb13cbcc92 Mon Sep 17 00:00:00 2001 From: Pau Espin Pedrol Date: Mon, 16 Mar 2020 19:48:02 +0100 Subject: doc/manuals: Add proper content for Debugging section Change-Id: Iaed2544d59f7c5dd69eef3ddfade544b35c837cd --- doc/manuals/chapters/debugging.adoc | 65 ++++++++++++++++++++++++++++++++++++- 1 file changed, 64 insertions(+), 1 deletion(-) (limited to 'doc') diff --git a/doc/manuals/chapters/debugging.adoc b/doc/manuals/chapters/debugging.adoc index bea1e5c..6c32e7a 100644 --- a/doc/manuals/chapters/debugging.adoc +++ b/doc/manuals/chapters/debugging.adoc @@ -1,4 +1,67 @@ [[debugging]] == Debugging -*TODO*: describe how to invoke 'ipdb3' and step into a suite's test script +{app-name} is a complex program which at the same time orchestrates sets of +other complex programs to form a network of nodes. As such, it can be sometimes +challenging to find out what is going on during a trial run. This section aims +at providing some tips on how to debug possible issues. + +=== Logging level + +{app-name} runs by default under 'info' log level. As a first debugging step, it +is always a good idea to increase log verbosity. By switching to debug level +(command line argument '-l dbg'), a lot more information and events are displayed which +can give a much better idea to understand possible misconfigurations or wrong +steps. + +In any case, {app-name} usually provides several log files of interest. In +general, both a 'log' and a 'log_brief' are stored directly under the trial's +run directory, the first containing output up to debug level included, while the +second contains output up to info level included. Furthermore, {app-name} writes +a debug level log file per test case under each test's run directory. + +It is also in general useful to enable the '-T' command line argument. By using +it, it will instruct {app-name} to write the full backtrace to the log output +when something wrong happens, such an unexpected exception. + +[[pdb]] +=== python debugger + +{app-name} can be further debugged using python's debugger 'pdb'. Easiest way to +use it is to modify the python code were you want to break and add this code: +---- +import pdb; pdb.set_trace() +---- + +When {app-name} runs over that code, it will pause and provide a debugging +interactive shell, where one can inspect variables, execute code, etc. + +TIP: Remember {app-name} is managed by its internal main loop, meaning if you +jump into a debugger console you will still need to give back control to the +main loop for events to be processed and checks done. That can be done for +instance by calling the 'MainLoop.sleep(log_obj, secs)' internal API in general +or `sleep(secs)' under test context. + +=== debug suite + +Sometimes, however, one may be interested in debugging the behavior of the +software under test by {app-name} rather than {app-name} itself. For instance, +one may simply want to set up a full running network of nodes and keep it up +until some manual tests are done, or one may want {app-name} to do so at a given +point of time. + +To fulfill this kind of scenarios, {app-name} provides some code available for +tests to gain access to a high-level interactive console which is fully +integrated with {app-name}'s own main loop. So the approach here is usually to +write a regular test (with its corresponding <>) to set +up and run all required processes and then allow it to jump into the interactive +console instance. Then the test pulls received commands from it and it is +responsible for parsing and implementing them. One command can for instance ask +a modem to send an sms to another. Another command can for instance jump into a +<>. + +The interactive console is available to tests through the 'prompt' method, and +its implementation can be found under 'method input_polling' in 'util.py'. + +An interactive console example as explained in this section can be found under +the 'debug/interactive.py' test in osmo-gsm-tester.git. -- cgit v1.2.3