adhearsion 2.4.0 → 2.5.0

data/spec/adhearsion/call_controller/output/formatter_spec.rb

@@ -24,15 +24,17 @@ module Adhearsion
         end
 
         describe "#ssml_for_collection" do
-          let(:collection) { ["/foo/bar.wav", 1, Time.now] }
+          let(:collection) { ["/foo/bar.wav", 1, Time.now, '123*'] }
           let :ssml do
             file = collection[0]
             n = collection[1].to_s
             t = collection[2].to_s
+            c = collection[3].to_s
             RubySpeech::SSML.draw do
               audio :src => file
               say_as(:interpret_as => 'cardinal') { n }
               say_as(:interpret_as => 'time') { t }
+              say_as(:interpret_as => 'characters') { c }
             end
           end
 
@@ -78,6 +80,16 @@ module Adhearsion
             subject.detect_type(number).should be :numeric
           end
 
+          it "detects a String of digits" do
+            number = '123'
+            subject.detect_type(number).should be :numeric
+          end
+
+          it "detects a String of characters" do
+            number = '123#'
+            subject.detect_type(number).should be :characters
+          end
+
           ["Foo", "Foo bar", "The answer: foo", "The answer could be foo/bar"].each do |string|
             it "detects '#{string}' as text" do
               subject.detect_type(string).should be :text

data/spec/adhearsion/call_controller/output_spec.rb

@@ -338,6 +338,13 @@ module Adhearsion
         let(:extra_options) do
           { renderer: :native }
         end
+
+        describe "with a nil argument" do
+          it "is a noop" do
+            subject.play nil
+          end
+        end
+
         describe "with a single string" do
           let(:audio_file) { "/foo/bar.wav" }
           let :ssml do
@@ -357,15 +364,17 @@ module Adhearsion
         end
 
         describe "with multiple arguments" do
-          let(:args) { ["/foo/bar.wav", 1, Time.now] }
+          let(:args) { ["/foo/bar.wav", 1, Time.now, "123#"] }
           let :ssml do
             file = args[0]
             n = args[1].to_s
             t = args[2].to_s
+            c = args[3].to_s
             RubySpeech::SSML.draw do
               audio :src => file
               say_as(:interpret_as => 'cardinal') { n }
               say_as(:interpret_as => 'time') { t }
+              say_as(:interpret_as => 'characters') { c }
             end
           end
 
@@ -398,6 +407,12 @@ module Adhearsion
             expect_ssml_output ssml
             subject.play(args).should be true
           end
+
+          context "that is empty" do
+            it "is a noop" do
+              subject.play []
+            end
+          end
         end
 
         describe "with a number" do
@@ -496,6 +511,13 @@ module Adhearsion
         let(:extra_options) do
           { renderer: :native }
         end
+
+        describe "with a nil argument" do
+          it "is a noop" do
+            subject.play! nil
+          end
+        end
+
         describe "with a single string" do
           let(:audio_file) { "/foo/bar.wav" }
           let :ssml do
@@ -731,6 +753,12 @@ module Adhearsion
       end
 
       describe "#say" do
+        describe "with a nil argument" do
+          it "is a no-op" do
+            subject.say nil
+          end
+        end
+
         describe "with a RubySpeech document" do
           it 'plays the correct SSML' do
             ssml = RubySpeech::SSML.draw { string "Hello world" }
@@ -829,6 +857,12 @@ module Adhearsion
       end
 
       describe "#say!" do
+        describe "with a nil argument" do
+          it "is a noop" do
+            subject.say! nil
+          end
+        end
+
         describe "with a RubySpeech document" do
           it 'plays the correct SSML' do
             ssml = RubySpeech::SSML.draw { string "Hello world" }

data/spec/adhearsion/call_controller_spec.rb

@@ -28,6 +28,13 @@ module Adhearsion
     its(:logger)    { should be call.logger }
     its(:variables) { should be call.variables }
 
+    describe "#send_message" do
+      it 'should send a message' do
+        call.should_receive(:send_message).with("Hello World!").once
+        subject.send_message "Hello World!"
+      end
+    end
+
     context "when the call is dead" do
       before { call.terminate }
 
@@ -49,6 +56,17 @@ module Adhearsion
         subject.execute!
       end
 
