content/public/test/web_contents_tester.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 CONTENT_PUBLIC_TEST_WEB_CONTENTS_TESTER_H_
   6 #define CONTENT_PUBLIC_TEST_WEB_CONTENTS_TESTER_H_
   7
   8 #include <string>
   9
  10 #include "ui/base/page_transition_types.h"
  11
  12 class GURL;
  13
  14 namespace content {
  15
  16 class BrowserContext;
  17 class RenderFrameHost;
  18 class RenderViewHost;
  19 class SiteInstance;
  20 class WebContents;
  21 struct Referrer;
  22
  23 // This interface allows embedders of content/ to write tests that depend on a
  24 // test version of WebContents.  This interface can be retrieved from any
  25 // WebContents that was retrieved via a call to
  26 // RenderViewHostTestHarness::GetWebContents() (directly or indirectly) or
  27 // constructed explicitly via CreateTestWebContents.
  28 //
  29 // Tests within content/ can directly static_cast WebContents objects retrieved
  30 // or created as described above to TestWebContents.
  31 //
  32 // Design note: We considered two alternatives to this separate test interface
  33 // approach:
  34 //
  35 // a) Define a TestWebContents interface that inherits from WebContents, and
  36 // have the concrete TestWebContents inherit from it as well as from
  37 // WebContentsImpl.  This approach was discarded as it introduces a diamond
  38 // inheritance pattern, which means we wouldn't be e.g. able to downcast from
  39 // WebContents to WebContentsImpl using static_cast.
  40 //
  41 // b) Define a TestWebContents interface that inherits from WebContents, and
  42 // have the concrete TestWebContents implement it, using composition of a
  43 // WebContentsImpl to implement most methods.  This approach was discarded as
  44 // there is a fundamental assumption in content/ that a WebContents* can be
  45 // downcast to a WebContentsImpl*, and this wouldn't be true for TestWebContents
  46 // objects.
  47 class WebContentsTester {
  48  public:
  49   // Retrieves a WebContentsTester to drive tests of the specified WebContents.
  50   // As noted above you need to be sure the 'contents' object supports testing,
  51   // i.e. is either created using one of the Create... functions below, or is
  52   // retrieved via RenderViewHostTestHarness::GetWebContents().
  53   static WebContentsTester* For(WebContents* contents);
  54
  55   // Creates a WebContents enabled for testing.
  56   static WebContents* CreateTestWebContents(
  57       BrowserContext* browser_context,
  58       SiteInstance* instance);
  59
  60   // Simulates the appropriate RenderView (pending if any, current otherwise)
  61   // sending a navigate notification for the NavigationController pending entry.
  62   virtual void CommitPendingNavigation() = 0;
  63
  64   // Gets the pending RenderFrameHost, if any, for the main frame. For the
  65   // current RenderFrameHost of the main frame, use WebContents::GetMainFrame().
  66   // PlzNavigate: When browser side navigation is enabled it returns the
  67   // speculative RenderFrameHost for the main frame if one exists.
  68   virtual RenderFrameHost* GetPendingMainFrame() const = 0;
  69
  70   // Creates a pending navigation to |url|. Also simulates the
  71   // DidStartProvisionalLoad received from the renderer.  To commit the
  72   // navigation, callers should use
  73   // RenderFrameHostTester::SimulateNavigationCommit. Callers can then use
  74   // RenderFrameHostTester::SimulateNavigationStop to simulate the navigation
  75   // stop.
  76   // Note that this function is meant for callers that want to control the
  77   // timing of navigation events precisely. Other callers should use
  78   // NavigateAndCommit.
  79   // PlzNavigate: this does not simulate the DidStartProvisionalLoad from the
  80   // renderer, as it only should be received after the navigation is ready to
  81   // commit.
  82   virtual void StartNavigation(const GURL& url) = 0;
  83
  84   // Creates a pending navigation to the given URL with the default parameters
  85   // and then commits the load with a page ID one larger than any seen. This
  86   // emulates what happens on a new navigation.
  87   virtual void NavigateAndCommit(const GURL& url) = 0;
  88
  89   // Sets the loading state to the given value.
  90   virtual void TestSetIsLoading(bool value) = 0;
  91
  92   // Simulates the current RVH notifying that it has unloaded so that the
  93   // pending RVH navigation can proceed.
  94   // Does nothing if no cross-navigation is pending.
  95   virtual void ProceedWithCrossSiteNavigation() = 0;
  96
  97   // Simulates a navigation with the given information.
  98   //
  99   // Guidance for calling these:
 100   // - nav_entry_id should be 0 if simulating a renderer-initiated navigation;
 101   //   if simulating a browser-initiated one, pass the GetUniqueID() value of
 102   //   the NavigationController's PendingEntry.
 103   // - did_create_new_entry should be true if simulating a navigation that
 104   //   created a new navigation entry; false for history navigations, reloads,
 105   //   and other navigations that don't affect the history list.
 106   virtual void TestDidNavigate(RenderFrameHost* render_frame_host,
 107                                int page_id,
 108                                int nav_entry_id,
 109                                bool did_create_new_entry,
 110                                const GURL& url,
 111                                ui::PageTransition transition) = 0;
 112   virtual void TestDidNavigateWithReferrer(RenderFrameHost* render_frame_host,
 113                                            int page_id,
 114                                            int nav_entry_id,
 115                                            bool did_create_new_entry,
 116                                            const GURL& url,
 117                                            const Referrer& referrer,
 118                                            ui::PageTransition transition) = 0;
 119
 120   // Returns headers that were passed in the previous SaveFrameWithHeaders(...)
 121   // call.
 122   virtual const std::string& GetSaveFrameHeaders() = 0;
 123 };
 124
 125 }  // namespace content
 126
 127 #endif  // CONTENT_PUBLIC_TEST_WEB_CONTENTS_TESTER_H_