src/chrome/test/base/web_ui_browsertest.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_TEST_BASE_WEB_UI_BROWSERTEST_H_
   6 #define CHROME_TEST_BASE_WEB_UI_BROWSERTEST_H_
   7
   8 #include <string>
   9 #include <vector>
  10
  11 #include "base/files/file_path.h"
  12 #include "base/memory/scoped_vector.h"
  13 #include "base/strings/string16.h"
  14 #include "chrome/test/base/in_process_browser_test.h"
  15
  16 namespace base {
  17 class Value;
  18 }
  19
  20 namespace content {
  21 class RenderViewHost;
  22 class WebUI;
  23 class WebUIMessageHandler;
  24 }
  25
  26 class TestChromeWebUIControllerFactory;
  27 class WebUITestHandler;
  28
  29 // This macro simplifies the declaration of simple javascript unit tests.
  30 // Use:
  31 //   WEB_UI_UNITTEST_F(MyWebUIPageTest, myJavascriptUnittest);
  32 #define WEB_UI_UNITTEST_F(x, y) \
  33   IN_PROC_BROWSER_TEST_F(x, y) { \
  34     ASSERT_TRUE(RunJavascriptTest(#y)); \
  35   }
  36
  37 // The runner of WebUI javascript based tests.
  38 // See chrome/test/data/webui/test_api.js for the javascript side test API's.
  39 //
  40 // These tests should follow the form given in:
  41 // chrome/test/data/webui/sample_downloads.js.
  42 // and the lone test within this class.
  43 class WebUIBrowserTest : public InProcessBrowserTest {
  44  public:
  45   typedef ScopedVector<const base::Value> ConstValueVector;
  46   virtual ~WebUIBrowserTest();
  47
  48   // Add a custom helper JS library for your test.
  49   // If a relative path is specified, it'll be read
  50   // as relative to the test data dir.
  51   void AddLibrary(const base::FilePath& library_path);
  52
  53   // Runs a javascript function in the context of all libraries.
  54   // Note that calls to functions in test_api.js are not supported.
  55   // Takes ownership of Value* arguments.
  56   bool RunJavascriptFunction(const std::string& function_name);
  57   bool RunJavascriptFunction(const std::string& function_name,
  58                              base::Value* arg);
  59   bool RunJavascriptFunction(const std::string& function_name,
  60                              base::Value* arg1,
  61                              base::Value* arg2);
  62   bool RunJavascriptFunction(const std::string& function_name,
  63                              const ConstValueVector& function_arguments);
  64
  65   // Runs a test fixture that may include calls to functions in test_api.js.
  66   bool RunJavascriptTestF(bool is_async,
  67                           const std::string& test_fixture,
  68                           const std::string& test_name);
  69
  70   // Runs a test that may include calls to functions in test_api.js.
  71   // Takes ownership of Value* arguments.
  72   bool RunJavascriptTest(const std::string& test_name);
  73   bool RunJavascriptTest(const std::string& test_name,
  74                          base::Value* arg);
  75   bool RunJavascriptTest(const std::string& test_name,
  76                          base::Value* arg1,
  77                          base::Value* arg2);
  78   bool RunJavascriptTest(const std::string& test_name,
  79                          const ConstValueVector& test_arguments);
  80
  81   // Runs a test that may include calls to functions in test_api.js, and waits
  82   // for call to testDone().  Takes ownership of Value* arguments.
  83   bool RunJavascriptAsyncTest(const std::string& test_name);
  84   bool RunJavascriptAsyncTest(const std::string& test_name,
  85                               base::Value* arg);
  86   bool RunJavascriptAsyncTest(const std::string& test_name,
  87                               base::Value* arg1,
  88                               base::Value* arg2);
  89   bool RunJavascriptAsyncTest(const std::string& test_name,
  90                               base::Value* arg1,
  91                               base::Value* arg2,
  92                               base::Value* arg3);
  93   bool RunJavascriptAsyncTest(const std::string& test_name,
  94                               const ConstValueVector& test_arguments);
  95
  96   // Sends message through |preload_host| to preload javascript libraries and
  97   // sets the |libraries_preloaded| flag to prevent re-loading at next
  98   // javascript invocation.
  99   void PreLoadJavascriptLibraries(const std::string& preload_test_fixture,
 100                                   const std::string& preload_test_name,
 101                                   content::RenderViewHost* preload_host);
 102
 103   // Called by javascript-generated test bodies to browse to a page and preload
 104   // the javascript for the given |preload_test_fixture| and
 105   // |preload_test_name|. chrome.send will be overridden to allow javascript
 106   // handler mocking.
 107   void BrowsePreload(const GURL& browse_to);
 108
 109   // Called by javascript-generated test bodies to browse to a page and preload
 110   // the javascript for the given |preload_test_fixture| and
 111   // |preload_test_name|. chrome.send will be overridden to allow javascript
 112   // handler mocking.
 113   void BrowsePrintPreload(const GURL& browse_to);
 114
 115  protected:
 116   // URL to dummy WebUI page for testing framework.
 117   static const char kDummyURL[];
 118
 119   WebUIBrowserTest();
 120
 121   // Accessors for preload test fixture and name.
 122   void set_preload_test_fixture(const std::string& preload_test_fixture);
 123   void set_preload_test_name(const std::string& preload_test_name);
 124
 125   // Set up & tear down console error catching.
 126   virtual void SetUpOnMainThread() OVERRIDE;
 127   virtual void CleanUpOnMainThread() OVERRIDE;
 128
 129   // Set a WebUI instance to run tests on.
 130   void SetWebUIInstance(content::WebUI* web_ui);
 131
 132   // Returns a mock WebUI object under test (if any).
 133   virtual content::WebUIMessageHandler* GetMockMessageHandler();
 134
 135   // Returns a file:// GURL constructed from |path| inside the test data dir for
 136   // webui tests.
 137   static GURL WebUITestDataPathToURL(const base::FilePath::StringType& path);
 138
 139  private:
 140   // Builds a string containing all added javascript libraries.
 141   void BuildJavascriptLibraries(string16* content);
 142
 143   // Builds a string with a call to the runTest JS function, passing the
 144   // given |is_async|, |test_name| and its |args|.
 145   string16 BuildRunTestJSCall(bool is_async,
 146                               const std::string& test_name,
 147                               const WebUIBrowserTest::ConstValueVector& args);
 148
 149   // Loads all libraries added with AddLibrary(), and calls |function_name| with
 150   // |function_arguments|. When |is_test| is true, the framework wraps
 151   // |function_name| with a test helper function, which waits for completion,
 152   // logging an error message on failure, otherwise |function_name| is called
 153   // asynchronously. When |preload_host| is non-NULL, sends the javascript to
 154   // the RenderView for evaluation at the appropriate time before the onload
 155   // call is made. Passes |is_async| along to runTest wrapper.
 156   bool RunJavascriptUsingHandler(const std::string& function_name,
 157                                  const ConstValueVector& function_arguments,
 158                                  bool is_test,
 159                                  bool is_async,
 160                                  content::RenderViewHost* preload_host);
 161
 162   // Attaches mock and test handlers.
 163   void SetupHandlers();
 164
 165   // Handles test framework messages.
 166   scoped_ptr<WebUITestHandler> test_handler_;
 167
 168   // Location of test data (currently test/data/webui).
 169   base::FilePath test_data_directory_;
 170
 171   // Location of generated test data (<(PROGRAM_DIR)/test_data).
 172   base::FilePath gen_test_data_directory_;
 173
 174   // User added libraries
 175   std::vector<base::FilePath> user_libraries_;
 176
 177   // Indicates that the libraries have been pre-loaded and to not load them
 178   // again.
 179   bool libraries_preloaded_;
 180
 181   // Saves the states of |test_fixture| and |test_name| for calling
 182   // PreloadJavascriptLibraries().
 183   std::string preload_test_fixture_;
 184   std::string preload_test_name_;
 185
 186   // When this is non-NULL, this is The WebUI instance used for testing.
 187   // Otherwise the selected tab's web_ui is used.
 188   content::WebUI* override_selected_web_ui_;
 189
 190   scoped_ptr<TestChromeWebUIControllerFactory> test_factory_;
 191 };
 192
 193 #endif  // CHROME_TEST_BASE_WEB_UI_BROWSERTEST_H_