This is merely a historical archive of years 2008-2021, before the migration to mailman3.
A maintained and still updated list archive can be found at https://lists.osmocom.org/hyperkitty/list/gerrit-log@lists.osmocom.org/.
Harald Welte gerrit-no-reply at lists.osmocom.orgHarald Welte has submitted this change and it was merged.
Change subject: add cmdline doc to osmo_interact_* and osmo_verify_*
......................................................................
add cmdline doc to osmo_interact_* and osmo_verify_*
The tools are so far badly under-documented. Alleviate that by comprehensive
description and examples shown by -h option output. Hint at that from the
README.
Change-Id: I94dcad257558b917cb54fc877122594cd164f496
---
M osmopy/osmo_interact/common.py
M osmopy/osmo_interact/ctrl.py
M osmopy/osmo_interact/vty.py
3 files changed, 137 insertions(+), 8 deletions(-)
Approvals:
Harald Welte: Looks good to me, approved
Jenkins Builder: Verified
diff --git a/osmopy/osmo_interact/common.py b/osmopy/osmo_interact/common.py
index f7070ae..31f44a8 100644
--- a/osmopy/osmo_interact/common.py
+++ b/osmopy/osmo_interact/common.py
@@ -19,9 +19,9 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
'''
-Common code for osmo_interact_vty.py and osmo_interact_ctrl.py.
+Common code for VTY and CTRL interface interaction and transcript verification.
This implements all of application interaction, piping and verification.
-osmo_interact_{vty,ctrl}.py plug VTY and CTRL interface specific bits.
+vty.py and ctrl.py plug VTY and CTRL interface specific bits.
'''
# Our setup.py currently wants everything to be parsable by both py2 and py3.
@@ -370,8 +370,9 @@
return passed
-def common_parser():
- parser = argparse.ArgumentParser()
+def common_parser(doc=None):
+ parser = argparse.ArgumentParser(description=doc,
+ formatter_class=argparse.RawDescriptionHelpFormatter)
parser.add_argument('-r', '--run', dest='run_app_str',
help='command to run to launch application to test,'
' including command line arguments. If omitted, no'
diff --git a/osmopy/osmo_interact/ctrl.py b/osmopy/osmo_interact/ctrl.py
index b752351..85e7554 100755
--- a/osmopy/osmo_interact/ctrl.py
+++ b/osmopy/osmo_interact/ctrl.py
@@ -87,7 +87,30 @@
return split_responses
def main_interact_ctrl():
- parser = common_parser()
+ '''
+Run CTRL commands against a given application by stdin/stdout piping.
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, to start a session that allows typing CTRL commands on stdin:
+
+ osmo_interact_ctrl.py -p 4259 \\
+ -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db'
+
+Where 4259 is OsmoHLR's CTRL port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+ osmo_interact_ctrl.py -p 4259
+
+See also osmo_verify_transcript_vty.py, which allows verifying and updating
+complete CTRL session transcripts, in essence to write CTRL tests from a screen
+dump of a CTRL session.
+
+A VTY equivalent is osmo_interact_vty.py.
+'''
+ parser = common_parser(__doc__)
parser_add_run_args(parser)
args = parser.parse_args()
@@ -99,7 +122,44 @@
def main_verify_transcript_ctrl():
- parser = common_parser()
+ '''
+A CTRL transcript contains CTRL commands and their expected results.
+It looks like:
+
+"
+SET 1 var val
+SET_REPLY 1 var OK
+
+GET 2 var
+GET_REPLY 2 var val
+"
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, if above transcript example is in file test.ctrl, you can verify
+that OsmoHLR still shows this behavior by:
+
+ osmo_interact_ctrl.py -p 4259 \\
+ -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db' \\
+ test.ctrl
+
+Where 4259 is OsmoHLR's CTRL port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+ osmo_interact_ctrl.py -p 4259 test.ctrl
+
+If osmo-hlr has changed its behavior, e.g. some reply changed, the transcript
+can be automatically updated, which overwrites the file, like:
+
+ osmo_interact_ctrl.py -p 4259 -u test.ctrl
+
+See also osmo_interact_ctrl.py, which allows piping CTRL commands to stdin.
+
+A VTY equivalent is osmo_verify_transcript_vty.py.
+'''
+ parser = common_parser(__doc__)
parser_add_verify_args(parser)
parser.add_argument('-i', '--keep-ids', dest='keep_ids', action='store_true',
help='With --update, default is to overwrite the command IDs'
diff --git a/osmopy/osmo_interact/vty.py b/osmopy/osmo_interact/vty.py
index f34e87e..4704c09 100755
--- a/osmopy/osmo_interact/vty.py
+++ b/osmopy/osmo_interact/vty.py
@@ -156,7 +156,30 @@
return parser
def main_interact_vty():
- parser = common_parser()
+ '''
+Run VTY commands against a given application by stdin/stdout piping.
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, to extract the VTY reference XML file from osmo-hlr:
+
+ osmo_interact_vty.py -p 4258 --gen-xml-ref \\
+ -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db'
+
+Where 4258 is OsmoHLR's VTY port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+ osmo_interact_vty.py -p 4258 --gen-xml-ref
+
+See also osmo_verify_transcript_vty.py, which allows verifying and updating
+complete VTY session transcripts, in essence to write VTY tests from a screen
+dump of a VTY session.
+
+A Control interface equivalent is osmo_interact_ctrl.py.
+'''
+ parser = common_parser(__doc__)
parser_add_vty_args(parser)
parser_add_run_args(parser)
parser.add_argument('-X', '--gen-xml-ref', dest='gen_xml', action='store_true',
@@ -178,7 +201,52 @@
args.cmd_files, interact)
def main_verify_transcript_vty():
- parser = common_parser()
+ '''
+A VTY transcript contains VTY commands and their expected results.
+It looks like a screen dump of a live VTY session:
+
+"
+OsmoHLR> enable
+
+OsmoHLR# subscriber show imsi 123456789023000
+% No subscriber for imsi = '123456789023000'
+OsmoHLR# subscriber show msisdn 12345
+% No subscriber for msisdn = '12345'
+
+OsmoHLR# subscriber create imsi 123456789023000
+% Created subscriber 123456789023000
+ ID: 1
+ IMSI: 123456789023000
+ MSISDN: none
+ No auth data
+"
+
+Optionally, this can launch and tear down the application with -r.
+
+For example, if above transcript example is in file test.vty, you can verify
+that OsmoHLR still shows this behavior by:
+
+ osmo_interact_vty.py -p 4258 \\
+ -r 'osmo-hlr -c /etc/osmocom/osmo-hlr.cfg -l /tmp/hlr.db' \\
+ test.vty
+
+Where 4258 is OsmoHLR's VTY port number, see
+https://osmocom.org/projects/cellular-infrastructure/wiki/Port_Numbers
+
+If osmo-hlr is already running, this shortens to just
+
+ osmo_interact_vty.py -p 4258 test.vty
+
+If osmo-hlr has changed its behavior, e.g. some error message changed, the
+transcript can be automatically updated, which overwrites the file, like:
+
+ osmo_interact_vty.py -p 4258 -u test.vty
+
+See also osmo_interact_vty.py, which allows piping VTY commands to stdin.
+
+A Control interface equivalent is osmo_verify_transcript_ctrl.py.
+'''
+ parser = common_parser(__doc__)
parser_add_vty_args(parser)
parser_add_verify_args(parser)
args = parser.parse_args()
--
To view, visit https://gerrit.osmocom.org/5494
To unsubscribe, visit https://gerrit.osmocom.org/settings
Gerrit-MessageType: merged
Gerrit-Change-Id: I94dcad257558b917cb54fc877122594cd164f496
Gerrit-PatchSet: 2
Gerrit-Project: python/osmo-python-tests
Gerrit-Branch: master
Gerrit-Owner: Neels Hofmeyr <nhofmeyr at sysmocom.de>
Gerrit-Reviewer: Harald Welte <laforge at gnumonks.org>
Gerrit-Reviewer: Jenkins Builder