From 0ac45953a77b47d29fa58505c47d8cb4527a2242 Mon Sep 17 00:00:00 2001 From: Tyler Goodlet Date: Mon, 1 Feb 2016 15:39:38 -0500 Subject: [PATCH] Docs bump --- README.md | 70 +++++++++++++++++++++++++++++++++++++------------ pysipp/agent.py | 8 +++++- setup.py | 4 +-- 3 files changed, 62 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 1abf061..48663df 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,47 @@ # `pysipp` is for people who hate SIPp -and use it for automated testing because it gets the job done... +but (want to) use it for automated testing because it gets the job done... ## What is it? -A python wrapper for easily configuring and launching the infamous -[SIPp](http://sipp.sourceforge.net/). It allows for invoking multi-UA -scenarios from Python thus avoiding nightmarish shell command concoctions. +Python configuring and launching the infamous +[SIPp](http://sipp.sourceforge.net/) using an api inspired by +[requests](http://docs.python-requests.org/) +## It definitely lets you -## Quick start +- Launch multi-UA scenarios (aka SIPp subprocesses) sanely + * avoids nightmarish shell command concoctions from multiple terminals + * allows for complex functional or end-to-end SIP testing +- Reuse your existing SIPp XML scripts +- Integrate nicely with [pytest](http://pytest.org/) + + +## It doesn't try to + +- Auto-generate SIPp XML scripts like [sippy_cup](https://github.com/mojolingo/sippy_cup) + * we believe this is the wrong way to work around the problem of SIPp's shitty XML control language + + +## Usage Launching the default uac scenario is a short line: ```python import pysipp -pysipp.client('10.10.8.88', 5060)() +pysipp.client(destaddr=('10.10.8.88', 5060))() ``` -Manually running the default uac <-> uas scenario is simple as well: +Manually running the default `uac` --calls--> `uas` scenario is also simple: ```python -uas = pysipp.server(sockaddr=('10.10.8.88', 5060)) -uac = pysipp.client(*uas.sockaddr) -uas(block=False) +uas = pysipp.server(srcaddr=('10.10.8.88', 5060)) +uac = pysipp.client(uas.srcaddr) +uas(block=False) # returns a `pysipp.launch.PopenRunner` instance by default uac() ``` For more complex multi-UA orchestrations we can use -a `pysipp.scenario`. The scenario above is the default: +a `pysipp.scenario`. The scenario from above is the default +agent configuration: ```python scen = pysipp.scenario() @@ -43,12 +58,24 @@ test_scenario/ referer_uas.xml referee_uas.xml ``` -and your DUT is listening on socket `10.10.8.1:5060` + +If you've configured your DUT to listen for for SIP on `10.10.8.1:5060` +and route traffic to the destination specified in the SIP `TO:` header +and your local ip address is `10.10.8.8`: ```python scen = pysipp.scenario(scendir='path/to/test_scenario/', - proxy=('10.10.8.1', 5060) + proxyaddr=('10.10.8.1', 5060) ) + +# setup local server sockets +for port, ua in enumerate(scen.servers.values(), 5080): + ua.srcaddr = ('10.10.8.8', port) + +# point client at first server +scen.clientdefaults.destaddr = scen.servers.values()[0].srcaddr + +# run all agents in sequence starting with servers scen() ``` @@ -58,9 +85,14 @@ them: ```python for path, scen in pysipp.walk('path/to/scendirs/root/'): print("running scenario collected from {}".format(path)) + # ... steps from above ... scen() ``` +To see the mapping of SIPp command line args to `pysipp.agent.UserAgent` +attributes, take a look at `pysipp.command.sipp_spec`. +This should give you an idea of what can be set on each agent. + ## Features - (a)synchronous multi-scenario invocation @@ -71,16 +103,16 @@ for path, scen in pysipp.walk('path/to/scendirs/root/'): ## Dependencies -SIPp duh. Get the latest version on -[github](http://sipp.sourceforge.net/) +SIPp duh...Get the latest version on [github](https://github.com/SIPp/sipp) ## Install from git ``` -pip install pip install git+git://github.com/tgoodlet/pysipp.git +pip install git+git://github.com/tgoodlet/pysipp.git ``` + ## Hopes and dreams I'd love to see `pysipp` become a standard end-to-end unit testing tool for SIPp itself (particularly if paired with `pytest`). @@ -88,4 +120,8 @@ tool for SIPp itself (particularly if paired with `pytest`). Other thoughts are that someone might one day write actual Python bindings to the internals of SIPp such that a pure Python DSL can be used instead of the silly default xml SIP-flow mini-language. -If/when that happens, pysipp can serve as the front end interface. +If/when that happens, pysipp can serve as a front end interface. + + +## Advanced Usage +Coming soon... diff --git a/pysipp/agent.py b/pysipp/agent.py index 0c15015..1cf2a66 100644 --- a/pysipp/agent.py +++ b/pysipp/agent.py @@ -29,7 +29,9 @@ def setter(self, pair): for attr, val in zip(attrs, pair or repeat(None)): setattr(self, attr, val) - return property(getter, setter) + doc = "{} parameters composed as a tuple".format(', '.join(attrs)) + + return property(getter, setter, doc=doc) class UserAgent(command.SippCmd): @@ -159,6 +161,10 @@ def server(**kwargs): defaults = { 'scen_name': 'uas', } + if 'dstaddr' in kwargs: + raise ValueError( + "User agent server does not accept a destination address" + ) # override with user settings defaults.update(kwargs) return ua(**defaults) diff --git a/setup.py b/setup.py index 5394e76..ca76e04 100755 --- a/setup.py +++ b/setup.py @@ -28,8 +28,8 @@ setup( name="pysipp", version='0.1.alpha', - description='pysipp is Python wrapper for configuring and launching SIPp scenarios for use in' - ' automated testing', + description='pysipp is a SIPp scenario launcher for for use in' + ' automated VoIP testing', long_description=readme, license='GPLv2', author='Tyler Goodlet',