switest 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d902a23fc1a0ad34adf1cf55feacc64a3f4b25bfed50e14b32249cb07cd68b8f
-  data.tar.gz: 30dba87635d06da98bfb19468efe35442a415de21b5ee6acf1e741b670f6b17d
+  metadata.gz: 694639e976172b9f71b539b6bfc9d1decb8c2ae1735647c394a732213a419db7
+  data.tar.gz: bf525eb26fb1fbe8ed28cf7dbf760e08b8a3c9d4831b01e01355e69dceda42df
 SHA512:
-  metadata.gz: aa1102910bc74897527ef14f4a4370f6bf019d09064d49bc5c5a47356f36ccee709a5924002f9dae9c2071d1abf82c5b90dc31dfb8e78eca562e94c39341dc5c
-  data.tar.gz: a013d6e72d21fafd3461b0d5c5ad1d8be27d48afc97f9526032c91f8b2df2d3ec78904a8e8229279ed0d655d76343893783d562a1c227a5695fe23da121554ed
+  metadata.gz: edb3db5bd51e39e16707578d5a07c298edb10bac0188c5eebcbb34829677507203499837b3a58a7b1924003c3c925c9b61368ae45e5d373b21e6ea14f11c4a41
+  data.tar.gz: a2115e1b1429a1a7c7558dcf75fd4d54b53c64f9992723b5af742343d44c5fe2ad99ba5844f4712417d6f32711fa0d42a84d72bad67183bd0c0f94c3b7336c40

data/README.md

@@ -1,11 +1,17 @@
+<p align="center">
+  <img src=".github/banner.svg" alt="switest" width="800"/>
+</p>
+
 # Switest
 
-Functional testing for voice applications via FreeSWITCH ESL.
+Functional testing for voice applications via FreeSWITCH.
 
