1 /* 2 * Copyright 2017 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 #ifndef PC_PEER_CONNECTION_WRAPPER_H_ 12 #define PC_PEER_CONNECTION_WRAPPER_H_ 13 14 #include <memory> 15 #include <string> 16 #include <vector> 17 18 #include "api/data_channel_interface.h" 19 #include "api/function_view.h" 20 #include "api/jsep.h" 21 #include "api/media_stream_interface.h" 22 #include "api/media_types.h" 23 #include "api/peer_connection_interface.h" 24 #include "api/rtc_error.h" 25 #include "api/rtp_sender_interface.h" 26 #include "api/rtp_transceiver_interface.h" 27 #include "api/scoped_refptr.h" 28 #include "api/stats/rtc_stats_report.h" 29 #include "pc/test/mock_peer_connection_observers.h" 30 31 namespace webrtc { 32 33 // Class that wraps a PeerConnection so that it is easier to use in unit tests. 34 // Namely, gives a synchronous API for the event-callback-based API of 35 // PeerConnection and provides an observer object that stores information from 36 // PeerConnectionObserver callbacks. 37 // 38 // This is intended to be subclassed if additional information needs to be 39 // stored with the PeerConnection (e.g., fake PeerConnection parameters so that 40 // tests can be written against those interactions). The base 41 // PeerConnectionWrapper should only have helper methods that are broadly 42 // useful. More specific helper methods should be created in the test-specific 43 // subclass. 44 // 45 // The wrapper is intended to be constructed by specialized factory methods on 46 // a test fixture class then used as a local variable in each test case. 47 class PeerConnectionWrapper { 48 public: 49 // Constructs a PeerConnectionWrapper from the given PeerConnection. 50 // The given PeerConnectionFactory should be the factory that created the 51 // PeerConnection and the MockPeerConnectionObserver should be the observer 52 // that is watching the PeerConnection. 53 PeerConnectionWrapper( 54 rtc::scoped_refptr<PeerConnectionFactoryInterface> pc_factory, 55 rtc::scoped_refptr<PeerConnectionInterface> pc, 56 std::unique_ptr<MockPeerConnectionObserver> observer); 57 virtual ~PeerConnectionWrapper(); 58 59 PeerConnectionFactoryInterface* pc_factory(); 60 PeerConnectionInterface* pc(); 61 MockPeerConnectionObserver* observer(); 62 63 // Calls the underlying PeerConnection's CreateOffer method and returns the 64 // resulting SessionDescription once it is available. If the method call 65 // failed, null is returned. 66 std::unique_ptr<SessionDescriptionInterface> CreateOffer( 67 const PeerConnectionInterface::RTCOfferAnswerOptions& options, 68 std::string* error_out = nullptr); 69 // Calls CreateOffer with default options. 70 std::unique_ptr<SessionDescriptionInterface> CreateOffer(); 71 // Calls CreateOffer and sets a copy of the offer as the local description. 72 std::unique_ptr<SessionDescriptionInterface> CreateOfferAndSetAsLocal( 73 const PeerConnectionInterface::RTCOfferAnswerOptions& options); 74 // Calls CreateOfferAndSetAsLocal with default options. 75 std::unique_ptr<SessionDescriptionInterface> CreateOfferAndSetAsLocal(); 76 77 // Calls the underlying PeerConnection's CreateAnswer method and returns the 78 // resulting SessionDescription once it is available. If the method call 79 // failed, null is returned. 80 std::unique_ptr<SessionDescriptionInterface> CreateAnswer( 81 const PeerConnectionInterface::RTCOfferAnswerOptions& options, 82 std::string* error_out = nullptr); 83 // Calls CreateAnswer with the default options. 84 std::unique_ptr<SessionDescriptionInterface> CreateAnswer(); 85 // Calls CreateAnswer and sets a copy of the offer as the local description. 86 std::unique_ptr<SessionDescriptionInterface> CreateAnswerAndSetAsLocal( 87 const PeerConnectionInterface::RTCOfferAnswerOptions& options); 88 // Calls CreateAnswerAndSetAsLocal with default options. 89 std::unique_ptr<SessionDescriptionInterface> CreateAnswerAndSetAsLocal(); 90 std::unique_ptr<SessionDescriptionInterface> CreateRollback(); 91 92 // Calls the underlying PeerConnection's SetLocalDescription method with the 93 // given session description and waits for the success/failure response. 94 // Returns true if the description was successfully set. 95 bool SetLocalDescription(std::unique_ptr<SessionDescriptionInterface> desc, 96 std::string* error_out = nullptr); 97 // Calls the underlying PeerConnection's SetRemoteDescription method with the 98 // given session description and waits for the success/failure response. 99 // Returns true if the description was successfully set. 100 bool SetRemoteDescription(std::unique_ptr<SessionDescriptionInterface> desc, 101 std::string* error_out = nullptr); 102 bool SetRemoteDescription(std::unique_ptr<SessionDescriptionInterface> desc, 103 RTCError* error_out); 104 105 // Does a round of offer/answer with the local PeerConnectionWrapper 106 // generating the offer and the given PeerConnectionWrapper generating the 107 // answer. 108 // Equivalent to: 109 // 1. this->CreateOffer(offer_options) 110 // 2. this->SetLocalDescription(offer) 111 // 3. answerer->SetRemoteDescription(offer) 112 // 4. answerer->CreateAnswer(answer_options) 113 // 5. answerer->SetLocalDescription(answer) 114 // 6. this->SetRemoteDescription(answer) 115 // Returns true if all steps succeed, false otherwise. 116 // Suggested usage: 117 // ASSERT_TRUE(caller->ExchangeOfferAnswerWith(callee.get())); 118 bool ExchangeOfferAnswerWith(PeerConnectionWrapper* answerer); 119 bool ExchangeOfferAnswerWith( 120 PeerConnectionWrapper* answerer, 121 const PeerConnectionInterface::RTCOfferAnswerOptions& offer_options, 122 const PeerConnectionInterface::RTCOfferAnswerOptions& answer_options); 123 124 // The following are wrappers for the underlying PeerConnection's 125 // AddTransceiver method. They return the result of calling AddTransceiver 126 // with the given arguments, DCHECKing if there is an error. 127 rtc::scoped_refptr<RtpTransceiverInterface> AddTransceiver( 128 cricket::MediaType media_type); 129 rtc::scoped_refptr<RtpTransceiverInterface> AddTransceiver( 130 cricket::MediaType media_type, 131 const RtpTransceiverInit& init); 132 rtc::scoped_refptr<RtpTransceiverInterface> AddTransceiver( 133 rtc::scoped_refptr<MediaStreamTrackInterface> track); 134 rtc::scoped_refptr<RtpTransceiverInterface> AddTransceiver( 135 rtc::scoped_refptr<MediaStreamTrackInterface> track, 136 const RtpTransceiverInit& init); 137 138 // Returns a new dummy audio track with the given label. 139 rtc::scoped_refptr<AudioTrackInterface> CreateAudioTrack( 140 const std::string& label); 141 142 // Returns a new dummy video track with the given label. 143 rtc::scoped_refptr<VideoTrackInterface> CreateVideoTrack( 144 const std::string& label); 145 146 // Wrapper for the underlying PeerConnection's AddTrack method. DCHECKs if 147 // AddTrack fails. 148 rtc::scoped_refptr<RtpSenderInterface> AddTrack( 149 rtc::scoped_refptr<MediaStreamTrackInterface> track, 150 const std::vector<std::string>& stream_ids = {}); 151 152 // Calls the underlying PeerConnection's AddTrack method with an audio media 153 // stream track not bound to any source. 154 rtc::scoped_refptr<RtpSenderInterface> AddAudioTrack( 155 const std::string& track_label, 156 const std::vector<std::string>& stream_ids = {}); 157 158 // Calls the underlying PeerConnection's AddTrack method with a video media 159 // stream track fed by a FakeVideoTrackSource. 160 rtc::scoped_refptr<RtpSenderInterface> AddVideoTrack( 161 const std::string& track_label, 162 const std::vector<std::string>& stream_ids = {}); 163 164 // Calls the underlying PeerConnection's CreateDataChannel method with default 165 // initialization parameters. 166 rtc::scoped_refptr<DataChannelInterface> CreateDataChannel( 167 const std::string& label); 168 169 // Returns the signaling state of the underlying PeerConnection. 170 PeerConnectionInterface::SignalingState signaling_state(); 171 172 // Returns true if ICE has finished gathering candidates. 173 bool IsIceGatheringDone(); 174 175 // Returns true if ICE has established a connection. 176 bool IsIceConnected(); 177 178 // Calls GetStats() on the underlying PeerConnection and returns the resulting 179 // report. If GetStats() fails, this method returns null and fails the test. 180 rtc::scoped_refptr<const RTCStatsReport> GetStats(); 181 182 private: 183 std::unique_ptr<SessionDescriptionInterface> CreateSdp( 184 rtc::FunctionView<void(CreateSessionDescriptionObserver*)> fn, 185 std::string* error_out); 186 bool SetSdp(rtc::FunctionView<void(SetSessionDescriptionObserver*)> fn, 187 std::string* error_out); 188 189 rtc::scoped_refptr<PeerConnectionFactoryInterface> pc_factory_; 190 std::unique_ptr<MockPeerConnectionObserver> observer_; 191 rtc::scoped_refptr<PeerConnectionInterface> pc_; 192 }; 193 194 } // namespace webrtc 195 196 #endif // PC_PEER_CONNECTION_WRAPPER_H_ 197