Source/WebDriver/Session.h

   1 /*
   2  * Copyright (C) 2017 Igalia S.L.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   7  * 1. Redistributions of source code must retain the above copyright
   8  *    notice, this list of conditions and the following disclaimer.
   9  * 2. Redistributions in binary form must reproduce the above copyright
  10  *    notice, this list of conditions and the following disclaimer in the
  11  *    documentation and/or other materials provided with the distribution.
  12  *
  13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
  14  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  15  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  16  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
  17  * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  18  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  19  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  20  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  21  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  22  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  23  * THE POSSIBILITY OF SUCH DAMAGE.
  24  */
  25
  26 #pragma once
  27
  28 #include "Capabilities.h"
  29 #include <wtf/Forward.h>
  30 #include <wtf/Function.h>
  31 #include <wtf/JSONValues.h>
  32 #include <wtf/OptionSet.h>
  33 #include <wtf/RefCounted.h>
  34 #include <wtf/text/WTFString.h>
  35
  36 namespace WebDriver {
  37
  38 class CommandResult;
  39 class SessionHost;
  40
  41 class Session : public RefCounted<Session> {
  42 public:
  43     static Ref<Session> create(std::unique_ptr<SessionHost>&& host)
  44     {
  45         return adoptRef(*new Session(WTFMove(host)));
  46     }
  47     ~Session();
  48
  49     const String& id() const { return m_id; }
  50     const Capabilities& capabilities() const;
  51
  52     enum class FindElementsMode { Single, Multiple };
  53     enum class ExecuteScriptMode { Sync, Async };
  54     enum class Timeout { Script, PageLoad, Implicit };
  55
  56     struct Cookie {
  57         String name;
  58         String value;
  59         std::optional<String> path;
  60         std::optional<String> domain;
  61         std::optional<bool> secure;
  62         std::optional<bool> httpOnly;
  63         std::optional<unsigned> expiry;
  64     };
  65
  66     void waitForNavigationToComplete(Function<void (CommandResult&&)>&&);
  67     void createTopLevelBrowsingContext(Function<void (CommandResult&&)>&&);
  68     void close(Function<void (CommandResult&&)>&&);
  69     void getTimeouts(Function<void (CommandResult&&)>&&);
  70     void setTimeouts(const Timeouts&, Function<void (CommandResult&&)>&&);
  71
  72     void go(const String& url, Function<void (CommandResult&&)>&&);
  73     void getCurrentURL(Function<void (CommandResult&&)>&&);
  74     void back(Function<void (CommandResult&&)>&&);
  75     void forward(Function<void (CommandResult&&)>&&);
  76     void refresh(Function<void (CommandResult&&)>&&);
  77     void getTitle(Function<void (CommandResult&&)>&&);
  78     void getWindowHandle(Function<void (CommandResult&&)>&&);
  79     void closeWindow(Function<void (CommandResult&&)>&&);
  80     void switchToWindow(const String& windowHandle, Function<void (CommandResult&&)>&&);
  81     void getWindowHandles(Function<void (CommandResult&&)>&&);
  82     void switchToFrame(RefPtr<JSON::Value>&&, Function<void (CommandResult&&)>&&);
  83     void switchToParentFrame(Function<void (CommandResult&&)>&&);
  84     void getWindowRect(Function<void (CommandResult&&)>&&);
  85     void setWindowRect(std::optional<double> x, std::optional<double> y, std::optional<double> width, std::optional<double> height, Function<void (CommandResult&&)>&&);
  86     void findElements(const String& strategy, const String& selector, FindElementsMode, const String& rootElementID, Function<void (CommandResult&&)>&&);
  87     void getActiveElement(Function<void (CommandResult&&)>&&);
  88     void isElementSelected(const String& elementID, Function<void (CommandResult&&)>&&);
  89     void getElementText(const String& elementID, Function<void (CommandResult&&)>&&);
  90     void getElementTagName(const String& elementID, Function<void (CommandResult&&)>&&);
  91     void getElementRect(const String& elementID, Function<void (CommandResult&&)>&&);
  92     void isElementEnabled(const String& elementID, Function<void (CommandResult&&)>&&);
  93     void isElementDisplayed(const String& elementID, Function<void (CommandResult&&)>&&);
  94     void getElementAttribute(const String& elementID, const String& attribute, Function<void (CommandResult&&)>&&);
  95     void elementClick(const String& elementID, Function<void (CommandResult&&)>&&);
  96     void elementClear(const String& elementID, Function<void (CommandResult&&)>&&);
  97     void elementSendKeys(const String& elementID, Vector<String>&& keys, Function<void (CommandResult&&)>&&);
  98     void executeScript(const String& script, RefPtr<JSON::Array>&& arguments, ExecuteScriptMode, Function<void (CommandResult&&)>&&);
  99     void getAllCookies(Function<void (CommandResult&&)>&&);
 100     void getNamedCookie(const String& name, Function<void (CommandResult&&)>&&);
 101     void addCookie(const Cookie&, Function<void (CommandResult&&)>&&);
 102     void deleteCookie(const String& name, Function<void (CommandResult&&)>&&);
 103     void deleteAllCookies(Function<void (CommandResult&&)>&&);
 104     void dismissAlert(Function<void (CommandResult&&)>&&);
 105     void acceptAlert(Function<void (CommandResult&&)>&&);
 106     void getAlertText(Function<void (CommandResult&&)>&&);
 107     void sendAlertText(const String&, Function<void (CommandResult&&)>&&);
 108     void takeScreenshot(std::optional<String> elementID, std::optional<bool> scrollIntoView, Function<void (CommandResult&&)>&&);
 109
 110 private:
 111     Session(std::unique_ptr<SessionHost>&&);
 112
 113     void switchToTopLevelBrowsingContext(std::optional<String>);
 114     void switchToBrowsingContext(std::optional<String>);
 115     void closeTopLevelBrowsingContext(const String& toplevelBrowsingContext, Function<void (CommandResult&&)>&&);
 116     void closeAllToplevelBrowsingContexts(const String& toplevelBrowsingContext, Function<void (CommandResult&&)>&&);
 117
 118     void getToplevelBrowsingContextRect(Function<void (CommandResult&&)>&&);
 119     void moveToplevelBrowsingContextWindow(double x, double y, Function<void (CommandResult&&)>&&);
 120     void resizeToplevelBrowsingContextWindow(double width, double height, Function<void (CommandResult&&)>&&);
 121
 122     std::optional<String> pageLoadStrategyString() const;
 123
 124     void handleUserPrompts(Function<void (CommandResult&&)>&&);
 125     void handleUnexpectedAlertOpen(Function<void (CommandResult&&)>&&);
 126     void reportUnexpectedAlertOpen(Function<void (CommandResult&&)>&&);
 127
 128     RefPtr<JSON::Object> createElement(RefPtr<JSON::Value>&&);
 129     RefPtr<JSON::Object> createElement(const String& elementID);
 130     RefPtr<JSON::Object> extractElement(JSON::Value&);
 131     String extractElementID(JSON::Value&);
 132     RefPtr<JSON::Value> handleScriptResult(RefPtr<JSON::Value>&&);
 133
 134     struct Point {
 135         int x { 0 };
 136         int y { 0 };
 137     };
 138
 139     struct Size {
 140         int width { 0 };
 141         int height { 0 };
 142     };
 143
 144     struct Rect {
 145         Point origin;
 146         Size size;
 147     };
 148
 149     enum class ElementLayoutOption {
 150         ScrollIntoViewIfNeeded = 1 << 0,
 151         UseViewportCoordinates = 1 << 1,
 152     };
 153     void computeElementLayout(const String& elementID, OptionSet<ElementLayoutOption>, Function<void (std::optional<Rect>&&, std::optional<Point>&&, bool, RefPtr<JSON::Object>&&)>&&);
 154
 155     void selectOptionElement(const String& elementID, Function<void (CommandResult&&)>&&);
 156
 157     enum class MouseButton { None, Left, Middle, Right };
 158     enum class MouseInteraction { Move, Down, Up, SingleClick, DoubleClick };
 159     void performMouseInteraction(int x, int y, MouseButton, MouseInteraction, Function<void (CommandResult&&)>&&);
 160
 161     enum class KeyboardInteractionType { KeyPress, KeyRelease, InsertByKey };
 162     struct KeyboardInteraction {
 163         KeyboardInteractionType type { KeyboardInteractionType::InsertByKey };
 164         std::optional<String> text;
 165         std::optional<String> key;
 166     };
 167     enum KeyModifier {
 168         None = 0,
 169         Shift = 1 << 0,
 170         Control = 1 << 1,
 171         Alternate = 1 << 2,
 172         Meta = 1 << 3,
 173     };
 174     String virtualKeyForKeySequence(const String& keySequence, KeyModifier&);
 175     void performKeyboardInteractions(Vector<KeyboardInteraction>&&, Function<void (CommandResult&&)>&&);
 176
 177     std::unique_ptr<SessionHost> m_host;
 178     Timeouts m_timeouts;
 179     String m_id;
 180     std::optional<String> m_toplevelBrowsingContext;
 181     std::optional<String> m_currentBrowsingContext;
 182 };
 183
 184 } // WebDriver