-Switest lets you write tests for your voice applications using direct
-ESL (Event Socket Library) communication with FreeSWITCH. Tests run as
-plain Minitest cases — no Adhearsion, no Rayo, just a TCP socket to
-FreeSWITCH.
+Switest lets you write tests for your voice applications using
+[librevox](https://github.com/relatel/librevox) to communicate with
+FreeSWITCH over Event Socket. Tests run as plain Minitest cases — no
+Adhearsion, no Rayo, just a TCP socket to FreeSWITCH. Each test runs
+inside an [async](https://github.com/socketry/async) reactor for
+fiber-based concurrency.
 
 ## Table of Contents
 
@@ -74,8 +80,9 @@ bundle exec rake test
 ### Scenario
 
 `Switest::Scenario` is a Minitest::Test subclass that handles FreeSWITCH
-connection lifecycle for you. Each test method gets a fresh ESL client that
-connects on setup and disconnects on teardown.
+connection lifecycle for you. Each test method gets a fresh connection that
+is established on setup and torn down after the test. The test body runs
+inside an `Async` reactor, so all waits are fiber-based and non-blocking.
 
 ```ruby
 class MyTest < Switest::Scenario
@@ -137,6 +144,7 @@ Agent.listen_for_call(guards)  # e.g. to: /pattern/, from: /pattern/
 agent.answer(wait: 5)             # Answer an inbound call
 agent.hangup(wait: 5)             # Hang up
 agent.reject(reason = :decline)   # Reject inbound call (:decline or :busy)
+agent.play_audio(url)             # Play an audio file or tone stream
 agent.send_dtmf(digits)           # Send DTMF tones
 agent.receive_dtmf(count:, timeout:)  # Receive DTMF digits
 ```
@@ -145,8 +153,7 @@ agent.receive_dtmf(count:, timeout:)  # Receive DTMF digits
 
 ```ruby
 agent.wait_for_call(timeout: 5)    # Wait for inbound call to arrive
-agent.wait_for_answer(timeout: 5)  # Wait for call to be answered
-agent.wait_for_bridge(timeout: 5)  # Wait for call to be bridged
+agent.wait_for_answer(timeout: 5)  # Wait for call to be fully answered (ACTIVE)
 agent.wait_for_end(timeout: 5)     # Wait for call to end
 ```
 
@@ -158,34 +165,30 @@ agent.alive?      # Call exists and not ended?
 agent.active?     # Answered and not ended?
 agent.answered?   # Has been answered?
 agent.ended?      # Has ended?
+agent.inbound?    # Is an inbound call?
+agent.outbound?   # Is an outbound call?
+agent.id          # Call UUID
+agent.headers     # Call headers hash
 agent.start_time  # When call started
 agent.answer_time # When answered
+agent.end_time    # When ended
 agent.end_reason  # e.g. "NORMAL_CLEARING"
 ```
 
 ### Scenario Assertions
 
-`Switest::Scenario` provides these assertions:
+Available via `Switest::Assertions` (included in `Switest::Scenario`):
 
 ```ruby
 assert_call(agent, timeout: 5)                       # Agent receives a call
 assert_no_call(agent, timeout: 2)                    # Agent does NOT receive a call
-assert_answered(agent, timeout: 5)                   # Call has been answered
-assert_bridged(agent, timeout: 5)                    # Call has been bridged (see note below)
+assert_answered(agent, timeout: 5)                   # Call is fully established (ACTIVE)
 assert_hungup(agent, timeout: 5)                     # Call has ended
 assert_not_hungup(agent, timeout: 2)                 # Call is still active
 assert_dtmf(agent, "123", timeout: 5)                # Agent receives expected DTMF digits
 assert_dtmf(agent, "123") { other.send_dtmf("123") } # With block: flushes stale DTMF first
 ```
 
-**Note on `assert_bridged`:** This assertion only works when a CHANNEL_BRIDGE
-event fires on a channel Switest tracks. It works when the FreeSWITCH dialplan
-runs the `bridge` application on an inbound channel picked up via
-`listen_for_call`. It does **not** work for agent-to-agent calls routed through
-SIP gateways — the bridge happens on internal gateway legs whose UUIDs Switest
-doesn't track. For gateway scenarios, use `assert_answered` on both agents
-instead to confirm the call is connected.
-
 The `hangup_all` helper ends all active calls (useful before CDR assertions):
 
 ```ruby
@@ -272,12 +275,13 @@ docker compose up -d freeswitch          # start FreeSWITCH
 docker compose run --rm test             # run integration tests
 ```
 
-The compose file mounts three config files into FreeSWITCH:
+The compose file mounts config files into FreeSWITCH:
 
 | Local file                                    | Container path                                                  |
 |-----------------------------------------------|-----------------------------------------------------------------|
 | `docker/freeswitch/event_socket.conf.xml`     | `/etc/freeswitch/autoload_configs/event_socket.conf.xml`        |
 | `docker/freeswitch/acl.conf.xml`              | `/etc/freeswitch/autoload_configs/acl.conf.xml`                 |
+| `docker/freeswitch/switch.conf.xml`           | `/etc/freeswitch/autoload_configs/switch.conf.xml`              |
 | `docker/freeswitch/dialplan.xml`              | `/etc/freeswitch/dialplan/public/00_switest.xml`                |
 
 ### FreeSWITCH Requirements
@@ -312,13 +316,13 @@ The compose file mounts three config files into FreeSWITCH:
 ```ruby
 Switest.configure do |config|
   config.host = "127.0.0.1"     # FreeSWITCH host
-  config.port = 8021             # ESL port
-  config.password = "ClueCon"   # ESL password
+  config.port = 8021             # Event Socket port
+  config.password = "ClueCon"   # Event Socket password
   config.default_timeout = 5    # Default timeout for waits
 end
 ```
 
-Or via environment variables (used by the integration test helper):
+Or via environment variables (used by the scenario helper):
 
 ```bash
 FREESWITCH_HOST=127.0.0.1
@@ -329,7 +333,7 @@ FREESWITCH_PASSWORD=ClueCon
 ## Dependencies
 
 - Ruby >= 3.0
-- concurrent-ruby ~> 1.2
+- librevox ~> 1.0
 - minitest >= 5.5, < 7.0
 
 ## License

data/lib/switest/agent.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "async"
+require "async/promise"
+
 module Switest
   class Agent
     class << self
@@ -30,8 +33,7 @@ module Switest
 
         # Register a one-time handler for matching inbound calls
         @events.once(:offer, guards) do |data|
-          agent.instance_variable_set(:@call, data[:call])
-          agent.instance_variable_get(:@call_event).set
+          agent.receive_call(data[:call])
         end
 
         agent
@@ -42,7 +44,7 @@ module Switest
 
     def initialize(call)
       @call = call
-      @call_event = Concurrent::Event.new
+      @call_promise = Async::Promise.new
     end
 
     def call?
@@ -81,7 +83,9 @@ module Switest
 
     def wait_for_call(timeout: 5)
       return true if @call
-      @call_event.wait(timeout)
+      Async::Task.current.with_timeout(timeout) { @call_promise.wait }
+      !@call.nil?
+    rescue Async::TimeoutError
       !@call.nil?
     end
 
@@ -90,11 +94,6 @@ module Switest
       @call.wait_for_answer(timeout: timeout)
     end
 
-    def wait_for_bridge(timeout: 5)
-      raise "No call to wait for" unless @call
-      @call.wait_for_bridge(timeout: timeout)
-    end
-
     def wait_for_end(timeout: 5)
       raise "No call to wait for" unless @call
       @call.wait_for_end(timeout: timeout)
@@ -117,6 +116,18 @@ module Switest
       @call&.ended? || false
     end
 
+    def outbound?
+      @call&.outbound? || false
+    end
+
+    def inbound?
+      @call&.inbound? || false
+    end
+
+    def id
+      @call&.id
+    end
+
     def start_time
       @call&.start_time
     end
@@ -125,8 +136,22 @@ module Switest
       @call&.answer_time
     end
 
+    def end_time
+      @call&.end_time
+    end
+
     def end_reason
       @call&.end_reason
     end
+
+    def headers
+      @call&.headers
+    end
+
+    # @api private — called by listen_for_call handler
+    def receive_call(call)
+      @call = call
+      @call_promise.resolve(true)
+    end
   end
 end

data/lib/switest/assertions.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Switest
+  module Assertions
+    def assert_call(agent, timeout: 5)
+      success = agent.wait_for_call(timeout: timeout)
+      assert success, "Expected agent to receive a call within #{timeout} seconds"
+    end
+
+    def assert_no_call(agent, timeout: 2)
+      sleep timeout
+      refute agent.call?, "Expected agent to not have received a call"
+    end
+
+    def assert_answered(agent, timeout: 5)
+      assert agent.call?, "Agent has no call"
+      success = agent.wait_for_answer(timeout: timeout)
+      assert success, "Expected call to be answered within #{timeout} seconds"
+    end
+
+    def assert_hungup(agent, timeout: 5)
+      assert agent.call?, "Agent has no call"
+      success = agent.wait_for_end(timeout: timeout)
+      assert success, "Expected call to be hung up within #{timeout} seconds"
+    end
+
+    def assert_not_hungup(agent, timeout: 2)
+      assert agent.call?, "Agent has no call"
+      sleep timeout
+      refute agent.ended?, "Expected call to still be active"
+    end
+
+    def assert_dtmf(agent, expected_dtmf, timeout: 5, after: 1, &block)
+      assert agent.call?, "Agent has no call"
+
+      if block
+        agent.flush_dtmf
+        Async do
+          sleep after
+          block.call
+        end
+        received = agent.receive_dtmf(count: expected_dtmf.length, timeout: timeout + after)
+      else
+        received = agent.receive_dtmf(count: expected_dtmf.length, timeout: timeout)
+      end
+
+      assert_equal expected_dtmf, received, "Expected DTMF '#{expected_dtmf}' but received '#{received}'"
+    end
+
+  end
+end

data/lib/switest/call.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/promise"
+require "async/queue"
+
+module Switest
+  class Call
+    CALLSTATE_MAP = { "RINGING" => :ringing, "ACTIVE" => :answered }.freeze
+
+    attr_reader :id, :to, :from, :headers, :direction
+    attr_reader :start_time, :answer_time, :end_time, :end_reason
+    attr_reader :state
+
+    def initialize(id:, direction:, to: nil, from: nil, headers: {}, session: nil)
+      @id = id
+      @session = session
+      @direction = direction  # :inbound or :outbound
+      @to = to
+      @from = from
+      @headers = headers.is_a?(Hash) ? headers.dup : {}
+
+      @state = :new
+      @start_time = Time.now
+      @answer_time = nil
+      @end_time = nil
+      @end_reason = nil
+
+      @dtmf_queue = Async::Queue.new
+
+      @answered_promise = Async::Promise.new
+      @ended_promise = Async::Promise.new
+    end
+
+    # State queries
+    def alive?
+      @state != :ended
+    end
+
+    def active?
+      @state == :answered
+    end
+
+    def answered?
+      @state == :answered
+    end
+
+    def ended?
+      @state == :ended
+    end
+
+    def inbound?
+      @direction == :inbound
+    end
+
+    def outbound?
+      @direction == :outbound
+    end
+
+    # Actions
+    def answer(wait: 5)
+      return unless @state == :ringing && inbound?
+      sendmsg("execute", "answer")
+      return unless wait
+      wait_for_answer(timeout: wait)
+    end
+
+    def hangup(cause = "NORMAL_CLEARING", wait: 5)
+      return if ended?
+      sendmsg("hangup", hangup_cause: cause)
+      return unless wait
+      wait_for_end(timeout: wait)
+    end
+
+    def reject(reason = :decline, wait: 5)
+      return unless @state == :ringing && inbound?
+      cause = case reason
+              when :busy then "USER_BUSY"
+              when :decline then "CALL_REJECTED"
+              else "CALL_REJECTED"
+              end
+      hangup(cause, wait: wait)
+    end
+
+    def play_audio(url, wait: true)
+      sendmsg("execute", "playback", url, event_lock: wait)
+    end
+
+    def send_dtmf(digits, wait: true)
+      play_audio("tone_stream://d=200;w=250;#{digits}", wait: wait)
+    end
+
+    def flush_dtmf
+      @dtmf_queue.dequeue until @dtmf_queue.empty?
+    end
+
+    def receive_dtmf(count: 1, timeout: 5)
+      digits = String.new
+      deadline = Time.now + timeout
+
+      count.times do
+        remaining = deadline - Time.now
+        break if remaining <= 0
+
+        Async::Task.current.with_timeout(remaining) do
+          digits << @dtmf_queue.dequeue
+        end
+      rescue Async::TimeoutError
+        break
+      end
+
+      digits
+    end
+
+    # Blocking waits
+    def wait_for_answer(timeout: 5)
+      return true if answered?
+      Async::Task.current.with_timeout(timeout) { @answered_promise.wait }
+      answered?
+    rescue Async::TimeoutError
+      answered?
+    end
+
+    def wait_for_end(timeout: 5)
+      return true if ended?
+      Async::Task.current.with_timeout(timeout) { @ended_promise.wait }
+      ended?
+    rescue Async::TimeoutError
+      ended?
+    end
+
+    # Internal: dispatch a librevox Response event to the appropriate handler.
+    def handle_event(response)
+      return unless response.event?
+
+      case response.event
+      when "CHANNEL_CALLSTATE"
+        handle_callstate(response.content[:channel_call_state])
+      when "CHANNEL_HANGUP_COMPLETE"
+        cause = response.content[:hangup_cause]
+        handle_hangup(cause, response.content)
+      when "DTMF"
+        digit = response.content[:dtmf_digit]
+        handle_dtmf(digit) if digit
+      end
+    end
+
+    # Internal state updates
+    def handle_callstate(call_state)
+      return if @state == :ended
+      new_state = CALLSTATE_MAP[call_state]
+      return if new_state.nil? || @state == new_state
+
+      @state = new_state
+      if new_state == :answered
+        @answer_time = Time.now
+        @answered_promise.resolve(true)
+      end
+    end
+
+    def handle_hangup(cause, event_content = {})
+      return if @state == :ended
+      @state = :ended
+      @end_time = Time.now
+      @end_reason = cause
+
+      # Merge event data into headers
+      if event_content.is_a?(Hash)
+        event_content.each do |k, v|
+          next if k == :body
+          @headers[k] = v.to_s
+        end
+      end
+
+      @answered_promise.resolve(true)
+      @ended_promise.resolve(true)
+    end
+
+    def handle_dtmf(digit)
+      @dtmf_queue.enqueue(digit)
+    end
+
+    private
+
+    def sendmsg(command, app = nil, arg = nil, event_lock: false, hangup_cause: nil)
+      msg = +"sendmsg #{@id}\n"
+      msg << "call-command: #{command}\n"
+      msg << "execute-app-name: #{app}\n" if app
+      msg << "execute-app-arg: #{arg}\n" if arg
+      msg << "event-lock: true\n" if event_lock
+      msg << "hangup-cause: #{hangup_cause}" if hangup_cause
+      @session.command(msg.chomp)
+    end
+
+  end
+end

data/lib/switest/client.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "async/promise"
+require "io/endpoint/host_endpoint"
+require_relative "from_parser"
+
+module Switest
+  class Client
+    attr_reader :calls
+
+    def initialize
+      @calls = {}
+      @offer_handlers = []
+      @session = nil
+      @client_task = nil
+    end
+
+    def start
+      config = Switest.configuration
+
+      # Configure Session class with client state
+      Session.call_registry = @calls
+      Session.offer_handler = method(:handle_inbound_offer)
+      Session.connection_promise = Async::Promise.new
+
+      endpoint = IO::Endpoint.tcp(config.host, config.port)
+      client = Librevox::Client.new(Session, endpoint, auth: config.password)
+      @client_task = Async { client.run }
+
+      # Wait for the session to be established
+      @session = Async::Task.current.with_timeout(config.default_timeout) do
+        Session.connection_promise.wait
+      end
+
+      self
+    rescue Async::TimeoutError
+      @client_task&.stop
+      @client_task = nil
+      raise Switest::ConnectionError, "Timed out connecting to FreeSWITCH"
+    end
+
+    def stop
+      hangup_all
+      @client_task&.stop
+      @client_task = nil
+      @session = nil
+      @calls.clear
+      Session.call_registry = nil
+      Session.offer_handler = nil
+      Session.connection_promise = nil
+    end
+
+    def connected?
+      !@session.nil?
+    end
+
+    def hangup_all(cause: "NORMAL_CLEARING", timeout: 5)
+      active = @calls.values.reject(&:ended?)
+
+      active.each do |call|
+        call.hangup(cause, wait: false) rescue nil
+      end
+
+      deadline = Time.now + timeout
+      active.each do |call|
+        remaining = deadline - Time.now
+        break if remaining <= 0
+        call.wait_for_end(timeout: remaining) unless call.ended?
+      end
+    end
+
+    def dial(to:, from: nil, timeout: nil, headers: {})
+      uuid = SecureRandom.uuid
+
+      vars = {
+        origination_uuid: uuid,
+        return_ring_ready: true
+      }
+      vars.merge!(FromParser.parse(from)) if from
+      vars[:originate_timeout] = timeout if timeout
+
+      var_string = Escaper.build_var_string(vars, headers)
+
+      call = Call.new(
+        id: uuid,
+        direction: :outbound,
+        to: to,
+        from: from,
+        headers: headers,
+        session: @session
+      )
+      @calls[uuid] = call
+
+      begin
+        @session.bgapi("originate #{var_string}#{to} &park()")
+      rescue
+        @calls.delete(uuid)
+        raise
+      end
+
+      call
+    end
+
+    def on_offer(&block)
+      @offer_handlers << block
+    end
+
+    def active_calls
+      @calls.select { |_k, v| v.alive? }
+    end
+
+    private
+
+    def handle_inbound_offer(event)
+      uuid = event.content[:unique_id]
+      data = event.content
+
+      call = Call.new(
+        id: uuid,
+        direction: :inbound,
+        to: data[:caller_destination_number],
+        from: data[:caller_caller_id_number],
+        headers: data,
+        session: @session
+      )
+      call.handle_callstate("RINGING")
+      @calls[uuid] = call
+
+      fire_offer(call)
+    end
+
+    def fire_offer(call)
+      @offer_handlers.each { |h| h.call(call) }
+    end
+  end
+end

data/lib/switest/{esl/escaper.rb → escaper.rb}

@@ -1,8 +1,7 @@
 # frozen_string_literal: true
 
 module Switest
-  module ESL
-    # Escapes values for use in FreeSWITCH channel variable strings.
+  # Escapes values for use in FreeSWITCH channel variable strings.
     #
     # FreeSWITCH originate syntax: {var1=value1,var2=value2}endpoint
     #
@@ -139,6 +138,5 @@ module Switest
         # Fallback - this should rarely happen
         ":"
       end
-    end
   end
 end