+      context "when trying to execute a command against a dead call" do
+        before do
+          subject.should_receive(:run).once.ordered.and_raise(Call::ExpiredError)
+        end
+
+        it "gracefully terminates " do
+          subject.logger.should_receive(:info).once.with(/Call was hung up/).ordered
+          subject.execute!
+        end
+      end
+
       it "catches standard errors, triggering an exception event" do
         subject.should_receive(:run).once.ordered.and_raise(StandardError)
         latch = CountDownLatch.new 1
@@ -165,26 +183,28 @@ module Adhearsion
     end
 
     describe "#pass" do
-      class PassController < CallController
-        after_call :foobar
-
-        def run
-          before
-          pass SecondController, :foo => 'bar'
-          after
-        end
+      let(:pass_controller) do
+        Class.new CallController do
+          after_call :foobar
+
+          def run
+            before
+            pass SecondController, :foo => 'bar'
+            after
+          end
 
-        def before
-        end
+          def before
+          end
 
-        def after
-        end
+          def after
+          end
 
-        def foobar
+          def foobar
+          end
         end
       end
 
-      subject { PassController.new call }
+      subject { pass_controller.new call }
 
       before do
         call.wrapped_object.stub :write_and_await_response => nil
@@ -211,6 +231,142 @@ module Adhearsion
       end
     end
 
+    describe "#hard_pass" do
+      let(:pass_controller) do
+        Class.new CallController do
+          def run
+            hard_pass SecondController, foo: 'bar'
+          end
+        end
+      end
+
+      subject { pass_controller.new call }
+
+      before do
+        call.wrapped_object.stub(:write_and_await_response).and_return do |command|
+          command.request!
+          command.execute!
+        end
+        call.stub register_controller: nil
+        SecondController.any_instance.should_receive(:md_check).once.with :foo => 'bar'
+        Events.should_receive(:trigger).with(:exception, Exception).never
+      end
+
+      it "should cease execution of the current controller, and instruct the call to execute another" do
+        call.should_receive(:answer).once.ordered
+
+        subject.exec
+      end
+
+      context "when components have been executed on the controller" do
+        let(:pass_controller) do
+          Class.new CallController do
+            attr_accessor :output1, :output2
+
+            def prep_output
+              @output1 = play! 'file://foo.wav'
+              @output2 = play! 'file://bar.wav'
+            end
+
+            def run
+              hard_pass SecondController, foo: 'bar'
+            end
+          end
+        end
+
+        before { subject.prep_output }
+
+        context "but not yet received a complete event" do
+          it "should terminate the components" do
+            subject.output1.should_receive(:stop!).once
+            subject.output2.should_receive(:stop!).once
+
+            subject.exec
+          end
+
+          context "and some fail to terminate" do
+            before { subject.output1.should_receive(:stop!).and_raise(Punchblock::Component::InvalidActionError) }
+
+            it "should terminate the others" do
+              subject.output2.should_receive(:stop!).once
+              subject.exec
+            end
+          end
+        end
+
+        context "when some have completed" do
+          before { subject.output1.trigger_event_handler Punchblock::Event::Complete.new }
+
+          it "should not terminate the completed components" do
+            subject.output1.should_receive(:stop!).never
+            subject.output2.should_receive(:stop!).once
+
+            subject.exec
+          end
+        end
+      end
+    end
+
+    describe '#stop_all_components' do
+      let(:stop_controller) do
+        Class.new CallController do
+          attr_accessor :output1, :output2
+
+          def prep_output
+            @output1 = play! 'file://foo.wav'
+            @output2 = play! 'file://bar.wav'
+          end
+
+          def run
+            stop_all_components
+          end
+        end
+      end
+
+      subject { stop_controller.new call }
+
+      context "when components have been executed on the controller" do
+        before do
+          call.wrapped_object.stub(:write_and_await_response).and_return do |command|
+            command.request!
+            command.execute!
+          end
+          call.stub register_controller: nil
+          Events.should_receive(:trigger).with(:exception, Exception).never
+          subject.prep_output
+        end
+
+        context "when they have not yet received a complete event" do
+          it "should terminate the components" do
+            subject.output1.should_receive(:stop!).once
+            subject.output2.should_receive(:stop!).once
+
+            subject.exec
+          end
+
+          context "and some fail to terminate" do
+            before { subject.output1.should_receive(:stop!).and_raise(Punchblock::Component::InvalidActionError) }
+
+            it "should terminate the others" do
+              subject.output2.should_receive(:stop!).once
+              subject.exec
+            end
+          end
+        end
+
+        context "when some have completed" do
+          before { subject.output1.trigger_event_handler Punchblock::Event::Complete.new }
+
+          it "should not terminate the completed components" do
+            subject.output1.should_receive(:stop!).never
+            subject.output2.should_receive(:stop!).once
+
+            subject.exec
+          end
+        end
+      end
+    end
+
     describe "#write_and_await_response" do
       let(:message) { Punchblock::Command::Accept.new }
 
