test/py: add docs for gdbserver and pytest options

Add documentation describing the new --gdbserver feature, and some common
pytest options.

Signed-off-by: Stephen Warren <swarren@nvidia.com>
Acked-by: Simon Glass <sjg@chromium.org>

1 files changed, 56 insertions, 4 deletions

diff --git a/test/py/README.md b/test/py/README.md
index 8036299..ba1674c 100644
--- a/test/py/README.md
+++ b/test/py/README.md
@@ -76,6 +76,43 @@ will be written to `${build_dir}/test-log.html`. This is best viewed in a web
 browser, but may be read directly as plain text, perhaps with the aid of the
 `html2text` utility.
 
+### Testing under a debugger
+
+If you need to run sandbox under a debugger, you may pass the command-line
+option `--gdbserver COMM`. This causes two things to happens:
+
+- Instead of running U-Boot directly, it will be run under gdbserver, with
+  debug communication via the channel `COMM`. You can attach a debugger to the
+  sandbox process in order to debug it. See `man gdbserver` and the example
+  below for details of valid values for `COMM`.
+- All timeouts in tests are disabled, allowing U-Boot an arbitrary amount of
+  time to execute commands. This is useful if U-Boot is stopped at a breakpoint
+  during debugging.
+
+A usage example is:
+
+Window 1:
+```shell
+./test/py/test.py --bd sandbox --gdbserver localhost:1234
+```
+
+Window 2:
+```shell
+gdb ./build-sandbox/u-boot -ex 'target remote localhost:1234'
+```
+
+Alternatively, you could leave off the `-ex` option and type the command
+manually into gdb once it starts.
+
+You can use any debugger you wish, so long as it speaks the gdb remote
+protocol, or any graphical wrapper around gdb.
+
+Some tests deliberately cause the sandbox process to exit, e.g. to test the
+reset command, or sandbox's CTRL-C handling. When this happens, you will need
+to attach the debugger to the new sandbox instance. If these tests are not
+relevant to your debugging session, you can skip them using pytest's -k
+command-line option; see the next section.
+
 ## Command-line options
 
 - `--board-type`, `--bd`, `-B` set the type of the board to be tested. For
@@ -98,10 +135,25 @@ browser, but may be read directly as plain text, perhaps with the aid of the
   data. This is test data that may be re-used across test runs, such as file-
   system images.
 
-`pytest` also implements a number of its own command-line options. Please see
-`pytest` documentation for complete details. Execute `py.test --version` for
-a brief summary. Note that U-Boot's test.py script passes all command-line
-arguments directly to `pytest` for processing.
+`pytest` also implements a number of its own command-line options. Commonly used
+options are mentioned below. Please see `pytest` documentation for complete
+details. Execute `py.test --version` for a brief summary. Note that U-Boot's
+test.py script passes all command-line arguments directly to `pytest` for
+processing.
+
+- `-k` selects which tests to run. The default is to run all known tests. This
+  option takes a single argument which is used to filter test names. Simple
+  logical operators are supported. For example:
+  - `'ums'` runs only tests with "ums" in their name.
+  - ``ut_dm'` runs only tests with "ut_dm" in their name. Note that in this
+    case, "ut_dm" is a parameter to a test rather than the test name. The full
+    test name is e.g. "test_ut[ut_dm_leak]".
+  - `'not reset'` runs everything except tests with "reset" in their name.
+  - `'ut or hush'` runs only tests with "ut" or "hush" in their name.
+  - `'not (ut or hush)'` runs everything except tests with "ut" or "hush" in
+    their name.
+- `-s` prevents pytest from hiding a test's stdout. This allows you to see
+  U-Boot's console log in real time on pytest's stdout.
 
 ## Testing real hardware