switest 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 53955d7e1a8c6b69c4a75f8f7ec87d7de55d99a515ef986e19f3645e0acf5dd5
+  data.tar.gz: 5375ca5a09fa90c44250264401a91cf37584d47af51222d2f2d19c2fe0f85cff
+SHA512:
+  metadata.gz: 8281a8651ebb7dc43d2776fd061b46b445f23872b6bdb48cd3eca55902fec82df6282d06343c95a182d7dd99dd614f52cbfa5e56c185f90bf3d008f017c7ba18
+  data.tar.gz: 1e00e657bcf9344e4a623d3314c9a94acccec6677c9ca5fb491e1a8a2c87a56bf2c332f5a416216eddff1839d6ba4804b25ddf8505a5234ae6ce94d996fdd518

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Relatel A/S
+
+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.md

@@ -0,0 +1,311 @@
+# Switest
+
+Functional testing for voice applications via FreeSWITCH ESL.
+
+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.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+  - [Scenario](#scenario)
+  - [Agent](#agent)
+- [API Reference](#api-reference)
+  - [Agent Class Methods](#agent-class-methods)
+  - [Agent Instance Methods](#agent-instance-methods)
+  - [Scenario Assertions](#scenario-assertions)
+  - [Dial Options](#dial-options)
+  - [Guards](#guards)
+- [DTMF](#dtmf)
+- [Docker / FreeSWITCH Setup](#docker--freeswitch-setup)
+- [Configuration](#configuration)
+- [Dependencies](#dependencies)
+- [License](#license)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "switest"
+```
+
+Then run `bundle install`.
+
+## Quick Start
+
+```ruby
+require "minitest"
+require "switest"
+
+class MyScenario < Switest::Scenario
+  def test_outbound_call
+    alice = Agent.dial("sofia/gateway/provider/+4512345678")
+    assert alice.wait_for_answer(timeout: 10), "Call should be answered"
+
+    alice.hangup
+    assert alice.ended?, "Call should be ended"
+  end
+end
+```
+
+Run with Minitest's rake task:
+
+```ruby
+# Rakefile
+require "minitest/test_task"
+
+Minitest::TestTask.create(:test) do |t|
+  t.libs << "lib" << "test"
+  t.test_globs = ["test/**/*_test.rb"]
+end
+```
+
+```bash
+bundle exec rake test
+```
+
+## Core Concepts
+
+### 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.
+
+```ruby
+class MyTest < Switest::Scenario
+  def test_something
+    # Agent, assert_call, hangup_all, etc. are available here
+  end
+end
+```
+
+### Agent
+
+An **Agent** represents a party in a call. There are two kinds:
+
+**Outbound** — initiates a call:
+
+```ruby
+alice = Agent.dial("sofia/gateway/provider/+4512345678")
+alice.wait_for_answer(timeout: 10)
+alice.hangup
+```
+
+**Inbound** — listens for an incoming call matching a guard:
+
+```ruby
+bob = Agent.listen_for_call(to: /^1000/)
+# ... something triggers an inbound call to 1000 ...
+bob.wait_for_call(timeout: 5)
+bob.answer
+```
+
+#### wait_for_answer vs answer
+
+| Method                        | Direction    | What it does                                |
+|-------------------------------|-------------|---------------------------------------------|
+| `wait_for_answer(timeout:)`   | Outbound    | Passively waits for the remote to answer    |
+| `answer(wait:)`               | Inbound     | Actively answers the call                   |
+
+#### wait_for_end vs hangup
+
+| Method                   | Use case              | What it does                         |
+|--------------------------|-----------------------|--------------------------------------|
+| `wait_for_end(timeout:)` | Remote hangs up       | Passively waits for the call to end  |
+| `hangup(wait:)`          | You hang up           | Sends hangup and waits               |
+
+## API Reference
+
+### Agent Class Methods
+
+```ruby
+Agent.dial(destination, from: nil, timeout: nil, headers: {})
+Agent.listen_for_call(guards)  # e.g. to: /pattern/, from: /pattern/
+```
+
+### Agent Instance Methods
+
+#### Actions
+
+```ruby
+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.send_dtmf(digits)           # Send DTMF tones
+agent.receive_dtmf(count:, timeout:)  # Receive DTMF digits
+```
+
+#### Waits
+
+```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_end(timeout: 5)     # Wait for call to end
+```
+
+#### State
+
+```ruby
+agent.call?       # Has a call object?
+agent.alive?      # Call exists and not ended?
+agent.active?     # Answered and not ended?
+agent.answered?   # Has been answered?
+agent.ended?      # Has ended?
+agent.start_time  # When call started
+agent.answer_time # When answered
+agent.end_reason  # e.g. "NORMAL_CLEARING"
+```
+
+### Scenario Assertions
+
+`Switest::Scenario` provides these assertions:
+
+```ruby
+assert_call(agent, timeout: 5)         # Agent receives a call
+assert_no_call(agent, timeout: 2)      # Agent does NOT receive a call
+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
+```
+
+The `hangup_all` helper ends all active calls (useful before CDR assertions):
+
+```ruby
+hangup_all(cause: "NORMAL_CLEARING", timeout: 5)
+```
+
+### Dial Options
+
+```ruby
+Agent.dial(
+  "sofia/gateway/provider/+4512345678",
+  from: "+4587654321",                  # Caller ID (number and name)
+  timeout: 30,                          # Originate timeout in seconds
+  headers: { "Privacy" => "user;id" }   # Custom SIP headers (auto-prefixed sip_h_)
+)
+```
+
+The `from:` parameter accepts several formats:
+
+| Format                                    | Effect                                   |
+|-------------------------------------------|------------------------------------------|
+| `"+4512345678"`                           | Sets caller ID number and name           |
+| `"tel:+4512345678"`                       | Same, strips `tel:` prefix               |
+| `"sip:user@host"`                         | Sets `sip_from_uri`                      |
+| `"Display Name sip:user@host"`            | Sets display name + SIP URI              |
+| `'"Display Name" <sip:user@host>'`        | Quoted display name + angle-bracketed URI|
+
+### Guards
+
+Guards filter which inbound calls match `listen_for_call`:
+
+```ruby
+Agent.listen_for_call(to: /^1000/)               # Regex on destination
+Agent.listen_for_call(from: /^\+45/)              # Regex on caller ID
+Agent.listen_for_call(to: "1000")                 # Exact match
+Agent.listen_for_call(to: /^1000/, from: /^\+45/) # Multiple (AND logic)
+```
+
+## DTMF
+
+Send DTMF tones on an active call:
+
+```ruby
+alice.send_dtmf("123#")
+```
+
+Receive DTMF from the remote party:
+
+```ruby
+digits = alice.receive_dtmf(count: 4, timeout: 5)
+assert_equal "1234", digits
+```
+
+Or use the assertion helper:
+
+```ruby
+assert_dtmf(alice, "1234", timeout: 5)
+```
+
+DTMF events are routed per-call — concurrent calls each receive only their
+own digits.
+
+## Docker / FreeSWITCH Setup
+
+The project includes a `compose.yml` for running FreeSWITCH locally:
+
+```bash
+docker compose up -d freeswitch          # start FreeSWITCH
+docker compose run --rm test             # run integration tests
+```
+
+The compose file mounts three 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/dialplan.xml`              | `/etc/freeswitch/dialplan/public/00_switest.xml`                |
+
+### FreeSWITCH Requirements
+
+1. **mod_event_socket** must be loaded (default).
+
+2. `event_socket.conf.xml` must allow connections:
+
+```xml
+<configuration name="event_socket.conf" description="Socket Client">
+  <settings>
+    <param name="nat-map" value="false"/>
+    <param name="listen-ip" value="0.0.0.0"/>
+    <param name="listen-port" value="8021"/>
+    <param name="password" value="ClueCon"/>
+  </settings>
+</configuration>
+```
+
+3. A dialplan that parks inbound calls so Switest can control them:
+
+```xml
+<extension name="switest-park">
+  <condition>
+    <action application="park"/>
+  </condition>
+</extension>
+```
+
+## Configuration
+
+```ruby
+Switest.configure do |config|
+  config.host = "127.0.0.1"     # FreeSWITCH host
+  config.port = 8021             # ESL port
+  config.password = "ClueCon"   # ESL password
+  config.default_timeout = 5    # Default timeout for waits
+end
+```
+
+Or via environment variables (used by the integration test helper):
+
+```bash
+FREESWITCH_HOST=127.0.0.1
+FREESWITCH_PORT=8021
+FREESWITCH_PASSWORD=ClueCon
+```
+
+## Dependencies
+
+- Ruby >= 3.0
+- concurrent-ruby ~> 1.2
+- minitest >= 5.5, < 7.0
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.

data/lib/switest/agent.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Switest
+  class Agent
+    class << self
+      # Shared client for all agents in a test
+      attr_accessor :client, :events
+
+      def setup(client, events)
+        @client = client
+        @events = events
+      end
+
+      def teardown
+        @client = nil
+        @events = nil
+      end
+
+      def dial(destination, from: nil, timeout: nil, headers: {})
+        raise "Agent.setup not called" unless @client
+
+        call = @client.dial(to: destination, from: from, timeout: timeout, headers: headers)
+        new(call)
+      end
+
+      def listen_for_call(guards = {})
+        raise "Agent.setup not called" unless @client
+
+        agent = new(nil)
+
+        # Register a one-time handler for matching inbound calls
+        @events.once(:offer, guards) do |data|
+          agent.instance_variable_set(:@call, data[:call])
+        end
+
+        agent
+      end
+    end
+
+    attr_reader :call
+
+    def initialize(call)
+      @call = call
+    end
+
+    def call?
+      !@call.nil?
+    end
+
+    def answer(wait: 5)
+      raise "No call to answer" unless @call
+      @call.answer(wait: wait)
+    end
+
+    def hangup(wait: 5)
+      raise "No call to hangup" unless @call
+      @call.hangup(wait: wait)
+    end
+
+    def reject(reason = :decline)
+      raise "No call to reject" unless @call
+      @call.reject(reason)
+    end
+
+    def send_dtmf(digits)
+      raise "No call for DTMF" unless @call
+      @call.send_dtmf(digits)
+    end
+
+    def receive_dtmf(count: 1, timeout: 5)
+      raise "No call for DTMF" unless @call
+      @call.receive_dtmf(count: count, timeout: timeout)
+    end
+
+    def wait_for_call(timeout: 5)
+      deadline = Time.now + timeout
+      while Time.now < deadline
+        return true if @call
+        sleep 0.1
+      end
+      false
+    end
+
+    def wait_for_answer(timeout: 5)
+      raise "No call to wait for" unless @call
+      @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)
+    end
+
+    # Delegate state queries to call
+    def alive?
+      @call&.alive? || false
+    end
+
+    def active?
+      @call&.active? || false
+    end
+
+    def answered?
+      @call&.answered? || false
+    end
+
+    def ended?
+      @call&.ended? || false
+    end
+
+    def start_time
+      @call&.start_time
+    end
+
+    def answer_time
+      @call&.answer_time
+    end
+
+    def end_reason
+      @call&.end_reason
+    end
+  end
+end

data/lib/switest/case_insensitive_hash.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Switest
+  # Hash subclass with case-insensitive key lookup
+  class CaseInsensitiveHash < Hash
+    def self.from(hash)
+      new.merge!(hash)
+    end
+
+    def [](key)
+      return super if key?(key)
+      key_downcase = key.downcase
+      found_key = keys.find { |k| k.downcase == key_downcase }
+      found_key ? super(found_key) : nil
+    end
+  end
+end

data/lib/switest/configuration.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Switest
+  class Configuration
+    attr_accessor :host, :port, :password, :default_timeout
+
+    def initialize
+      @host = "127.0.0.1"
+      @port = 8021
+      @password = "ClueCon"
+      @default_timeout = 5
+    end
+
+    def to_h
+      {
+        host: @host,
+        port: @port,
+        password: @password,
+        default_timeout: @default_timeout
+      }
+    end
+  end
+end

data/lib/switest/esl/call.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "concurrent"
+
+module Switest
+  module ESL
+    class Call
+      attr_reader :id, :to, :from, :headers, :direction
+      attr_reader :start_time, :answer_time, :end_time, :end_reason
+      attr_reader :state
+
+      def initialize(id:, connection:, direction:, to: nil, from: nil, headers: {})
+        @id = id
+        @connection = connection
+        @direction = direction  # :inbound or :outbound
+        @to = to
+        @from = from
+        @headers = Switest::CaseInsensitiveHash.from(headers)
+
+        @state = :offered
+        @start_time = Time.now
+        @answer_time = nil
+        @end_time = nil
+        @end_reason = nil
+
+        @bridged = false
+        @dtmf_buffer = Queue.new
+        @callbacks = { answer: [], bridge: [], end: [] }
+        @mutex = Mutex.new
+
+        @answered_latch = Concurrent::CountDownLatch.new(1)
+        @bridged_latch = Concurrent::CountDownLatch.new(1)
+        @ended_latch = Concurrent::CountDownLatch.new(1)
+      end
+
+      # State queries
+      def alive?
+        @state != :ended
+      end
+
+      def active?
+        @state == :answered
+      end
+
+      def answered?
+        @state == :answered || (@state == :ended && @answer_time)
+      end
+
+      def ended?
+        @state == :ended
+      end
+
+      def bridged?
+        @bridged
+      end
+
+      def inbound?
+        @direction == :inbound
+      end
+
+      def outbound?
+        @direction == :outbound
+      end
+
+      # Actions
+      def answer(wait: 5)
+        return unless @state == :offered && inbound?
+        sendmsg("execute", "answer")
+        return unless wait
+        wait_for_answer(timeout: wait)
+      end
+
+      def hangup(cause = "NORMAL_CLEARING", wait: 5)
+        return if ended?
+        msg = +"sendmsg #{@id}\n"
+        msg << "call-command: hangup\n"
+        msg << "hangup-cause: #{cause}"
+        @connection.send_command(msg)
+        return unless wait
+        wait_for_end(timeout: wait)
+      end
+
+      def reject(reason = :decline, wait: 5)
+        return unless @state == :offered && 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 receive_dtmf(count: 1, timeout: 5)
+        digits = String.new
+        deadline = Time.now + timeout
+
+        count.times do
+          remaining = deadline - Time.now
+          break if remaining <= 0
+
+          begin
+            digit = @dtmf_buffer.pop(timeout: remaining)
+            digits << digit if digit
+          rescue ThreadError
+            break # Timeout
+          end
+        end
+
+        digits
+      end
+
+      # Callbacks
+      def on_answer(&block)
+        @mutex.synchronize { @callbacks[:answer] << block }
+      end
+
+      def on_bridge(&block)
+        @mutex.synchronize { @callbacks[:bridge] << block }
+      end
+
+      def on_end(&block)
+        @mutex.synchronize { @callbacks[:end] << block }
+      end
+
+      # Blocking waits
+      def wait_for_answer(timeout: 5)
+        @answered_latch.wait(timeout)
+        answered?
+      end
+
+      def wait_for_bridge(timeout: 5)
+        @bridged_latch.wait(timeout)
+        bridged?
+      end
+
+      def wait_for_end(timeout: 5)
+        @ended_latch.wait(timeout)
+        ended?
+      end
+
+      # Internal state updates (called by Client)
+      def handle_answer
+        @mutex.synchronize do
+          return if @state == :ended
+          @state = :answered
+          @answer_time = Time.now
+        end
+        @answered_latch.count_down
+        fire_callbacks(:answer)
+      end
+
+      def handle_bridge
+        @mutex.synchronize do
+          return if @state == :ended
+          @bridged = true
+        end
+        @bridged_latch.count_down
+        fire_callbacks(:bridge)
+      end
+
+      def handle_hangup(cause, headers = {})
+        @mutex.synchronize do
+          return if @state == :ended
+          @state = :ended
+          @end_time = Time.now
+          @end_reason = cause
+          @headers.merge!(headers)
+        end
+        @answered_latch.count_down  # Release any waiting threads
+        @bridged_latch.count_down
+        @ended_latch.count_down
+        fire_callbacks(:end)
+      end
+
+      def handle_dtmf(digit)
+        @dtmf_buffer.push(digit)
+      end
+
+      private
+
+      def sendmsg(command, app = nil, arg = nil, event_lock: false)
+        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
+        @connection.send_command(msg.chomp)
+      end
+
+
+      def fire_callbacks(type)
+        callbacks = @mutex.synchronize { @callbacks[type].dup }
+        callbacks.each { |cb| cb.call(self) }
+      end
+    end
+  end
+end