sippy_cup 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a8574849c4b88b7655ae212461569d8578ce21cb
-  data.tar.gz: 29d281da44037bff5259cd498bf86893882b41c3
+  metadata.gz: 6dd7d94d947152635902fedf054429f24ffa2de8
+  data.tar.gz: 621cb762e6bbef801190e0aeb855c82eeb9ed064
 SHA512:
-  metadata.gz: cd4c8d367d9d931018ce1a09870c0dc1c666fb692e38c51489b2c4ab2d5a63c23b468a0c5e42fe8b3b0c8826c3a6e4a2e0ba1872366c23da2ed383eefd71cc12
-  data.tar.gz: 0c0570408e0370593818fe55eb8756c7edbba3c88289e54208e3bb417425f304d4495f8d7b3ef513c484c34ed6500796091c8773808064a56ae4d4fdee983ba1
+  metadata.gz: 2423aa6cff4c235c5416b3f3fdbea27a973a79eff72fee91a56862386827eaa0a3d04bc260515d4031331623abbc2da0271589d7cb505380eb89c499434d2f34
+  data.tar.gz: a45bac4f0fbb3a98c5e40dcc8aa4761a49bf6b4d8f3452f8fed86f141456cc200148ab2c2739681a81abe53e07510259837f5f9a3dd23f5dd7fd74b15f061543

data/.gitignore

@@ -5,3 +5,6 @@
 Gemfile.lock
 .ruby-gemset
 tmp/