@@ -249,7 +405,7 @@ module Adhearsion
     describe "#join" do
       it "delegates to the call, blocking first until it is allowed to execute, and unblocking when an unjoined event is received" do
         subject.should_receive(:block_until_resumed).once.ordered
-        subject.call.should_receive(:join).once.with('call1', :foo => :bar).ordered.and_return Punchblock::Command::Join.new(:call_id => 'call1')
+        call.wrapped_object.should_receive(:write_and_await_response).once.ordered.with(Punchblock::Command::Join.new(call_uri: 'call1'))
         latch = CountDownLatch.new 1
         Thread.new do
           subject.join 'call1', :foo => :bar
@@ -265,7 +421,7 @@ module Adhearsion
       context "with a mixer" do
         it "delegates to the call, blocking first until it is allowed to execute, and unblocking when an unjoined event is received" do
           subject.should_receive(:block_until_resumed).once.ordered
-          subject.call.should_receive(:join).once.with({:mixer_name => 'foobar', :foo => :bar}, {}).ordered.and_return Punchblock::Command::Join.new(:mixer_name => 'foobar')
+          call.wrapped_object.should_receive(:write_and_await_response).once.ordered.with(Punchblock::Command::Join.new(mixer_name: 'foobar'))
           latch = CountDownLatch.new 1
           Thread.new do
             subject.join :mixer_name => 'foobar', :foo => :bar
@@ -282,7 +438,7 @@ module Adhearsion
       context "with :async => true" do
         it "delegates to the call, blocking first until it is allowed to execute, and unblocking when the joined event is received" do
           subject.should_receive(:block_until_resumed).once.ordered
-          subject.call.should_receive(:join).once.with('call1', :foo => :bar).ordered.and_return Punchblock::Command::Join.new(:call_id => 'call1')
+          call.wrapped_object.should_receive(:write_and_await_response).once.ordered.with(Punchblock::Command::Join.new(call_uri: 'call1'))
           latch = CountDownLatch.new 1
           Thread.new do
             subject.join 'call1', :foo => :bar, :async => true
@@ -296,7 +452,7 @@ module Adhearsion
         context "with a mixer" do
           it "delegates to the call, blocking first until it is allowed to execute, and unblocking when the joined event is received" do
             subject.should_receive(:block_until_resumed).once.ordered
-            subject.call.should_receive(:join).once.with({:mixer_name => 'foobar', :foo => :bar}, {}).ordered.and_return Punchblock::Command::Join.new(:mixer_name => 'foobar')
+            call.wrapped_object.should_receive(:write_and_await_response).once.ordered.with(Punchblock::Command::Join.new(mixer_name: 'foobar'))
             latch = CountDownLatch.new 1
             Thread.new do
               subject.join :mixer_name => 'foobar', :foo => :bar, :async => true

data/spec/adhearsion/call_spec.rb

@@ -37,6 +37,20 @@ module Adhearsion
       Adhearsion.active_calls.clear
     end
 
+    it "should do recursion detection on inspect" do
+      subject[:foo] = subject
+      Timeout.timeout(0.2) do
+        expect(subject.inspect).to match('...')
+      end
+    end
+
+    it "should allow timers to be registered from outside" do
+      foo = :bar
+      subject.after(1) { foo = :baz }
+      sleep 1.1
+      foo.should == :baz
+    end
+
     it { should respond_to :<< }
 
     its(:end_reason) { should be == nil }
@@ -50,6 +64,8 @@ module Adhearsion
     its(:to)      { should be == to }
     its(:from)    { should be == from }
 
+    its(:auto_hangup) { should be_true }
+
     context "when the ID is nil" do
       let(:call_id) { nil }
 
@@ -141,28 +157,52 @@ module Adhearsion
       end
     end
 
