From 342aeeb62b638687fcfb78a32fc4859e7857f67b Mon Sep 17 00:00:00 2001 From: James Prestwood Date: Wed, 28 Aug 2019 12:33:34 -0700 Subject: [PATCH] doc: add some documentation about --shell --- doc/test-runner.txt | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/doc/test-runner.txt b/doc/test-runner.txt index fe455de2..4b0ba420 100644 --- a/doc/test-runner.txt +++ b/doc/test-runner.txt @@ -425,3 +425,31 @@ class TestFailingCase(unittest.TestCase): if __name__ == '__main__': unittest.main() #~~~~~~~~~~~~~~~~~~ end of alwaysFailingTest.py ~~~~~~~~~~~~~~~~~~~~~~~~~ + +Using the 'shell' feature +--------------------------- + +The --shell,-s flag allows you to boot into a shell inside the test-runner VM. +If this flag is used the python test will not actually run, only the environment +will be setup. Tis is useful for diagnosing issues with a particular test +quickly without having to modify the python test and restart the VM. The shell +flag is meant to be used in conjunction with --autotest,-A. If no specific test +is specified test-runner will default to the 'shell' test, which is just an +empty test with one adapter. + +Using the shell with real hardware (--hw flag) is even more powerful. If your +system is setup for USB/PCI passthrough you can expose physical network cards +in the VM and use them in the shell sandbox. This allows you to try out +different kernels in the VM very quickly (no reboots/swapping out kernels on +the host system). + +Here are some examples of --shell usage: + +Setup environment for 'testWPA' and boot into shell: +./test-runner -k -A testWPA --shell + +Boot directly into 'shell' test (sandbox): +./test-runner -k --shell + +Use hardware passthrough: +./test-runner -k --hw --shell