src/chrome/browser/extensions/extension_test_message_listener.h

   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 CHROME_BROWSER_EXTENSIONS_EXTENSION_TEST_MESSAGE_LISTENER_H_
   6 #define CHROME_BROWSER_EXTENSIONS_EXTENSION_TEST_MESSAGE_LISTENER_H_
   7
   8 #include <string>
   9
  10 #include "base/compiler_specific.h"
  11 #include "content/public/browser/notification_observer.h"
  12 #include "content/public/browser/notification_registrar.h"
  13
  14 namespace extensions {
  15 class TestSendMessageFunction;
  16 }
  17
  18 // This class helps us wait for incoming messages sent from javascript via
  19 // chrome.test.sendMessage(). A sample usage would be:
  20 //
  21 //   ExtensionTestMessageListener listener("foo");
  22 //   ... do some work
  23 //   ASSERT_TRUE(listener.WaitUntilSatisfied());
  24 //
  25 // It is also possible to have the extension wait for our reply. This is
  26 // useful for coordinating multiple pages/processes and having them wait on
  27 // each other. Example:
  28 //
  29 //   ExtensionTestMessageListener listener1("foo1");
  30 //   ExtensionTestMessageListener listener2("foo2");
  31 //   ASSERT_TRUE(listener1.WaitUntilSatisfied());
  32 //   ASSERT_TRUE(listener2.WaitUntilSatisfied());
  33 //   ... do some work
  34 //   listener1.Reply("foo2 is ready");
  35 //   listener2.Reply("foo1 is ready");
  36 //
  37 // TODO(asargent) - In the future we may want to add the ability to listen for
  38 // multiple messages, and/or to wait for "any" message and then retrieve the
  39 // contents of that message. We may also want to specify an extension id as
  40 // satisfaction criteria in addition to message content.
  41 //
  42 // Note that when using it in browser tests, you need to make sure it gets
  43 // destructed *before* the browser gets torn down. Two common patterns are to
  44 // either make it a local variable inside your test body, or if it's a member
  45 // variable of a ExtensionBrowserTest subclass, override the
  46 // InProcessBrowserTest::CleanUpOnMainThread() method and clean it up there.
  47 class ExtensionTestMessageListener : public content::NotificationObserver {
  48  public:
  49   // We immediately start listening for |expected_message|.
  50   ExtensionTestMessageListener(const std::string& expected_message,
  51                                bool will_reply);
  52   virtual ~ExtensionTestMessageListener();
  53
  54   void AlsoListenForFailureMessage(const std::string& failure_message) {
  55     failure_message_ = failure_message;
  56   }
  57
  58   // This returns true immediately if we've already gotten the expected
  59   // message, or waits until it arrives. Returns false if the wait is
  60   // interrupted and we still haven't gotten the message.
  61   bool WaitUntilSatisfied();
  62
  63   // Send the given message as a reply. It is only valid to call this after
  64   // WaitUntilSatisfied has returned true, and if will_reply is true.
  65   void Reply(const std::string& message);
  66
  67   // Convenience method that formats int as a string and sends it.
  68   void Reply(int message);
  69
  70   // Implements the content::NotificationObserver interface.
  71   virtual void Observe(int type,
  72                        const content::NotificationSource& source,
  73                        const content::NotificationDetails& details) OVERRIDE;
  74
  75   bool was_satisfied() const { return satisfied_; }
  76
  77  private:
  78   content::NotificationRegistrar registrar_;
  79
  80   // The message we're expecting.
  81   std::string expected_message_;
  82
  83   // Whether we've seen expected_message_ yet.
  84   bool satisfied_;
  85
  86   // If we're waiting, then we want to post a quit task when the expected
  87   // message arrives.
  88   bool waiting_;
  89
  90   // If true, we expect the calling code to manually send a reply. Otherwise,
  91   // we send an automatic empty reply to the extension.
  92   bool will_reply_;
  93
  94   // The message that signals failure.
  95   std::string failure_message_;
  96
  97   // If we received a message that was the failure message.
  98   bool failed_;
  99
 100   // The function we need to reply to.
 101   extensions::TestSendMessageFunction* function_;
 102 };
 103
 104 #endif  // CHROME_BROWSER_EXTENSIONS_EXTENSION_TEST_MESSAGE_LISTENER_H_