-    it 'allows the registration of event handlers which are called when messages are delivered' do
-      event = double 'Event'
-      event.should_receive(:foo?).and_return true
-      response = double 'Response'
-      response.should_receive(:call).once
-      subject.register_event_handler(:foo?) { response.call }
-      subject << event
+    context 'registered event handlers' do
+      let(:event)     { double 'Event' }
+      let(:response)  { double 'Response' }
+
+      it 'are called when messages are delivered' do
+        event.should_receive(:foo?).and_return true
+        response.should_receive(:call).once
+        subject.register_event_handler(:foo?) { response.call }
+        subject << event
+      end
+
+      context 'when a handler raises' do
+        it 'does not cause the call actor to crash' do
+          subject.register_event_handler { raise 'Boom' }
+          subject << event
+          subject.should be_alive
+        end
+
+        it "triggers an exception event" do
+          e = StandardError.new('Boom')
+          Events.should_receive(:trigger).once.with(:exception, [e, subject.logger])
+          subject.register_event_handler { raise e }
+          subject << event
+        end
+
+        it 'executes all handlers for each event' do
+          response.should_receive(:call).once
+          subject.register_event_handler { raise 'Boom' }
+          subject.register_event_handler { response.call }
+          subject << event
+        end
+      end
     end
 
     describe "event handlers" do
-      before { pending }
       let(:response) { double 'Response' }
 
       describe "for joined events" do
         context "joined to another call" do
           let :event do
-            Punchblock::Event::Joined.new call_uri: 'xmpp:foobar@rayo.net'
+            Punchblock::Event::Joined.new call_uri: 'footransport:foobar@rayo.net'
           end
 
           it "should trigger any on_joined callbacks set for the matching call ID" do
             response.should_receive(:call).once.with(event)
-            subject.on_joined(:call_uri => 'xmpp:foobar@rayo.net') { |event| response.call event }
+            subject.on_joined(:call_uri => 'footransport:foobar@rayo.net') { |event| response.call event }
             subject << event
           end
 
@@ -175,14 +215,14 @@ module Adhearsion
           it "should trigger any on_joined callbacks set for the matching call" do
             response.should_receive(:call).once.with(event)
             call = Call.new
-            call.wrapped_object.stub id: 'foobar', domain: 'rayo.net'
+            call.wrapped_object.stub id: 'foobar', domain: 'rayo.net', transport: 'footransport'
             subject.on_joined(call) { |event| response.call event }
             subject << event
           end
 
           it "should not trigger on_joined callbacks for other call IDs" do
             response.should_receive(:call).never
-            subject.on_joined(:call_id => 'barfoo') { |event| response.call event }
+            subject.on_joined(:call_uri => 'barfoo') { |event| response.call event }
             subject << event
           end
 
@@ -212,7 +252,7 @@ module Adhearsion
 
           it "should not trigger any on_joined callbacks set for calls" do
             response.should_receive(:call).never
-            subject.on_joined(:call_id => 'foobar') { |event| response.call event }
+            subject.on_joined(:call_uri => 'foobar') { |event| response.call event }
             subject << event
           end
 
@@ -225,7 +265,7 @@ module Adhearsion
           it "should not trigger any on_joined callbacks set for the matching call" do
             response.should_receive(:call).never
             call = Call.new
-            call.stub :id => 'foobar'
+            call.wrapped_object.stub :id => 'foobar'
             subject.on_joined(call) { |event| response.call event }
             subject << event
           end
@@ -235,12 +275,12 @@ module Adhearsion
       describe "for unjoined events" do
         context "unjoined from another call" do
           let :event do
-            Punchblock::Event::Unjoined.new call_uri: 'xmpp:foobar@rayo.net'
+            Punchblock::Event::Unjoined.new call_uri: 'footransport:foobar@rayo.net'
           end
 
           it "should trigger any on_unjoined callbacks set for the matching call ID" do
             response.should_receive(:call).once.with(event)
-            subject.on_unjoined(:call_uri => 'xmpp:foobar@rayo.net') { |event| response.call event }
+            subject.on_unjoined(:call_uri => 'footransport:foobar@rayo.net') { |event| response.call event }
             subject << event
           end
 
@@ -253,14 +293,14 @@ module Adhearsion
           it "should trigger any on_unjoined callbacks set for the matching call" do
             response.should_receive(:call).once.with(event)
             call = Call.new
