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/.
Neels Hofmeyr gerrit-no-reply at lists.osmocom.orgReview at https://gerrit.osmocom.org/5494 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(-) git pull ssh://gerrit.osmocom.org:29418/python/osmo-python-tests refs/changes/94/5494/1 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: newchange Gerrit-Change-Id: I94dcad257558b917cb54fc877122594cd164f496 Gerrit-PatchSet: 1 Gerrit-Project: python/osmo-python-tests Gerrit-Branch: master Gerrit-Owner: Neels Hofmeyr <nhofmeyr at sysmocom.de>