+/examples/*.xml
+/examples/*.pcap
+/examples/*.log

data/.travis.yml

@@ -8,8 +8,6 @@ rvm:
   - ruby-head
 matrix:
   allow_failures:
-    - rvm: 2.0.0
-    - rvm: 2.1.0
     - rvm: jruby-19mode
     - rvm: rbx-19mode
     - rvm: ruby-head

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+# develop
+
+# [0.5.0](https://github.com/mojolingo/sippy_cup/compare/v0.4.1...v0.5.0)
+SYNTAX CHANGES!
+This is a backward incompatible change. If upgrading from Sippy Cup 0.4.x please see the [documentation](http://mojolingo.github.io/sippy_cup/#available-scenario-steps) and the `Change` items below.
+You will also need to compile the latest [SIPp from Github](https://github.com/sipp/sipp) to make use of all the features.
+  * Feature: Add support for saving screen and error reports to specified files
+  * Feature: Add support for UAS actions (waiting for an incoming call)
+  * Feature: Permit supplying a SIP advertise address that is different from the bind IP for NAT traversal purposes
+  * Feature: Add support for CallLengthRepartition and ResponseTimeRepartition tables
+  * Bugfix: Much improved support for sending a hangup from SIPp, rather than waiting for the far end to do it
+  * Bugfix: If scenario compilation fails on the CLI, explain why
+  * Change: Rework the `register` command so it works without any other expectations
+  * Change: `wait_for_answer` now includes `ack_answer`
+  * Documentation: Create `examples/` directory with example scenarios
+
 # [0.4.1](https://github.com/bklang/sippy_cup/compare/v0.4.0...v0.4.1)
   * Bugfix: Fix some Ruby 2 string encoding problems
   * Bugfix: Fix backward alias of `respond_ok` with `respond_200`

data/Guardfile

@@ -1,4 +1,4 @@
-guard 'rspec', :cli => '--format documentation', :all_on_start => true, :all_after_pass => true do
+guard 'rspec', cmd: 'bundle exec rspec --format documentation', :all_on_start => true, :all_after_pass => true do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
   watch('spec/spec_helper.rb')  { "spec/" }

data/README.markdown

@@ -105,6 +105,8 @@ Password:
 I, [2013-09-30T14:48:16.728712 #9883]  INFO -- : Test completed successfully.
 ```
 
+More examples are [available in the source repository](https://github.com/mojolingo/sippy_cup/tree/develop/examples).
+
 ### Example embedding SIPp in another Ruby process
 
 ```Ruby
@@ -135,17 +137,23 @@ The above code can be executed as a standalone Ruby script and the resulting sce
 
 ### Available Scenario Steps
 
-Each command below can take [SIPp attributes](http://sipp.sourceforge.net/doc/reference.html) as optional arguments. For a full list of available steps, see the [API documentation](http://rubydoc.info/gems/sippy_cup/SippyCup/Scenario).
+Each command below can take [SIPp attributes](http://sipp.sourceforge.net/doc/reference.html) as optional arguments. For a full list of available steps with arguments explained, see the [API documentation](http://rubydoc.info/gems/sippy_cup/SippyCup/Scenario).
 
 * `sleep <seconds>` Wait a specified number of seconds
 * `invite` Send a SIP INVITE to the specified target
+* `receive_invite` Wait for an INVITE to be received
 * `register <username> [password]` Register the specified user to the target with an optional password
+* `send_trying` Send a `100 Trying` provisional response
 * `receive_trying` Expect to receive a `100 Trying` response from the target
+* `send_ringing` Send a `180 Ringing` provisional response
 * `receive_ringing` Expect to receive a `180 Ringing` response from the target
 * `receive_progress` Expect to receive a `183 Progress` response from the target
+* `send_answer` Send a `200 Ok` response to an INVITE (answer the call)
 * `receive_answer` Expect to receive a `200 OK` (answering the call) response from the target
+* `answer` Convenient shortcut for `send_answer; receive_ack`
 * `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`
+* `receive_ack` Expect to receive an `ACK`
 * `send_digits <string>` Send a DTMF string. May send one or many digits, including `0-9`, `*`, `#`, and `A-D`
 * `receive_ok` Expect to receive a `200 OK`
 * `receive_message [regex]` Expect to receive a SIP MESSAGE, optionally matching a regex
@@ -153,6 +161,9 @@ Each command below can take [SIPp attributes](http://sipp.sourceforge.net/doc/re
 * `receive_bye` Expect to receive a `BYE` from the target
 * `ack_bye` Send a `200 OK` response to a `BYE`
 * `wait_for_hangup` Convenient shortcut for `receive_bye; ack_bye`
+* `hangup` Convenient shortcut for `send_bye; receive_ok`
+* `call_length_repartition` Creates a histogram table of individual call lengths in milliseconds between min length and max length, at the specified interval
+* `response_time_repartition` Creates a histogram table of individual SIP request response times in milliseconds between min length and max length, at the specified interval
 
 ### Alternate Output File Path
 
@@ -179,6 +190,7 @@ This will create the files `somewhere.xml` and `somewhere.pcap` in the `/path/to
 ### Customizing the Test Run
 
 Each parameter has an impact on the test, and may either be changed once the XML 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>stats_file</dt>
   <dd>Path to a file where call statistics will be stored in a CSV format, defaults to not storing stats</dd>
@@ -198,6 +210,12 @@ Each parameter has an impact on the test, and may either be changed once the XML
   <dt>full_sipp_output</dt>
   <dd>By default, SippyCup will show SIPp's command line output while running a scenario. Set this parameter to `false` to hide full command line output</dd>
 
+  <dt>summary_report_file</dt>
+  <dd>Write a summary of the SIPp run to the specified file. This summary is the output from the SIPp `-trace_screen` command. Requires a development build of SIPp; see https://github.com/SIPp/sipp/pull/106.</dd>
+
+  <dt>errors_report_file</dt>
+  <dd>Record SIPp's errors to the specified file. This report is the output from the SIPp `-trace_err` command.</dd>
+
   <dt>options</dt>
   <dd>A string of SIPp command line options included with the SIPp run.</dd>
 
@@ -205,10 +223,25 @@ Each parameter has an impact on the test, and may either be changed once the XML
   <dd>By default, SIPp assigns RTP ports dynamically. However, if there is a need for a static RTP port (say, for data collection purposes), it can be done by supplying a port number here.</dd>
 
   <dt>dtmf_mode</dt>
-  <dd>Specify the mechanism by which DTMF is signaled. Valid options are `rfc2833` for within the RTP media, or `info` for SIP INFO.</dd>
+  <dd>Specify the mechanism by which DTMF is signaled. Valid options are `rfc2833` for within the RTP media, or `info` for SIP INFO. Default: rfc2833</dd>
 
   <dt>scenario_variables</dt>
   <dd>If you're using sippy_cup to run a SIPp XML file, there may be CSV fields in the scenario ([field0], [field1], etc.). Specify a path to a CSV file containing the required information using this option. (File is semicolon delimeted, information can be found [here](http://sipp.sourceforge.net/doc/reference.html#inffile).)</dd>
+
+  <dt>concurrent_max</dt>
+  <dd>The maximum number of calls permitted to be active at any given time. When this limit is reached, SIPp will slow down or stop sending new calls until there it falls below the limit. Default: 5</dd>
+
+  <dt>calls_per_second</dt>
+  <dd>The rate at which new calls should be created. Note that SIPp will automatically adjust this downward to stay at or beneath the maximum number of concurrent calls (`concurrent_max`). Default: 10</dt>
+
+  <dt>calls_per_second_incr</dt>
+  <dd>When used with `calls_per_second_max`, tells SIPp the amount by which calls-per-second should be incremented. CPS rate is adjusted each `stats_interval`. Default: 1.</dd>
+
+  <dt>calls_per_second_max</dt>
+  <dd>The maximum rate of calls-per-second. If unset, the CPS rate will remain at the level set by `calls_per_second`.</dd>
+
+  <dt>advertise_address</dt>
+  <dd>The IP address to advertise in SIP and SDP if different from the bind IP (defaults to the bind IP).</dd>
 </dl>
 
 ### Additional SIPp Scenario Attributes

data/bin/sippy_cup

@@ -60,7 +60,15 @@ unless compile || run
 end
 
 scenario = SippyCup::Scenario.from_manifest File.read(manifest_path), input_filename: manifest_path
-scenario.compile! if compile
+if scenario.valid?
+  scenario.compile! if compile
+else
+  $stderr.puts "Errors encountered while building the scenario!"
+  puts "Step\tError Message"
+  scenario.errors.each do |error|
+    puts "#{error[:step]}\t#{error[:message]}"
+  end
+end
 
 if run
   runner = SippyCup::Runner.new scenario

data/examples/navigate_ivr.yml

@@ -0,0 +1,14 @@
+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_hangup

data/examples/simple_call.yml

@@ -0,0 +1,11 @@
+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 5
+  - hangup

data/examples/wait_for_call.yml

@@ -0,0 +1,15 @@
+---
+source: 10.3.18.108
+destination: 10.3.18.134
+max_concurrent: 1
+calls_per_second: 1
+number_of_calls: 1
+steps:
+  - wait_for_call
+  - send_trying
+  - sleep 1
+  - send_ringing
+  - sleep 3
+  - answer
+  - sleep 5
+  - hangup

data/lib/sippy_cup/runner.rb

@@ -1,5 +1,6 @@
 # encoding: utf-8
 require 'logger'
+require 'fileutils'
 
 #
 # Service object to oversee the execution of a Scenario
@@ -67,7 +68,8 @@ module SippyCup
     #
     def wait
       exit_status = Process.wait2 @sipp_pid.to_i
-      @rd.close if @rd
+      @err_rd.close if @err_rd
+      @stdout_rd.close if @stdout_rd
       final_result = process_exit_status exit_status, @stderr_buffer
       if final_result
         @logger.info "Test completed successfully!"
@@ -95,23 +97,39 @@ module SippyCup
 
     def command_options
       options = {
-        i: @scenario_options[:source],
         p: @scenario_options[:source_port] || '8836',
         sf: @input_files[:scenario].path,
-        l: @scenario_options[:max_concurrent] || 5,
+        l: @scenario_options[:concurrent_max] || @scenario_options[:max_concurrent] || 5,
         m: @scenario_options[:number_of_calls] || 10,
         r: @scenario_options[:calls_per_second] || 10,
         s: @scenario_options[:to_user] || '1'
       }
 
+      options[:i] = @scenario_options[:source] if @scenario_options[:source]
       options[:mp] = @scenario_options[:media_port] if @scenario_options[:media_port]
 
+      if @scenario_options[:calls_per_second_max]
+        options[:no_rate_quit] = nil
+        options[:rate_max] = @scenario_options[:calls_per_second_max]
+        options[:rate_increase] = @scenario_options[:calls_per_second_incr] || 1
+      end
+
       if @scenario_options[:stats_file]
         options[:trace_stat] = nil
         options[:stf] = @scenario_options[:stats_file]
         options[:fd] = @scenario_options[:stats_interval] || 1
       end
 
+      if @scenario_options[:summary_report_file]
+        options[:trace_screen] = nil
+        options[:screen_file] = @scenario_options[:summary_report_file]
+      end
+
+      if @scenario_options[:errors_report_file]
+        options[:trace_err] = nil
+        options[:error_file] = @scenario_options[:errors_report_file]
+      end
+
       if @scenario_options[:transport_mode]
         options[:t] = @scenario_options[:transport_mode]
       end
@@ -126,21 +144,39 @@ module SippyCup
     end
 
     def execute_with_redirected_streams
-      @rd, wr = IO.pipe
-      stdout_target = @options[:full_sipp_output] ? $stdout : '/dev/null'
+      @err_rd, err_wr = IO.pipe
+      stdout_target = if @options[:full_sipp_output]
+        @stdout_rd, stdout_wr = IO.pipe
+        stdout_wr
+      else
+        '/dev/null'
+      end
 
-      @sipp_pid = spawn command, err: wr, out: stdout_target
+      @sipp_pid = spawn command, err: err_wr, out: stdout_target
 
       @stderr_buffer = String.new
 
       Thread.new do
-        wr.close
-        until @rd.eof?
-          buffer = @rd.readpartial(1024).strip
+        err_wr.close
+        until @err_rd.eof?
+          buffer = @err_rd.readpartial(1024).strip
           @stderr_buffer += buffer
           $stderr << buffer if @options[:full_sipp_output]
         end
       end
+
+      if @stdout_rd
+        @stdout_buffer = String.new
+
+        Thread.new do
+          stdout_wr.close
+          until @stdout_rd.eof?
+            buffer = @stdout_rd.readpartial(1024).strip
+            @stdout_buffer += buffer
+            $stdout << buffer
+          end
+        end
+      end
     end
 
     def process_exit_status(process_status, error_message = nil)
@@ -167,7 +203,7 @@ module SippyCup
       @input_files.values.compact.each do |value|
         value.close
         value.unlink
-      end
+      end if @input_files
     end
   end
 

data/lib/sippy_cup/scenario.rb

@@ -3,6 +3,7 @@ require 'nokogiri'
 require 'psych'
 require 'active_support/core_ext/hash'
 require 'tempfile'
+require 'set'
 
 module SippyCup
   #
@@ -12,6 +13,7 @@ module SippyCup
     USER_AGENT = "SIPp/sippy_cup"
     VALID_DTMF = %w{0 1 2 3 4 5 6 7 8 9 0 * # A B C D}.freeze
     MSEC = 1_000
+    DEFAULT_RETRANS = 500
 
     #
     # Build a scenario based on either a manifest string or a file handle. Manifests are supplied in YAML format.
@@ -79,6 +81,7 @@ module SippyCup
     # @option options [String] :source The source IP/hostname with which to invoke SIPp.
     # @option options [String, Numeric] :source_port The source port to bind SIPp to (defaults to 8836).
     # @option options [String] :destination The target system at which to direct traffic.
+    # @option options [String] :advertise_address The IP address to advertise in SIP and SDP if different from the bind IP (defaults to the bind IP).
     # @option options [String] :from_user The SIP user from which traffic should appear.
     # @option options [String] :to_user The SIP user to send requests to.
     # @option options [Integer] :media_port The RTCP (media) port to bind to locally.
@@ -102,10 +105,13 @@ module SippyCup
       @scenario_options = args.merge name: name
       @filename = args[:filename] || name.downcase.gsub(/\W+/, '_')
       @filename = File.expand_path @filename, Dir.pwd
-      @media = Media.new '127.0.0.255', 55555, '127.255.255.255', 5060
+      @media = nil
       @message_variables = 0
+      # Reference variables don't generate warnings/errors if unused in the scenario
+      @reference_variables = Set.new
       @media_nodes = []
       @errors = []
+      @adv_ip = args[:advertise_address] || "[local_ip]"
 
       instance_eval &block if block_given?
     end
@@ -124,11 +130,10 @@ module SippyCup
       raise ArgumentError, "Must provide scenario steps" unless steps
       steps.each_with_index do |step, index|
         begin
-          instruction, arg = step.split ' ', 2
-          if arg && !arg.empty?
-            # Strip leading/trailing quotes if present
-            arg.gsub!(/^'|^"|'$|"$/, '')
-            self.__send__ instruction, arg
+          instruction, args = step.split ' ', 2
+          args = split_quoted_string args
+          if args && !args.empty?
+            self.__send__ instruction, *args
           else
             self.__send__ instruction
           end
@@ -149,22 +154,24 @@ module SippyCup
       opts[:retrans] ||= 500
       # FIXME: The DTMF mapping (101) is hard-coded. It would be better if we could
       # get this from the DTMF payload generator
+      from_addr = "#{@from_user}@#{@adv_ip}:[local_port]"
+      to_addr   = "[service]@[remote_ip]:[remote_port]"
       msg = <<-MSG
 
-INVITE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
-Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
-From: "#{@from_user}" <sip:#{@from_user}@[local_ip]>;tag=[call_number]
-To: <sip:[service]@[remote_ip]:[remote_port]>
+INVITE sip:#{to_addr} SIP/2.0
+Via: SIP/2.0/[transport] #{@adv_ip}:[local_port];branch=[branch]
+From: "#{@from_user}" <sip:#{from_addr}>;tag=[call_number]
+To: <sip:#{to_addr}>
 Call-ID: [call_id]
 CSeq: [cseq] INVITE
-Contact: <sip:#{@from_user}@[local_ip]:[local_port];transport=[transport]>
+Contact: <sip:#{from_addr};transport=[transport]>
 Max-Forwards: 100
 User-Agent: #{USER_AGENT}
 Content-Type: application/sdp
 Content-Length: [len]
 #{opts.has_key?(:headers) ? opts.delete(:headers).sub(/\n*\Z/, "\n") : ''}
 v=0
-o=user1 53655765 2353687637 IN IP[local_ip_type] [local_ip]
+o=user1 53655765 2353687637 IN IP[local_ip_type] #{@adv_ip}
 s=-
 c=IN IP[media_ip_type] [media_ip]
 t=0 0
@@ -173,7 +180,24 @@ a=rtpmap:0 PCMU/8000
 a=rtpmap:101 telephone-event/8000
 a=fmtp:101 0-15
       MSG
-      send msg, opts
+      send msg, opts do |send|
+        send << doc.create_element('action') do |action|
+          action << doc.create_element('assignstr') do |assignstr|
+            assignstr['assign_to'] = "remote_addr"
+            assignstr['value']     = to_addr
+          end
+          action << doc.create_element('assignstr') do |assignstr|
+            assignstr['assign_to'] = "local_addr"
+            assignstr['value']     = from_addr
+          end
+          action << doc.create_element('assignstr') do |assignstr|
+            assignstr['assign_to'] = "call_addr"
+            assignstr['value']     = to_addr
+          end
+        end
+      end
+      # These variables will only be used if we initiate a hangup
+      @reference_variables += %w(remote_addr local_addr call_addr)
     end
 
     #
@@ -190,16 +214,142 @@ a=fmtp:101 0-15
     #   s.register 'frank'
     #
     def register(user, password = nil, opts = {})
-      opts[:retrans] ||= 500
+      send_opts = opts.dup
+      send_opts[:retrans] ||= DEFAULT_RETRANS
       user, domain = parse_user user
-      msg = if password
-        register_auth domain, user, password
+      if password
+        send register_message(domain, user), send_opts
+        recv opts.merge(response: 401, auth: true, optional: false)
+        send register_auth(domain, user, password), send_opts
+        receive_ok opts.merge(optional: false)
       else
-        register_message domain, user
+        send register_message(domain, user), send_opts
+      end
+    end
+
+    #
+    # Expect to receive a SIP INVITE
+    #
+    # @param [Hash] opts A set of options containing SIPp <recv> element attributes
+    #
+    def receive_invite(opts = {})
+      recv(opts.merge(request: 'INVITE', rrs: true)) do |recv|
+        action = doc.create_element('action') do |action|
+          action << doc.create_element('ereg') do |ereg|
+            ereg['regexp'] = '<sip:(.*)>.*;tag=([^;]*)'
+            ereg['search_in'] = 'hdr'
+            ereg['header'] = 'From:'
+            ereg['assign_to'] = 'dummy,remote_addr,remote_tag'
+          end
+          action << doc.create_element('ereg') do |ereg|
+            ereg['regexp'] = '<sip:(.*)>'
+            ereg['search_in'] = 'hdr'
+            ereg['header'] = 'To:'
+            ereg['assign_to'] = 'dummy,local_addr'
+          end
+          action << doc.create_element('assignstr') do |assignstr|
+            assignstr['assign_to'] = "call_addr"
+            assignstr['value']     = "[$local_addr]"
+          end
+        end
+        recv << action
       end
+      # These variables (except dummy) will only be used if we initiate a hangup
+      @reference_variables += %w(dummy remote_addr remote_tag local_addr call_addr)
+    end
+    alias :wait_for_call :receive_invite
+
+    #
+    # Send a "100 Trying" response
+    #
+    # @param [Hash] opts A set of options containing SIPp <recv> element attributes
+    #
+    def send_trying(opts = {})
+      msg = <<-MSG
+
+SIP/2.0 100 Trying
+[last_Via:]
+From: <sip:[$remote_addr]>;tag=[$remote_tag]
+To: <sip:[$local_addr]>;tag=[call_number]
+[last_Call-ID:]
+[last_CSeq:]
+Server: #{USER_AGENT}
+Contact: <sip:[$local_addr];transport=[transport]>
+Content-Length: 0
+      MSG
+      send msg, opts
+    end
+    alias :send_100 :send_trying
+
+    #
+    # Send a "180 Ringing" response
+    #
+    # @param [Hash] opts A set of options containing SIPp <recv> element attributes
+    #
+    def send_ringing(opts = {})
+      msg = <<-MSG
+
+SIP/2.0 180 Ringing
+[last_Via:]
+From: <sip:[$remote_addr]>;tag=[$remote_tag]
+To: <sip:[$local_addr]>;tag=[call_number]
+[last_Call-ID:]
+[last_CSeq:]
+Server: #{USER_AGENT}
+Contact: <sip:[$local_addr];transport=[transport]>
+Content-Length: 0
+      MSG
+      send msg, opts
+    end
+    alias :send_180 :send_ringing
+
+    #
+    # Answer an incoming call
+    #
+    # @param [Hash] opts A set of options containing SIPp <send> element attributes
+    #
+    def send_answer(opts = {})
+      opts[:retrans] ||= DEFAULT_RETRANS
+      msg = <<-MSG
+
+SIP/2.0 200 Ok
+[last_Via:]
+From: <sip:[$remote_addr]>;tag=[$remote_tag]
+To: <sip:[$local_addr]>;tag=[call_number]
+[last_Call-ID:]
+[last_CSeq:]
+Server: #{USER_AGENT}
+Contact: <sip:[$local_addr];transport=[transport]>
+Content-Type: application/sdp
+[routes]
+Content-Length: [len]
+
+v=0
+o=user1 53655765 2353687637 IN IP[local_ip_type] #{@adv_ip} 
+s=-
+c=IN IP[media_ip_type] [media_ip]
+t=0 0
+m=audio [media_port] RTP/AVP 0
+a=rtpmap:0 PCMU/8000
+      MSG
+      start_media
       send msg, opts
     end
 
+    #
+    # Helper method to answer an INVITE and expect the ACK
+    #
+    # @param [Hash] opts A set of options containing SIPp element attributes - will be passed to both the <send> and <recv> elements
+    #
+    def answer(opts = {})
+      send_answer opts
+      receive_ack opts
+    end
+
+    def receive_ack(opts = {})
+      recv opts.merge request: 'ACK'
+    end
+
     #
     # Sets an expectation for a SIP 100 message from the remote party
     #
@@ -242,11 +392,22 @@ a=fmtp:101 0-15
     #
     def receive_answer(opts = {})
       options = {
-        rrs: true, # Record Record Set: Make the Route headers available via [route] later
+        rrs: true, # Record Record Set: Make the Route headers available via [routes] later
         rtd: true # Response Time Duration: Record the response time
       }
 
-      receive_200 options.merge(opts)
+      receive_200(options.merge(opts)) do |recv|
+        recv << doc.create_element('action') do |action|
+          action << doc.create_element('ereg') do |ereg|
+            ereg['regexp'] = '<sip:(.*)>.*;tag=([^;]*)'
+            ereg['search_in'] = 'hdr'
+            ereg['header'] = 'To:'
+            ereg['assign_to'] = 'dummy,remote_addr,remote_tag'
+          end
+        end
+      end
+      # These variables will only be used if we initiate a hangup
+      @reference_variables += %w(dummy remote_addr remote_tag)
     end
 
     #
@@ -255,13 +416,16 @@ a=fmtp:101 0-15
     # @param [Hash] opts A set of options to modify the expectation
     # @option opts [true, false] :optional Whether or not receipt of the message is optional. Defaults to false.
     #
-    def receive_ok(opts = {})
-      recv({ response: 200 }.merge(opts))
+    def receive_ok(opts = {}, &block)
+      recv({ response: 200 }.merge(opts), &block)
     end
     alias :receive_200 :receive_ok
 
     #
-    # Shortcut that sets expectations for optional SIP 100, 180 and 183, followed by a required 200.
+    # Convenience method to wait for an answer from the called party
+    #
+    # This sets expectations for optional SIP 100, 180 and 183,
+    # followed by a required 200 and sending the acknowledgement.
     #
     # @param [Hash] opts A set of options to modify the expectations
     #
@@ -270,10 +434,11 @@ a=fmtp:101 0-15
       receive_ringing opts
       receive_progress opts
       receive_answer opts
+      ack_answer opts
     end
 
     #
-    # Acknowledge a received answer message (SIP 200) and start media playback
+    # Acknowledge a received answer message and start media playback
     #
     # @param [Hash] opts A set of options to modify the message parameters
     #
@@ -281,12 +446,12 @@ a=fmtp:101 0-15
       msg = <<-BODY
 
 ACK [next_url] SIP/2.0
-Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
-From: "#{@from_user}" <sip:#{@from_user}@[local_ip]>;tag=[call_number]
+Via: SIP/2.0/[transport] #{@adv_ip}:[local_port];branch=[branch]
+From: "#{@from_user}" <sip:#{@from_user}@#{@adv_ip}:[local_port]>;tag=[call_number]
 To: <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
 Call-ID: [call_id]
 CSeq: [cseq] ACK
-Contact: <sip:#{@from_user}@[local_ip]:[local_port];transport=[transport]>
+Contact: <sip:[$local_addr];transport=[transport]>
 Max-Forwards: 100
 User-Agent: #{USER_AGENT}
 Content-Length: 0
@@ -304,7 +469,7 @@ Content-Length: 0
     def sleep(seconds)
       milliseconds = (seconds.to_f * MSEC).to_i
       pause milliseconds
-      @media << "silence:#{milliseconds}"
+      @media << "silence:#{milliseconds}" if @media
     end
 
     #
@@ -319,6 +484,7 @@ Content-Length: 0
     #   send_digits '1234'
     #
     def send_digits(digits)
+      raise "Media not started" unless @media
       delay = (0.250 * MSEC).to_i # FIXME: Need to pass this down to the media layer
       digits.split('').each do |digit|
         raise ArgumentError, "Invalid DTMF digit requested: #{digit}" unless VALID_DTMF.include? digit
@@ -331,12 +497,12 @@ Content-Length: 0
           info = <<-INFO
 
 INFO [next_url] SIP/2.0
-Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
-From: "#{@from_user}" <sip:#{@from_user}@[local_ip]>;tag=[call_number]
+Via: SIP/2.0/[transport] #{@adv_ip}:[local_port];branch=[branch]
+From: "#{@from_user}" <sip:#{@from_user}@#{@adv_ip}:[local_port]>;tag=[call_number]
 To: <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
 Call-ID: [call_id]
 CSeq: [cseq] INFO
-Contact: <sip:#{@from_user}@[local_ip]:[local_port];transport=[transport]>
+Contact: <sip:[$local_addr];transport=[transport]>
 Max-Forwards: 100
 User-Agent: #{USER_AGENT}
 [routes]
@@ -370,18 +536,17 @@ Duration=#{delay}
       if regexp
         action = Nokogiri::XML::Node.new 'action', doc
         ereg = Nokogiri::XML::Node.new 'ereg', doc
-        ref = Nokogiri::XML::Node.new 'Reference', doc
 
         ereg['regexp'] = regexp
         ereg['search_in'] = 'body'
         ereg['check_it'] = true
 
         var = "message_#{@message_variables += 1}"
-        ereg['assign_to'] = ref['variables'] = var
+        ereg['assign_to'] = var
+        @reference_variables << var
 
         action << ereg
         recv << action
-        scenario_node << ref
       end
 
       okay
@@ -395,13 +560,13 @@ Duration=#{delay}
     def send_bye(opts = {})
       msg = <<-MSG
 
-BYE [next_url] SIP/2.0
-Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
-From: "#{@from_user}" <sip:#{@from_user}@[local_ip]>;tag=[call_number]
-To: <sip:[service]@[remote_ip]:[remote_port]>[peer_tag_param]
+BYE sip:[$call_addr] SIP/2.0
+Via: SIP/2.0/[transport] #{@adv_ip}:[local_port];branch=[branch]
+From: <sip:[$local_addr]>;tag=[call_number]
+To: <sip:[$remote_addr]>;tag=[$remote_tag]
+Contact: <sip:[$local_addr];transport=[transport]>
 Call-ID: [call_id]
 CSeq: [cseq] BYE
-Contact: <sip:#{@from_user}@[local_ip]:[local_port];transport=[transport]>
 Max-Forwards: 100
 User-Agent: #{USER_AGENT}
 Content-Length: 0
@@ -433,7 +598,7 @@ SIP/2.0 200 OK
 [last_To:]
 [last_Call-ID:]
 [last_CSeq:]
-Contact: <sip:#{@from_user}@[local_ip]:[local_port];transport=[transport]>
+Contact: <sip:[$local_addr];transport=[transport]>
 Max-Forwards: 100
 User-Agent: #{USER_AGENT}
 Content-Length: 0
@@ -453,6 +618,34 @@ Content-Length: 0
       ack_bye(opts)
     end
 
+    #
+    # Shortcut to send a BYE and wait for the acknowledgement
+    #
+    # @param [Hash] opts A set of options containing SIPp <recv> element attributes - will be passed to both the <send> and <recv> elements
+    #
+    def hangup(opts = {})
+      send_bye opts
+      receive_ok opts
+    end
+
+    # Create partition table for Call Length
+    #
+    # @param [Integer] min An value specifying the minimum time in milliseconds for the table
+    # @param [Integer] max An value specifying the maximum time in milliseconds for the table
+    # @param [Integer] interval An value specifying the interval in milliseconds for the table
+    def call_length_repartition(min, max, interval)
+      partition_table 'CallLengthRepartition', min.to_i, max.to_i, interval.to_i
+    end
+
+    # Create partition table for Response Time
+    #
+    # @param [Integer] min An value specifying the minimum time in milliseconds for the table
+    # @param [Integer] max An value specifying the maximum time in milliseconds for the table
+    # @param [Integer] interval An value specifying the interval in milliseconds for the table
+    def response_time_repartition(min, max, interval)
+      partition_table 'ResponseTimeRepartition', min.to_i, max.to_i, interval.to_i
+    end
+
     #
     # Dump the scenario to a SIPp XML string
     #
@@ -474,6 +667,13 @@ Content-Length: 0
         end
       end
 
+      unless @reference_variables.empty?
+        scenario_node = docdup.xpath('scenario').first
+        scenario_node << docdup.create_element('Reference') do |ref|
+          ref[:variables] = @reference_variables.to_a.join ','
+        end
+      end
+
       docdup.to_xml
     end
 
@@ -494,7 +694,7 @@ Content-Length: 0
     #   scenario.compile! # Leaves files at test_scenario.xml and test_scenario.pcap
     #
     def compile!
-      unless @media.empty?
+      unless @media.nil?
         print "Compiling media to #{@filename}.pcap..."
         compile_media.to_file filename: "#{@filename}.pcap"
         puts "done."
@@ -520,8 +720,9 @@ Content-Length: 0
     # @see http://www.ruby-doc.org/stdlib-1.9.3/libdoc/tempfile/rdoc/Tempfile.html
     #
     def to_tmpfiles
-      unless @media.empty?
+      unless @media.nil? || @media.empty?
         media_file = Tempfile.new 'media'
+        media_file.binmode
         media_file.write compile_media.to_s
         media_file.rewind
       end
@@ -544,6 +745,12 @@ Content-Length: 0
       [user, domain]
     end
 
+    # Split a string into space-delimited components, optionally allowing quoted groups
+    # Example: cars "cats and dogs" fish 'hammers' => ["cars", "cats and dogs", "fish", "hammers"]
+    def split_quoted_string(args)
+      args.to_s.scan(/'.+?'|".+?"|[^ ]+/).map { |s| s.gsub /^['"]|['"]$/, '' }
+    end
+
     def doc
       @doc ||= begin
         Nokogiri::XML::Builder.new do |xml|
@@ -560,9 +767,6 @@ Content-Length: 0
     end
 
     def parse_args(args)
-      raise ArgumentError, "Must include source IP:PORT" unless args.has_key? :source
-      raise ArgumentError, "Must include destination IP:PORT" unless args.has_key? :destination
-
       if args[:dtmf_mode]
         @dtmf_mode = args[:dtmf_mode].to_sym
         raise ArgumentError, "dtmf_mode must be rfc2833 or info" unless [:rfc2833, :info].include?(@dtmf_mode)
@@ -570,25 +774,26 @@ Content-Length: 0
         @dtmf_mode = :rfc2833
       end
 
-      @from_addr, @from_port = args[:source].split ':'
-      @to_addr, @to_port = args[:destination].split ':'
+      @from_addr, @from_port = args[:source].split ':' if args[:source]
+      @to_addr, @to_port = args[:destination].split ':' if args[:destination]
       @from_user = args[:from_user] || "sipp"
     end
 
     def compile_media
+      raise "Media not started" unless @media
       @media.compile!
     end
 
-    def register_message(domain, user, opts = {})
+    def register_message(domain, user)
       <<-BODY
 
 REGISTER sip:#{domain} SIP/2.0
-Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
+Via: SIP/2.0/[transport] #{@adv_ip}:[local_port];branch=[branch]
 From: <sip:#{user}@#{domain}>;tag=[call_number]
 To: <sip:#{user}@#{domain}>
 Call-ID: [call_id]
 CSeq: [cseq] REGISTER
-Contact: <sip:#{@from_user}@[local_ip]:[local_port];transport=[transport]>
+Contact: <sip:#{@from_user}@#{@adv_ip}:[local_port];transport=[transport]>
 Max-Forwards: 10
 Expires: 120
 User-Agent: #{USER_AGENT}
@@ -596,17 +801,16 @@ Content-Length: 0
       BODY
     end
 
-    def register_auth(domain, user, password, opts = {})
-      recv response: '401', auth: true, optional: false
+    def register_auth(domain, user, password)
       <<-AUTH
 
 REGISTER sip:#{domain} SIP/2.0
-Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
+Via: SIP/2.0/[transport] #{@adv_ip}:[local_port];branch=[branch]
 From: <sip:#{user}@#{domain}>;tag=[call_number]
 To: <sip:#{user}@#{domain}>
 Call-ID: [call_id]
 CSeq: [cseq] REGISTER
-Contact: <sip:#{@from_user}@[local_ip]:[local_port];transport=[transport]>
+Contact: <sip:#{@from_user}@#{@adv_ip}:[local_port];transport=[transport]>
 Max-Forwards: 20
 Expires: 3600
 [authentication username=#{user} password=#{password}]
@@ -616,6 +820,7 @@ Content-Length: 0
     end
 
     def start_media
+      @media = Media.new '127.0.0.255', 55555, '127.255.255.255', 44444
       nop = doc.create_element('nop') { |nop|
         nop << doc.create_element('action') { |action|
           action << doc.create_element('exec')
@@ -640,15 +845,17 @@ Content-Length: 0
       send << "\n"
       send << Nokogiri::XML::CDATA.new(doc, msg)
       send << "\n" #Newlines are required before and after CDATA so SIPp will parse properly
+      yield send if block_given?
       scenario_node << send
     end
 
-    def recv(opts = {})
+    def recv(opts = {}, &block)
       raise ArgumentError, "Receive must include either a response or a request" unless opts.keys.include?(:response) || opts.keys.include?(:request)
       recv = Nokogiri::XML::Node.new 'recv', doc
       opts.each do |k,v|
         recv[k.to_s] = v
       end
+      yield recv if block_given?
       scenario_node << recv
     end
 
@@ -660,5 +867,12 @@ Content-Length: 0
     def handle_response(code, opts)
       optional_recv opts.merge(response: code)
     end
+
+    def partition_table(name, min, max, interval)
+      range = Range.new(min, max).step interval
+      partition_table = Nokogiri::XML::Node.new name, doc
+      partition_table[:value] = range.inject{ |n,m| "#{n},#{m}"}
+      scenario_node << partition_table
+    end
   end
 end