-            call.wrapped_object.stub id: 'foobar', domain: 'rayo.net'
+            call.wrapped_object.stub id: 'foobar', domain: 'rayo.net', transport: 'footransport'
             subject.on_unjoined(call) { |event| response.call event }
             subject << event
           end
 
           it "should not trigger on_unjoined callbacks for other call IDs" do
             response.should_receive(:call).never
-            subject.on_unjoined(:call_id => 'barfoo') { |event| response.call event }
+            subject.on_unjoined(:call_uri => 'barfoo') { |event| response.call event }
             subject << event
           end
 
@@ -290,7 +330,7 @@ module Adhearsion
 
           it "should not trigger any on_unjoined callbacks set for calls" do
             response.should_receive(:call).never
-            subject.on_unjoined(:call_id => 'foobar') { |event| response.call event }
+            subject.on_unjoined(:call_uri => 'foobar') { |event| response.call event }
             subject << event
           end
 
@@ -303,7 +343,7 @@ module Adhearsion
           it "should not trigger any on_unjoined callbacks set for the matching call" do
             response.should_receive(:call).never
             call = Call.new
-            call.stub :id => 'foobar'
+            call.wrapped_object.stub :id => 'foobar'
             subject.on_unjoined(call) { |event| response.call event }
             subject << event
           end
@@ -346,54 +386,121 @@ module Adhearsion
     end
 
     context "peer registry" do
-      let(:other_call_id) { 'foobar' }
+      let(:other_call_uri) { 'xmpp:foobar@example.com' }
       let(:other_call) { Call.new }
 
-      before { other_call.stub :id => other_call_id }
+      before { other_call.stub uri: other_call_uri }
 
       let :joined_event do
-        Punchblock::Event::Joined.new call_uri: other_call_id
+        Punchblock::Event::Joined.new call_uri: other_call_uri
       end
 
       let :unjoined_event do
-        Punchblock::Event::Unjoined.new call_uri: other_call_id
+        Punchblock::Event::Unjoined.new call_uri: other_call_uri
       end
 
       context "when we know about the joined call" do
         before { Adhearsion.active_calls << other_call }
+        after { Adhearsion.active_calls.remove_inactive_call other_call }
 
         it "should add the peer to its registry" do
           subject << joined_event
-          subject.peers.should == {'foobar' => other_call}
+          subject.peers.should == {'xmpp:foobar@example.com' => other_call}
+        end
+
+        context "in a handler for the joined event" do
+          it "should have already populated the registry" do
+            peer = nil
+
+            subject.on_joined do |event|
+              peer = subject.peers.keys.first
+            end
+
+            subject << joined_event
+
+            peer.should == other_call_uri
+          end
+        end
+
+        context "when being unjoined from a previously joined call" do
+          before { subject << joined_event }
+
+          it "should remove the peer from its registry" do
+            subject.peers.should_not eql({})
+            subject << unjoined_event
+            subject.peers.should eql({})
+          end
+
+          context "in a handler for the unjoined event" do
+            it "should have already been removed the registry" do
+              peer_count = nil
+
+              subject.on_unjoined do |event|
+                peer_count = subject.peers.size
+              end
+
+              subject << unjoined_event
+
+              peer_count.should == 0
+            end
+          end
         end
       end
 
       context "when we don't know about the joined call" do
         it "should add a nil entry to its registry" do
           subject << joined_event
-          subject.peers.should == {'foobar' => nil}
+          subject.peers.should == {'xmpp:foobar@example.com' => nil}
         end
-      end
 
-      it "should not return the same registry every call" do
-        subject.peers.should_not be subject.peers
-      end
+        context "in a handler for the joined event" do
+          it "should have already populated the registry" do
+            peer = nil
 
-      context "when being unjoined from a previously joined call" do
-        before { subject << joined_event }
+            subject.on_joined do |event|
+              peer = subject.peers.keys.first
+            end
+
+            subject << joined_event
 
-        it "should remove the peer from its registry" do
-          subject.peers.should_not eql({})
-          subject << unjoined_event
-          subject.peers.should eql({})
+            peer.should == other_call_uri
+          end
         end
