Home | History | Annotate | Download | only in tests 
      1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
      2 // Use of this source code is governed by a BSD-style license that can be
      3 // found in the LICENSE file.
      4 
      5 #ifndef PPAPI_TESTS_TEST_UTILS_H_
      6 #define PPAPI_TESTS_TEST_UTILS_H_
      7 
      8 #include <string>
      9 
     10 #include "ppapi/c/pp_instance.h"
     11 #include "ppapi/c/pp_stdint.h"
     12 #include "ppapi/c/private/ppb_testing_private.h"
     13 #include "ppapi/cpp/completion_callback.h"
     14 #include "ppapi/cpp/message_loop.h"
     15 #include "ppapi/utility/completion_callback_factory.h"
     16 
     17 namespace pp {
     18 class NetAddress;
     19 }
     20 
     21 // Timeout to wait for some action to complete.
     22 extern const int kActionTimeoutMs;
     23 
     24 const PPB_Testing_Private* GetTestingInterface();
     25 std::string ReportError(const char* method, int32_t error);
     26 void PlatformSleep(int duration_ms);
     27 bool GetLocalHostPort(PP_Instance instance, std::string* host, uint16_t* port);
     28 
     29 uint16_t ConvertFromNetEndian16(uint16_t x);
     30 uint16_t ConvertToNetEndian16(uint16_t x);
     31 bool EqualNetAddress(const pp::NetAddress& addr1, const pp::NetAddress& addr2);
     32 // Only returns the first address if there are more than one available.
     33 bool ResolveHost(PP_Instance instance,
     34                  const std::string& host,
     35                  uint16_t port,
     36                  pp::NetAddress* addr);
     37 bool ReplacePort(PP_Instance instance,
     38                  const pp::NetAddress& input_addr,
     39                  uint16_t port,
     40                  pp::NetAddress* output_addr);
     41 uint16_t GetPort(const pp::NetAddress& addr);
     42 
     43 // NestedEvent allows you to run a nested MessageLoop and wait for a particular
     44 // event to complete. For example, you can use it to wait for a callback on a
     45 // PPP interface, which will "Signal" the event and make the loop quit.
     46 // "Wait()" will return immediately if it has already been signalled. Otherwise,
     47 // it will run a nested message loop (using PPB_Testing.RunMessageLoop) and will
     48 // return only after it has been signalled.
     49 // Example:
     50 //  std::string TestFullscreen::TestNormalToFullscreen() {
     51 //    pp::Fullscreen screen_mode(instance);
     52 //    screen_mode.SetFullscreen(true);
     53 //    SimulateUserGesture();
     54 //    // Let DidChangeView run in a nested message loop.
     55 //    nested_event_.Wait();
     56 //    Pass();
     57 //  }
     58 //
     59 //  void TestFullscreen::DidChangeView(const pp::View& view) {
     60 //    nested_event_.Signal();
     61 //  }
     62 //
     63 // All methods except Signal and PostSignal must be invoked on the main thread.
     64 // It's OK to signal from a background thread, so you can (for example) Signal()
     65 // from the Audio thread.
     66 class NestedEvent {
     67  public:
     68   explicit NestedEvent(PP_Instance instance)
     69       : instance_(instance), waiting_(false), signalled_(false) {
     70   }
     71   // Run a nested message loop and wait until Signal() is called. If Signal()
     72   // has already been called, return immediately without running a nested loop.
     73   void Wait();
     74   // Signal the NestedEvent. If Wait() has been called, quit the message loop.
     75   // This can be called from any thread.
     76   void Signal();
     77   // Signal the NestedEvent in |wait_ms| milliseconds. This can be called from
     78   // any thread.
     79   void PostSignal(int32_t wait_ms);
     80 
     81   // Reset the NestedEvent so it can be used again.
     82   void Reset();
     83  private:
     84   void SignalOnMainThread();
     85   static void SignalThunk(void* async_event, int32_t result);
     86 
     87   PP_Instance instance_;
     88   bool waiting_;
     89   bool signalled_;
     90   // Disable copy and assign.
     91   NestedEvent(const NestedEvent&);
     92   NestedEvent& operator=(const NestedEvent&);
     93 };
     94 
     95 enum CallbackType { PP_REQUIRED, PP_OPTIONAL, PP_BLOCKING };
     96 class TestCompletionCallback {
     97  public:
     98   class Delegate {
     99    public:
    100     virtual ~Delegate() {}
    101     virtual void OnCallback(void* user_data, int32_t result) = 0;
    102   };
    103   explicit TestCompletionCallback(PP_Instance instance);
    104   // TODO(dmichael): Remove this constructor.
    105   TestCompletionCallback(PP_Instance instance, bool force_async);
    106 
    107   TestCompletionCallback(PP_Instance instance, CallbackType callback_type);
    108 
    109   // Sets a Delegate instance. OnCallback() of this instance will be invoked
    110   // when the completion callback is invoked.
    111   // The delegate will be reset when Reset() or GetCallback() is called.
    112   void SetDelegate(Delegate* delegate) { delegate_ = delegate; }
    113 
    114   // Wait for a result, given the return from the call which took this callback
    115   // as a parameter. If |result| is PP_OK_COMPLETIONPENDING, WaitForResult will
    116   // block until its callback has been invoked (in some cases, this will already
    117   // have happened, and WaitForCallback can return immediately).
    118   // For any other values, WaitForResult will simply set its internal "result_"
    119   // field. To retrieve the final result of the operation (i.e., the result
    120   // the callback has run, if necessary), call result(). You can call result()
    121   // as many times as necessary until a new pp::CompletionCallback is retrieved.
    122   //
    123   // In some cases, you may want to check that the callback was invoked in the
    124   // expected way (i.e., if the callback was "Required", then it should be
    125   // invoked asynchronously). Within the body of a test (where returning a non-
    126   // empty string indicates test failure), you can use the
    127   // CHECK_CALLBACK_BEHAVIOR(callback) macro. From within a helper function,
    128   // you can use failed() and errors().
    129   //
    130   // Example usage within a test:
    131   //  callback.WaitForResult(foo.DoSomething(callback));
    132   //  CHECK_CALLBACK_BEHAVIOR(callback);
    133   //  ASSERT_EQ(PP_OK, callback.result());
    134   //
    135   // Example usage within a helper function:
    136   //  void HelperFunction(std::string* error_message) {
    137   //    callback.WaitForResult(foo.DoSomething(callback));
    138   //    if (callback.failed())
    139   //      error_message->assign(callback.errors());
    140   //  }
    141   void WaitForResult(int32_t result);
    142 
    143   // Used when you expect to receive either synchronous completion with PP_OK
    144   // or a PP_ERROR_ABORTED asynchronously.
    145   //  Example usage:
    146   //  int32_t result = 0;
    147   //  {
    148   //    pp::URLLoader temp(instance_);
    149   //    result = temp.Open(request, callback);
    150   //  }
    151   //  callback.WaitForAbortResult(result);
    152   //  CHECK_CALLBACK_BEHAVIOR(callback);
    153   void WaitForAbortResult(int32_t result);
    154 
    155   // Retrieve a pp::CompletionCallback for use in testing. This Reset()s the
    156   // TestCompletionCallback.
    157   pp::CompletionCallback GetCallback();
    158 
    159   bool failed() { return !errors_.empty(); }
    160   const std::string& errors() { return errors_; }
    161 
    162   int32_t result() const { return result_; }
    163 
    164   // Reset so that this callback can be used again.
    165   void Reset();
    166 
    167   CallbackType callback_type() { return callback_type_; }
    168   void set_target_loop(const pp::MessageLoop& loop) { target_loop_ = loop; }
    169   static void Handler(void* user_data, int32_t result);
    170 
    171  protected:
    172   void RunMessageLoop();
    173   void QuitMessageLoop();
    174 
    175   // Used to check that WaitForResult is only called once for each usage of the
    176   // callback.
    177   bool wait_for_result_called_;
    178   // Indicates whether we have already been invoked.
    179   bool have_result_;
    180   // The last result received (or PP_OK_COMPLETIONCALLBACK if none).
    181   int32_t result_;
    182   CallbackType callback_type_;
    183   bool post_quit_task_;
    184   std::string errors_;
    185   PP_Instance instance_;
    186   Delegate* delegate_;
    187   pp::MessageLoop target_loop_;
    188 };
    189 
    190 namespace internal {
    191 
    192 template <typename OutputT, typename CallbackT>
    193 class TestCompletionCallbackWithOutputBase {
    194  public:
    195   explicit TestCompletionCallbackWithOutputBase(PP_Instance instance)
    196       : callback_(instance),
    197         output_storage_() {
    198     CallbackT::TraitsType::Initialize(&output_storage_);
    199   }
    200 
    201   TestCompletionCallbackWithOutputBase(PP_Instance instance, bool force_async)
    202       : callback_(instance, force_async),
    203         output_storage_() {
    204     CallbackT::TraitsType::Initialize(&output_storage_);
    205   }
    206 
    207   TestCompletionCallbackWithOutputBase(PP_Instance instance,
    208                                        CallbackType callback_type)
    209       : callback_(instance, callback_type),
    210         output_storage_() {
    211     CallbackT::TraitsType::Initialize(&output_storage_);
    212   }
    213 
    214   CallbackT GetCallback();
    215   OutputT output() {
    216     return CallbackT::TraitsType::StorageToPluginArg(
    217         output_storage_);
    218   }
    219 
    220   // Delegate functions to TestCompletionCallback
    221   void SetDelegate(TestCompletionCallback::Delegate* delegate) {
    222     callback_.SetDelegate(delegate);
    223   }
    224   void WaitForResult(int32_t result) { callback_.WaitForResult(result); }
    225   void WaitForAbortResult(int32_t result) {
    226     callback_.WaitForAbortResult(result);
    227   }
    228   bool failed() { return callback_.failed(); }
    229   const std::string& errors() { return callback_.errors(); }
    230   int32_t result() const { return callback_.result(); }
    231   void Reset() {
    232     CallbackT::TraitsType::Initialize(&output_storage_);
    233     return callback_.Reset();
    234   }
    235 
    236  private:
    237   TestCompletionCallback callback_;
    238   typename CallbackT::OutputStorageType output_storage_;
    239 };
    240 
    241 template <typename OutputT, typename CallbackT>
    242 CallbackT
    243 TestCompletionCallbackWithOutputBase<OutputT, CallbackT>::GetCallback() {
    244   this->Reset();
    245   if (callback_.callback_type() == PP_BLOCKING) {
    246     CallbackT cc(&output_storage_);
    247     return cc;
    248   }
    249 
    250   callback_.set_target_loop(pp::MessageLoop::GetCurrent());
    251   CallbackT cc(&TestCompletionCallback::Handler, this, &output_storage_);
    252   if (callback_.callback_type() == PP_OPTIONAL)
    253     cc.set_flags(PP_COMPLETIONCALLBACK_FLAG_OPTIONAL);
    254   return cc;
    255 }
    256 
    257 }  // namespace internal
    258 
    259 template <typename OutputT>
    260 class TestCompletionCallbackWithOutput
    261     : public internal::TestCompletionCallbackWithOutputBase<
    262         OutputT, pp::CompletionCallbackWithOutput<OutputT> > {
    263  public:
    264   explicit TestCompletionCallbackWithOutput(PP_Instance instance)
    265       : BaseType(instance) {
    266   }
    267 
    268   TestCompletionCallbackWithOutput(PP_Instance instance, bool force_async)
    269       : BaseType(instance, force_async) {
    270   }
    271 
    272   TestCompletionCallbackWithOutput(PP_Instance instance,
    273                                    CallbackType callback_type)
    274       : BaseType(instance, callback_type) {
    275   }
    276 
    277  private:
    278   typedef internal::TestCompletionCallbackWithOutputBase<
    279       OutputT, pp::CompletionCallbackWithOutput<OutputT> > BaseType;
    280 };
    281 
    282 template <typename OutputT>
    283 class TestExtCompletionCallbackWithOutput
    284     : public internal::TestCompletionCallbackWithOutputBase<
    285         OutputT, pp::ext::ExtCompletionCallbackWithOutput<OutputT> > {
    286  public:
    287   explicit TestExtCompletionCallbackWithOutput(PP_Instance instance)
    288       : BaseType(instance) {
    289   }
    290 
    291   TestExtCompletionCallbackWithOutput(PP_Instance instance, bool force_async)
    292       : BaseType(instance, force_async) {
    293   }
    294 
    295   TestExtCompletionCallbackWithOutput(PP_Instance instance,
    296                                       CallbackType callback_type)
    297       : BaseType(instance, callback_type) {
    298   }
    299 
    300  private:
    301   typedef internal::TestCompletionCallbackWithOutputBase<
    302       OutputT, pp::ext::ExtCompletionCallbackWithOutput<OutputT> > BaseType;
    303 };
    304 
    305 // Verifies that the callback didn't record any errors. If the callback is run
    306 // in an unexpected way (e.g., if it's invoked asynchronously when the call
    307 // should have blocked), this returns an appropriate error string.
    308 #define CHECK_CALLBACK_BEHAVIOR(callback) \
    309 do { \
    310   if ((callback).failed()) \
    311     return MakeFailureMessage(__FILE__, __LINE__, \
    312                               (callback).errors().c_str()); \
    313 } while (false)
    314 
    315 /*
    316  * A set of macros to use for platform detection. These were largely copied
    317  * from chromium's build_config.h.
    318  */
    319 #if defined(__APPLE__)
    320 #define PPAPI_OS_MACOSX 1
    321 #elif defined(ANDROID)
    322 #define PPAPI_OS_ANDROID 1
    323 #elif defined(__native_client__)
    324 #define PPAPI_OS_NACL 1
    325 #elif defined(__linux__)
    326 #define PPAPI_OS_LINUX 1
    327 #elif defined(_WIN32)
    328 #define PPAPI_OS_WIN 1
    329 #elif defined(__FreeBSD__)
    330 #define PPAPI_OS_FREEBSD 1
    331 #elif defined(__OpenBSD__)
    332 #define PPAPI_OS_OPENBSD 1
    333 #elif defined(__sun)
    334 #define PPAPI_OS_SOLARIS 1
    335 #else
    336 #error Please add support for your platform in ppapi/tests/test_utils.h
    337 #endif
    338 
    339 /* These are used to determine POSIX-like implementations vs Windows. */
    340 #if defined(__linux__) || defined(__APPLE__) || defined(__FreeBSD__) || \
    341     defined(__OpenBSD__) || defined(__sun) || defined(__native_client__)
    342 #define PPAPI_POSIX 1
    343 #endif
    344 
    345 #endif  // PPAPI_TESTS_TEST_UTILS_H_
    346