src/chrome/test/base/in_process_browser_test.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_IN_PROCESS_BROWSER_TEST_H_
   6 #define CHROME_TEST_BASE_IN_PROCESS_BROWSER_TEST_H_
   7
   8 #include "base/compiler_specific.h"
   9 #include "base/files/scoped_temp_dir.h"
  10 #include "base/memory/ref_counted.h"
  11 #include "base/memory/scoped_ptr.h"
  12 #include "content/public/common/page_transition_types.h"
  13 #include "content/public/test/browser_test.h"
  14 #include "content/public/test/browser_test_base.h"
  15 #include "testing/gtest/include/gtest/gtest.h"
  16
  17 namespace base {
  18 #if defined(OS_MACOSX)
  19 namespace mac {
  20 class ScopedNSAutoreleasePool;
  21 }  // namespace mac
  22 #endif  // defined(OS_MACOSX)
  23
  24 #if defined(OS_WIN)
  25 namespace win {
  26 class ScopedCOMInitializer;
  27 }
  28 #endif  // defined(OS_WIN)
  29 }  // namespace base
  30
  31 class Browser;
  32 class CommandLine;
  33 class Profile;
  34
  35 namespace content {
  36 class ContentRendererClient;
  37 }
  38
  39 // Base class for tests wanting to bring up a browser in the unit test process.
  40 // Writing tests with InProcessBrowserTest is slightly different than that of
  41 // other tests. This is necessitated by InProcessBrowserTest running a message
  42 // loop. To use InProcessBrowserTest do the following:
  43 // . Use the macro IN_PROC_BROWSER_TEST_F to define your test.
  44 // . Your test method is invoked on the ui thread. If you need to block until
  45 //   state changes you'll need to run the message loop from your test method.
  46 //   For example, if you need to wait till a find bar has completely been shown
  47 //   you'll need to invoke content::RunMessageLoop. When the message bar is
  48 //   shown, invoke MessageLoop::current()->Quit() to return control back to your
  49 //   test method.
  50 // . If you subclass and override SetUp, be sure and invoke
  51 //   InProcessBrowserTest::SetUp. (But see also SetUpOnMainThread,
  52 //   SetUpInProcessBrowserTestFixture and other related hook methods for a
  53 //   cleaner alternative).
  54 //
  55 // Following three hook methods are called in sequence before calling
  56 // BrowserMain(), thus no browser has been created yet. They are mainly for
  57 // setting up the environment for running the browser.
  58 // . SetUpUserDataDirectory()
  59 // . SetUpCommandLine()
  60 // . SetUpInProcessBrowserTestFixture()
  61 //
  62 // SetUpOnMainThread() is called just after creating the default browser object
  63 // and before executing the real test code. It's mainly for setting up things
  64 // related to the browser object and associated window, like opening a new Tab
  65 // with a testing page loaded.
  66 //
  67 // CleanUpOnMainThread() is called just after executing the real test code to
  68 // do necessary cleanup before the browser is torn down.
  69 //
  70 // TearDownInProcessBrowserTestFixture() is called after BrowserMain() exits to
  71 // cleanup things setup for running the browser.
  72 //
  73 // By default InProcessBrowserTest creates a single Browser (as returned from
  74 // the CreateBrowser method). You can obviously create more as needed.
  75
  76 // InProcessBrowserTest disables the sandbox when running.
  77 //
  78 // See ui_test_utils for a handful of methods designed for use with this class.
  79 //
  80 // It's possible to write browser tests that span a restart by splitting each
  81 // run of the browser process into a separate test. Example:
  82 //
  83 // IN_PROC_BROWSER_TEST_F(Foo, PRE_Bar) {
  84 //   do something
  85 // }
  86 //
  87 // IN_PROC_BROWSER_TEST_F(Foo, Bar) {
  88 //   verify something persisted from before
  89 // }
  90 //
  91 //  This is recursive, so PRE_PRE_Bar would run before PRE_BAR.
  92 class InProcessBrowserTest : public content::BrowserTestBase {
  93  public:
  94   InProcessBrowserTest();
  95   virtual ~InProcessBrowserTest();
  96
  97   // Configures everything for an in process browser test, then invokes
  98   // BrowserMain. BrowserMain ends up invoking RunTestOnMainThreadLoop.
  99   virtual void SetUp() OVERRIDE;
 100
 101   // Restores state configured in SetUp.
 102   virtual void TearDown() OVERRIDE;
 103
 104  protected:
 105   // Returns the browser created by CreateBrowser.
 106   Browser* browser() const { return browser_; }
 107
 108   // Convenience methods for adding tabs to a Browser.
 109   void AddTabAtIndexToBrowser(Browser* browser,
 110                               int index,
 111                               const GURL& url,
 112                               content::PageTransition transition);
 113   void AddTabAtIndex(int index, const GURL& url,
 114                      content::PageTransition transition);
 115
 116   // Initializes the contents of the user data directory. Called by SetUp()
 117   // after creating the user data directory, but before any browser is launched.
 118   // If a test wishes to set up some initial non-empty state in the user data
 119   // directory before the browser starts up, it can do so here. Returns true if
 120   // successful.
 121   virtual bool SetUpUserDataDirectory() WARN_UNUSED_RESULT;
 122
 123   // Override this to add any custom cleanup code that needs to be done on the
 124   // main thread before the browser is torn down.
 125   virtual void CleanUpOnMainThread() {}
 126
 127   // BrowserTestBase:
 128   virtual void RunTestOnMainThreadLoop() OVERRIDE;
 129
 130   // Creates a browser with a single tab (about:blank), waits for the tab to
 131   // finish loading and shows the browser.
 132   //
 133   // This is invoked from Setup.
 134   Browser* CreateBrowser(Profile* profile);
 135
 136   // Similar to |CreateBrowser|, but creates an incognito browser.
 137   Browser* CreateIncognitoBrowser();
 138
 139   // Creates a browser for a popup window with a single tab (about:blank), waits
 140   // for the tab to finish loading, and shows the browser.
 141   Browser* CreateBrowserForPopup(Profile* profile);
 142
 143   // Creates a browser for an application and waits for it to load and shows
 144   // the browser.
 145   Browser* CreateBrowserForApp(const std::string& app_name, Profile* profile);
 146
 147   // Called from the various CreateBrowser methods to add a blank tab, wait for
 148   // the navigation to complete, and show the browser's window.
 149   void AddBlankTabAndShow(Browser* browser);
 150
 151 #if !defined OS_MACOSX
 152   // Return a CommandLine object that is used to relaunch the browser_test
 153   // binary as a browser process. This function is deliberately not defined on
 154   // the Mac because re-using an existing browser process when launching from
 155   // the command line isn't a concept that we support on the Mac; AppleEvents
 156   // are the Mac solution for the same need. Any test based on these functions
 157   // doesn't apply to the Mac.
 158   CommandLine GetCommandLineForRelaunch();
 159 #endif
 160
 161 #if defined(OS_MACOSX)
 162   // Returns the autorelease pool in use inside RunTestOnMainThreadLoop().
 163   base::mac::ScopedNSAutoreleasePool* AutoreleasePool() const {
 164     return autorelease_pool_;
 165   }
 166 #endif  // OS_MACOSX
 167
 168   void set_exit_when_last_browser_closes(bool value) {
 169     exit_when_last_browser_closes_ = value;
 170   }
 171
 172   // This must be called before RunTestOnMainThreadLoop() to have any effect.
 173   void set_multi_desktop_test(bool multi_desktop_test) {
 174     multi_desktop_test_ = multi_desktop_test;
 175   }
 176
 177  private:
 178   // Creates a user data directory for the test if one is needed. Returns true
 179   // if successful.
 180   virtual bool CreateUserDataDirectory() WARN_UNUSED_RESULT;
 181
 182   // Quits all open browsers and waits until there are no more browsers.
 183   void QuitBrowsers();
 184
 185   // Prepare command line that will be used to launch the child browser process
 186   // with an in-process test.
 187   void PrepareTestCommandLine(CommandLine* command_line);
 188
 189   // Browser created from CreateBrowser.
 190   Browser* browser_;
 191
 192   // Temporary user data directory. Used only when a user data directory is not
 193   // specified in the command line.
 194   base::ScopedTempDir temp_user_data_dir_;
 195
 196   // True if we should exit the tests after the last browser instance closes.
 197   bool exit_when_last_browser_closes_;
 198
 199   // True if this is a multi-desktop test (in which case this browser test will
 200   // not ensure that Browsers are only created on the tested desktop).
 201   bool multi_desktop_test_;
 202
 203 #if defined(OS_MACOSX)
 204   base::mac::ScopedNSAutoreleasePool* autorelease_pool_;
 205 #endif  // OS_MACOSX
 206
 207 #if defined(OS_WIN)
 208   scoped_ptr<base::win::ScopedCOMInitializer> com_initializer_;
 209 #endif
 210 };
 211
 212 #endif  // CHROME_TEST_BASE_IN_PROCESS_BROWSER_TEST_H_