+
+        context "when being unjoined from a previously joined call" do
+          before { subject << joined_event }
+
+          it "should remove the peer from its registry" do
+            subject.peers.should_not eql({})
+            subject << unjoined_event
+            subject.peers.should eql({})
+          end
+
+          context "in a handler for the unjoined event" do
+            it "should have already been removed the registry" do
+              peer_count = nil
+
+              subject.on_unjoined do |event|
+                peer_count = subject.peers.size
+              end
+
+              subject << unjoined_event
+
+              peer_count.should == 0
+            end
+          end
+        end
+      end
+
+      it "should not return the same registry every call" do
+        subject.peers.should_not be subject.peers
       end
     end
 
     describe "#<<" do
       describe "with a Punchblock End" do
         let :end_event do
-          Punchblock::Event::End.new :reason => :hangup
+          Punchblock::Event::End.new :reason => :hangup, :platform_code => 'arbitrary_code'
         end
 
         it "should mark the call as ended" do
@@ -406,6 +513,11 @@ module Adhearsion
           subject.end_reason.should be == :hangup
         end
 
+        it "should set the end code" do
+          subject << end_event
+          subject.end_code.should be == 'arbitrary_code'
+        end
+
         it "should set the end time" do
           finish_time = Time.local(2008, 9, 1, 12, 1, 3)
           Timecop.freeze finish_time
@@ -654,6 +766,20 @@ module Adhearsion
       end
     end
 
+    describe "#send_message" do
+      it "should send a message through the Punchblock connection using the call ID and domain" do
+        subject.wrapped_object.should_receive(:client).once.and_return mock_client
+        mock_client.should_receive(:send_message).once.with(subject.id, subject.domain, "Hello World!", {})
+        subject.send_message "Hello World!"
+      end
+
+      it "should send a message with the given subject" do
+        subject.wrapped_object.should_receive(:client).once.and_return mock_client
+        mock_client.should_receive(:send_message).once.with(subject.id, subject.domain, nil, :subject => "Important Message")
+        subject.send_message nil, :subject => "Important Message"
+      end
+    end
+
     describe "basic control commands" do
       def expect_message_waiting_for_response(message = nil, fail = false, &block)
         expectation = subject.wrapped_object.should_receive(:write_and_await_response, &block).once
@@ -810,26 +936,156 @@ module Adhearsion
               subject.join target, :media => :bridge, :direction => :recv
             end
           end
