sippy_cup 0.1.1 → 0.2.0

data/CHANGELOG.md

@@ -1,5 +1,11 @@
-# [0.1.1](https://github.com/bklang/sippy_cup)
+# [0.2.0](https://github.com/bklang/sippy_cup/compare/v0.1.1...v0.2.0)
+* Add new command-line ability to parse and run Sippy Cup YAML
+* Bugfixes & documentation
+
+# [0.1.1](https://github.com/bklang/sippy_cup/compare/v0.1.0...v0.1.1)
 * Allow running SIPp directly from SippyCup
 * New shortcut command for common answer scenario: #wait_for_answer
 * Allow specifying output file name/location
 
+# [0.1.0](https://github.com/bklang/sippy_cup/releases/tag/v0.1.0)
+* Initial Release

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Mojo Lingo LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.markdown

@@ -1,20 +1,37 @@
-Sippy Cup
-=========
+# Sippy Cup
 
-Sippy Cup is a tool to generate [SIPp](http://sipp.sourceforge.net/) load test profiles and the corresponding media in PCAP format. The goal is to take an input document that describes a load test in a very simple way (call this number, wait this many seconds, send this digit, wait a few more seconds, etc).  The ideas are taken from [LoadBot](https://github.com/mojolingo/ahn-loadbot), but the goal is for a more performant load generating tool with no dependency on Asterisk.
+## Overview
+
+### The Problem
+
+Load testing voice systems, and voice applications in particular, is tricky.  While several commercial tools exist, there is really only one tool in the Open Source world that is good at efficiently generating SIP load: [SIPp](http://sipp.sourceforge.net/).  While SIPp does a good job of generating load, it is somewhat clumsy to use, due to a verbose XML format for scenarios, a confusing set of command line parameters, and worst of all, a lack of tools to create media needed to interact with voice applications.
+
+The last problem is especially tricky: Imagine you want to load test an IVR. Testing requires:
+
+* calling a test number
+* waiting a certain amount of time
+* sending some DTMF
+* waiting some more
+* sending more DTMF
+* etc....
 
+To test this with SIPp you need a PCAP file that contains the properly timed DTMF interactions. Since there is no tool to create this media, it is usually necessary to call into the system and record the PCAP, isolate the RTP from the captured packets with something like Wireshark, then connect the pcap file into the SIPp scenario.  This process is time consuming and error prone, meaning that testing isn't done as often as it should.
 
-Requirements
-------------
+SippyCup aims to help solve these problems.
+
+### The Solution
+
+Sippy Cup is a tool to generate [SIPp](http://sipp.sourceforge.net/) load test profiles and the corresponding media in PCAP format. The goal is to take an input document that describes a load test in a very simple way (call this number, wait this many seconds, send this digit, wait a few more seconds, etc).  The ideas are taken from [LoadBot](https://github.com/mojolingo/ahn-loadbot), but the goal is for a more performant load generating tool with no dependency on Asterisk.
+
+## Requirements
 
 SippyCup relies on the following to generate scenarios and the associated media PCAP files:
 
-* Ruby 1.9.3 (2.0.0 NOT YET SUPPORTED; see [PacketFu Issue #28](https://github.com/todb/packetfu/issues/28)
+* Ruby 1.9.3 (2.0.0 NOT YET SUPPORTED; see [PacketFu Issue #28](https://github.com/todb/packetfu/issues/28))
 * [SIPp](http://sipp.sourceforge.net/) - Download from http://sourceforge.net/projects/sipp/files/
+* "root" user access via sudo: needed to run SIPp so it can bind to raw network sockets
 
-
-Installation
-------------
+## Installation
 
 If you do not have Ruby 1.9.3 available (check using `ruby --version`), we recommend installing Ruby with [RVM](http://rvm.io)
 
@@ -26,9 +43,41 @@ gem install sippy_cup
 
 Now you can start creating scenario files like in the examples below.
 
+## Examples
 
-Example
--------
+### Simple Example
+
+```YAML
+---
+source: 192.0.2.15
+destination: 192.0.2.200
+max_concurrent: 10
+calls_per_second: 5
+number_of_calls: 20
+steps:
+  - invite
+  - wait_for_answer
+  - ack_answer
+  - sleep 3
+  - send_digits '3125551234'
+  - sleep 5
+  - send_digits '#'
+  - wait_for_bye
+```
+
+Both `source` and `destination` above may be optionally supplied with a port number, eg. `192.0.2.200:5061`
+
+Next, compile and run the scenario:
+
+```Shell
+$ sippy_cup -cr my_test_scenario.yml
+Compiling media to /Users/bklang/src/sippy_cup/my_test_scenario_xml.pcap...done.
+Compiling scenario to /Users/bklang/src/sippy_cup/my_test_scenario_xml.pcap...done.
+"Preparing to run SIPp command: sudo sipp -i 192.0.2.15 -p 8836 -sf /Users/bklang/src/sippy_cup/my_test_scenario.xml -l 10 -m 20 -r 5 -s 1 > /dev/null 2>&1"
+$
+```
+
+### Example embedding SIPp in another Ruby process
 
 ```Ruby
 require 'sippy_cup'
@@ -43,13 +92,11 @@ scenario = SippyCup::Scenario.new 'Sippy Cup', source: '192.168.5.5:10001', dest
   s.sleep 5
   s.send_digits '#'
 
-  s.receive_bye
-  s.ack_bye
+  s.wait_for_bye
 end
 
-# Create the scenario XML, PCAP media, and YAML options. File will be named after the scenario name, in our case:
+# Create the scenario XML and PCAP media. File will be named after the scenario name, in our case:
 # * sippy_cup.xml
-# * sippy_cup.yml
 # * sippy_cup.pcap
 scenario.compile!
 ```
@@ -58,21 +105,48 @@ The above code can either be executed as a standalone Ruby script and run with S
 ```Ruby
 require 'sippy_cup/tasks'
 ```
+
 Then running the rake task `rake sippy_cup:compile[sippy_cup.rb]`
 
 And finally running `rake sippy_cup:run[sippy_cup.yml]` to execute the scenario.
 
-Customize Your Scenarios
-------------------------
+## Customize Your Scenarios
 
-### Alternate File Path
+### Available Scenario Steps
 
-Don't want your scenario to end up in the same directory as your script? Need the filename to be different than the scenario name? No problem! Try:
+Each command below can take [SIPp attributes](http://sipp.sourceforge.net/doc/reference.html) as optional arguments.
+
+* `sleep <seconds>` Wait a specified number of seconds
+* `invite` Send a SIP INVITE to the specified target
+* `receive_trying` Expect to receive a `100 Trying` response from the target
+* `receive_ringing` Expect to receive a `180 Ringing` response from the target
+* `receive_progress` Expect to receive a `183 Progress` response from the target
+* `receive_answer` Expect to receive a `200 OK` (answering the call) response from the target
+* `wait_for_answer` Convenient shortcut for `receive_trying; receive_ringing; receive_progress; receive_answer`, with all but the `answer` marked as optional
+* `ack_answer` Send an `ACK` in response to a `200 OK`
+* `send_digits <string>` Send a DTMF string. May send one or many digits, including `0-9`, `*`, `#`, and `A-D`
+* `send_bye` Send a `BYE` (hangup request)
+* `receive_bye` Expect to receive a `BYE` from the target
+* `ack_bye` Send an `ACK` in response to a `BYE`
+* `wait_for_hangup` Convenient shortcut for `receive_bye; ack_bye`
+
+### Alternate Output File Path
+
+Don't want your scenario to end up in the same directory as your script? Need the filename to be different than the scenario name? No problem!
+
+For the `sippy_cup` YAML specification, use `scenario`:
+
+```YAML
+---
+scenario: /path/to/scenario.xml
+```
+
+Or, in Ruby:
 
 ```Ruby
 my_opts = { source: '192.168.5.5:10001', destination: '10.10.0.3:19995', filename: '/path/to/somewhere' }
 s = SippyCup::Scenario.new 'SippyCup', my_opts do
-  ...
+  # scenario definitions here...
 end
 ```
 
@@ -80,40 +154,27 @@ This will create the files `somewhere.xml`, `somewhere.pcap`, and `somewhere.yml
 
 ### Customizing the Test Run
 
-By default, sippy cup will automatically generate a YAML file with the following contents:
-```YAML
----
-:source: 127.0.0.1
-:destination: 127.0.0.1
-:scenario: /path/to/scenario.xml
-:max_concurrent: 10
-:calls_per_second: 5
-:number_of_calls: 20
-```
 
 Each parameter has an impact on the test, and may either be changed once the YAML file is generated or specified in the options hash for `SippyCup::Scenario.new`. In addition to the default parameters, some additional parameters can be set:
 <dl>
-  <dt>:source_port:</dt>
-  <dd>The local port from which to originate SIP traffic. This defaults to port 8836</dd>
-
-  <dt>:stats_file:</dt>
+  <dt>stats_file</dt>
   <dd>Path to a file where call statistics will be stored in a CSV format, defaults to not storing stats</dd>
 
-  <dt>:stats_interval</dt>
+  <dt>stats_interval</dt>
   <dd>Frequency (in seconds) of statistics collections. Defaults to 10. Has no effect unless :stats_file is also specified</dd>
 
-  <dt>:sip_user:</dt>
+  <dt>sip_user</dt>
   <dd>SIP username to use. Defaults to "1" (as in 1@127.0.0.1)</dd>
 
-  <dt>:full_sipp_output:</dt>
+  <dt>full_sipp_output</dt>
   <dd>By default, SippyCup will hide SIPp's command line output while running a scenario. Set this parameter to `true` to see full command line output</dd>
 </dl>
 
-### Additional SIPp Attributes
+### Additional SIPp Scenario Attributes
 
 With Sippy Cup, you can add additional attributes to each step of the scenario:
-```Ruby
 
+```Ruby
 #This limits the amount of time the server has to reply to an invite (3 seconds)
 s.receive_answer timeout: 3000
 
@@ -125,4 +186,14 @@ s.receive_answer optional: true
 s.receive_answer timeout: 3000, crlf: true
 ```
 
-For more information on possible attributes, visit the [SIPp Documentation](http://sipp.sourceforge.net/doc/reference.html)
+For more information on possible attributes, visit the [SIPp Documentation](http://sipp.sourceforge.net/doc/reference.html).
+
+## Credits
+
+Copyright (C) 2013 [Mojo Lingo LLC](https://mojolingo.com)
+
+Sippy Cup is released under the [MIT license](http://opensource.org/licenses/MIT). Please see the [LICENSE](https://github.com/bklang/sippy_cup/blob/master/LICENSE) file for details.
+
+Sippy Cup was created by [Ben Klang](https://twitter.com/bklang) and [Will Drexler](https://github.com/wdrexler) with support from [Mojo Lingo](https://mojolingo.com) and their clients.
+
+"Sippy Cup" name suggested by [Jamey Owens](https://github.com/vindir)

data/bin/sippy_cup

@@ -1,3 +1,78 @@
 #!/usr/bin/env ruby
 
 require 'sippy_cup'
+require 'getoptlong'
+
+def usage
+  puts "#{$0} [OPTS] </path/to/sippy_cup_definition.yml>"
+  puts
+  puts "--compile, -c  Compile the given scenario YAML to XML and PCAP"
+  puts "--run, -r      Run the scenario. If used without -c, must supply a previously"
+  puts "               compiled SippyCup file"
+  puts "--help, -h     Print this usage information"
+  puts "--version, -v  Print SippyCup version"
+end
+
+opts = GetoptLong.new(
+  ['--compile', '-c', GetoptLong::NO_ARGUMENT],
+  ['--run', '-r', GetoptLong::NO_ARGUMENT],
+  ['--help', '-h', GetoptLong::NO_ARGUMENT],
+  ['--version', '-V', GetoptLong::NO_ARGUMENT]
+)
+
+@compile = false
+@run = false
+opts.each do |opt, arg|
+  case opt
+  when '--compile'
+    @compile = true
+    @definition_file = arg
+  when '--run'
+    @run = true
+    @compiled_file = arg
+  when '--help'
+    usage
+    exit 0
+  when '--version'
+    puts "SippyCup version #{SippyCup::VERSION}"
+    exit 0
+  end
+end
+
+unless ARGV.count == 1
+  puts "ERROR: Must supply the SippyCup definition file"
+  puts
+  usage
+  exit 1
+end
+
+@definition_file = ARGV.shift
+
+unless File.readable? @definition_file
+  puts "ERROR: Unable to read definition file"
+  puts
+  usage
+  exit 1
+end
+
+unless @compile || @run
+  puts "No action (compile or run) specified. Exiting."
+  usage
+  exit 1
+end
+
+@definition = YAML.load File.read @definition_file
+@scenario_base = @definition_file.gsub /\.yml$/, ''
+
+unless @definition.has_key? :scenario
+  @definition[:scenario] = "#{@scenario_base}.xml"
+end
+unless @definition.has_key? :name
+  @definition[:name] = @definition[:scenario]
+end
+
+
+runner = SippyCup::Runner.new @definition
+runner.compile if @compile
+runner.run if @run
+

data/lib/sippy_cup.rb

@@ -1,6 +1,7 @@
 %w{
   scenario
   media
+  runner
 }.each {|r| require "sippy_cup/#{r}"}
 
 module SippyCup

data/lib/sippy_cup/runner.rb

@@ -1,14 +1,31 @@
 require 'yaml'
+require 'active_support/core_ext/hash'
 
 module SippyCup
   class Runner
     def initialize(opts = {})
-      @options = opts
+      @options = ActiveSupport::HashWithIndifferentAccess.new opts
+    end
+
+    def compile
+      raise ArgumentError, "Must provide scenario steps" unless @options[:steps]
+      scenario = SippyCup::Scenario.new @options[:name].titleize, source: @options[:source], destination: @options[:destination]
+      @options[:steps].each do |step|
+        instruction, arg = step.split ' ', 2
+        if arg && !arg.empty?
+          # Strip leading/trailing quotes if present
+          arg.gsub!(/^'|^"|'$|"$/, '')
+          scenario.send instruction.to_sym, arg
+        else
+          scenario.send instruction
+        end
+      end
+      scenario.compile!
     end
 
     def prepare_command
       [:scenario, :source, :destination, :max_concurrent, :calls_per_second, :number_of_calls].each do |arg|
-        raise "Must provide #{arg}!" unless @options[arg]
+        raise ArgumentError, "Must provide #{arg}!" unless @options[arg]
       end
       command = "sudo sipp"
       source_port = @options[:source_port] || '8836'
@@ -34,4 +51,4 @@ module SippyCup
     end
 
   end
-end
+end

data/lib/sippy_cup/scenario.rb

@@ -15,7 +15,7 @@ module SippyCup
       @filename = args[:filename] || name.downcase.gsub(/\W+/, '_')
       @filename = File.expand_path @filename
       @doc = builder.doc
-      @media = Media.new @from_addr, @from_port, @to_addr, @to_port
+      @media = Media.new '127.0.0.255', 55555, '127.255.255.255', 5060
       @scenario_opts = get_scenario_opts args
       @scenario = @doc.xpath('//scenario').first
 
@@ -45,6 +45,7 @@ module SippyCup
     end
 
     def sleep(seconds)
+      seconds = seconds.to_i
       # TODO play silent audio files to the server to fill the gap
       pause seconds * MSEC
       @media << "silence:#{seconds * MSEC}"
@@ -179,6 +180,14 @@ module SippyCup
       @scenario << new_send(msg, opts)
     end
 
+    ##
+    # Shortcut method that tells SIPp receive a BYE and acknowledge it
+    def wait_for_hangup(opts = {})
+      receive_bye(opts)
+      ack_bye(opts)
+    end
+
+
     def receive_bye(opts = {})
       opts.merge! request: 'BYE'
       @scenario << new_recv(opts)
@@ -206,14 +215,15 @@ module SippyCup
     end
 
     def compile!
+      print "Compiling media to #{@filename}.pcap..."
       File.open "#{@filename}.xml", 'w' do |file|
         file.write @doc.to_xml
       end
+      puts "done."
 
-      File.open "#{@filename}.yml", 'w' do |file|
-        file.write @scenario_opts.to_yaml
-      end
+      print "Compiling scenario to #{@filename}.pcap..."
       compile_media.to_file filename: "#{@filename}.pcap"
+      puts "done."
     end
 
   private

data/lib/sippy_cup/version.rb

@@ -1,5 +1,5 @@
 # encoding: utf-8
 
 module SippyCup
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/sippy_cup.gemspec

@@ -19,6 +19,7 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency 'packetfu'
   s.add_runtime_dependency 'nokogiri', ["~> 1.6.0"]
+  s.add_runtime_dependency 'activesupport', ["> 3.0"]
 
   s.add_development_dependency 'guard-rspec'
   s.add_development_dependency 'rspec', ["~> 2.11"]

data/spec/sippy_cup/scenario_spec.rb

@@ -4,7 +4,7 @@ describe SippyCup::Scenario do
   let(:default_args) { {source: '127.0.0.1:5060', destination: '10.0.0.1:5080'} }
 
   it %q{should create a media stream on initialization} do
-    SippyCup::Media.should_receive(:new).once.with('127.0.0.1', '5060', '127.0.0.2', '5061')
+    SippyCup::Media.should_receive(:new).once
     SippyCup::Scenario.new 'Test', source: '127.0.0.1:5060', destination: '127.0.0.2:5061'
   end
 

metadata

@@ -2,7 +2,7 @@
 name: sippy_cup
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.1.1
+  version: 0.2.0
 platform: ruby
 authors: 
 - Ben Klang
@@ -11,7 +11,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-08-08 00:00:00 Z
+date: 2013-08-23 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: packetfu
@@ -36,60 +36,71 @@ dependencies:
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: guard-rspec
+  name: activesupport
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: "3.0"
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: guard-rspec
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
-  version_requirements: *id003
+  version_requirements: *id004
 - !ruby/object:Gem::Dependency 
   name: rspec
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+  requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
       - !ruby/object:Gem::Version 
         version: "2.11"
   type: :development
-  version_requirements: *id004
+  version_requirements: *id005
 - !ruby/object:Gem::Dependency 
   name: simplecov
   prerelease: false
-  requirement: &id005 !ruby/object:Gem::Requirement 
+  requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
-  version_requirements: *id005
+  version_requirements: *id006
 - !ruby/object:Gem::Dependency 
   name: simplecov-rcov
   prerelease: false
-  requirement: &id006 !ruby/object:Gem::Requirement 
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
-  version_requirements: *id006
+  version_requirements: *id007
 - !ruby/object:Gem::Dependency 
   name: ci_reporter
   prerelease: false
-  requirement: &id007 !ruby/object:Gem::Requirement 
+  requirement: &id008 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
         version: "0"
   type: :development
-  version_requirements: *id007
+  version_requirements: *id008
 description: This tool makes it easier to generate SIPp load tests with DTMF interactions.
 email: 
 - bklang&mojolingo.com
@@ -106,6 +117,7 @@ files:
 - CHANGELOG.md
 - Gemfile
 - Guardfile
+- LICENSE
 - README.markdown
 - Rakefile
 - bin/sippy_cup