+
+          it "should return the command" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+            result[:command].should be_a Punchblock::Command::Join
+            result[:command].call_uri.should eql(uri)
+            result[:command].media.should eql(:bridge)
+            result[:command].direction.should eql(:recv)
+          end
+
+          it "should return something that can be blocked on until the join is complete" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            result[:joined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            result[:joined_condition].wait(0.5).should be_true
+          end
+
+          it "should return something that can be blocked on until the entities are unjoined" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Unjoined.new(call_uri: uri)
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should unblock all conditions on call end if no joined/unjoined events are received" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            result[:joined_condition].wait(0.5).should be_false
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::End.new
+            result[:joined_condition].wait(0.5).should be_true
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should not error on call end when joined/unjoined events are received correctly" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            subject << Punchblock::Event::Unjoined.new(call_uri: uri)
+
+            subject << Punchblock::Event::End.new
+          end
+
+          it "should not error if multiple joined events are received for the same join" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+
+            subject.should be_alive
+          end
         end
 
         context "with a call ID" do
           let(:target) { rand.to_s }
+          let(:uri) { "footransport:#{target}@#{subject.domain}" }
 
           it "should send a join command joining to the provided call ID" do
-            expect_join_with_options call_uri: "footransport:#{target}@#{subject.domain}"
+            expect_join_with_options call_uri: uri
             subject.join target
           end
 
           context "and direction/media options" do
             it "should send a join command with the correct options" do
-              expect_join_with_options :call_uri => "footransport:#{target}@#{subject.domain}", :media => :bridge, :direction => :recv
+              expect_join_with_options :call_uri => uri, :media => :bridge, :direction => :recv
               subject.join target, :media => :bridge, :direction => :recv
             end
           end
+
+          it "should return the command" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+            result[:command].should be_a Punchblock::Command::Join
+            result[:command].call_uri.should eql(uri)
+            result[:command].media.should eql(:bridge)
+            result[:command].direction.should eql(:recv)
+          end
+
+          it "should return something that can be blocked on until the join is complete" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            result[:joined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            result[:joined_condition].wait(0.5).should be_true
+          end
+
+          it "should return something that can be blocked on until the entities are unjoined" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Unjoined.new(call_uri: uri)
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should unblock all conditions on call end if no joined/unjoined events are received" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            result[:joined_condition].wait(0.5).should be_false
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::End.new
+            result[:joined_condition].wait(0.5).should be_true
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should not error on call end when joined/unjoined events are received correctly" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            subject << Punchblock::Event::Unjoined.new(call_uri: uri)
+
+            subject << Punchblock::Event::End.new
+          end
+
+          it "should not error if multiple joined events are received for the same join" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target, :media => :bridge, :direction => :recv
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+
+            subject.should be_alive
+          end
         end
 
         context "with a call URI as a hash key" do
           let(:call_id) { rand.to_s }
+          let(:uri) { call_id }
           let(:target)  { { :call_uri => call_id } }
 
           it "should send a join command joining to the provided call ID" do
@@ -843,6 +1099,70 @@ module Adhearsion
               subject.join target.merge({:media => :bridge, :direction => :recv})
             end
           end
+
+          it "should return the command" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+            result[:command].should be_a Punchblock::Command::Join
+            result[:command].call_uri.should eql(uri)
+            result[:command].media.should eql(:bridge)
+            result[:command].direction.should eql(:recv)
+          end
+
+          it "should return something that can be blocked on until the join is complete" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            result[:joined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            result[:joined_condition].wait(0.5).should be_true
+          end
+
+          it "should return something that can be blocked on until the entities are unjoined" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Unjoined.new(call_uri: uri)
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should unblock all conditions on call end if no joined/unjoined events are received" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            result[:joined_condition].wait(0.5).should be_false
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::End.new
+            result[:joined_condition].wait(0.5).should be_true
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should not error on call end when joined/unjoined events are received correctly" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            subject << Punchblock::Event::Unjoined.new(call_uri: uri)
+
+            subject << Punchblock::Event::End.new
+          end
+
+          it "should not error if multiple joined events are received for the same join" do
+            expect_join_with_options :call_id => uri, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+            subject << Punchblock::Event::Joined.new(call_uri: uri)
+
+            subject.should be_alive
+          end
         end
 
         context "with a mixer name as a hash key" do
@@ -860,6 +1180,70 @@ module Adhearsion
               subject.join target.merge({:media => :bridge, :direction => :recv})
             end
           end
+
+          it "should return the command" do
+            expect_join_with_options :mixer_name => mixer_name, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+            result[:command].should be_a Punchblock::Command::Join
+            result[:command].mixer_name.should eql(mixer_name)
+            result[:command].media.should eql(:bridge)
+            result[:command].direction.should eql(:recv)
+          end
+
+          it "should return something that can be blocked on until the join is complete" do
+            expect_join_with_options :mixer_name => mixer_name, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            result[:joined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(mixer_name: mixer_name)
+            result[:joined_condition].wait(0.5).should be_true
+          end
+
+          it "should return something that can be blocked on until the entities are unjoined" do
+            expect_join_with_options :mixer_name => mixer_name, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Joined.new(mixer_name: mixer_name)
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::Unjoined.new(mixer_name: mixer_name)
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should unblock all conditions on call end if no joined/unjoined events are received" do
+            expect_join_with_options :mixer_name => mixer_name, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            result[:joined_condition].wait(0.5).should be_false
+            result[:unjoined_condition].wait(0.5).should be_false
+
+            subject << Punchblock::Event::End.new
+            result[:joined_condition].wait(0.5).should be_true
+            result[:unjoined_condition].wait(0.5).should be_true
+          end
+
+          it "should not error on call end when joined/unjoined events are received correctly" do
+            expect_join_with_options :mixer_name => mixer_name, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            subject << Punchblock::Event::Joined.new(mixer_name: mixer_name)
+            subject << Punchblock::Event::Unjoined.new(mixer_name: mixer_name)
+
+            subject << Punchblock::Event::End.new
+          end
+
+          it "should not error if multiple joined events are received for the same join" do
+            expect_join_with_options :mixer_name => mixer_name, :media => :bridge, :direction => :recv
+            result = subject.join target.merge({:media => :bridge, :direction => :recv})
+
+            subject << Punchblock::Event::Joined.new(mixer_name: mixer_name)
+            subject << Punchblock::Event::Joined.new(mixer_name: mixer_name)
+
+            subject.should be_alive
+          end
         end
 
         context "with a call ID and a mixer name as hash keys" do