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 <wtf/Forward.h>
  29 #include <wtf/Function.h>
  30 #include <wtf/OptionSet.h>
  31 #include <wtf/RefCounted.h>
  32 #include <wtf/Seconds.h>
  33 #include <wtf/Vector.h>
  34 #include <wtf/text/WTFString.h>
  35
  36 namespace Inspector {
  37 class InspectorArray;
  38 class InspectorObject;
  39 class InspectorValue;
  40 }
  41
  42 namespace WebDriver {
  43
  44 class Capabilities;
  45 class CommandResult;
  46 class SessionHost;
  47
  48 class Session : public RefCounted<Session> {
  49 public:
  50     static Ref<Session> create(std::unique_ptr<SessionHost>&& host)
  51     {
  52         return adoptRef(*new Session(WTFMove(host)));
  53     }
  54     ~Session();
  55
  56     const String& id() const { return m_id; }
  57     const Capabilities& capabilities() const;
  58
  59     enum class FindElementsMode { Single, Multiple };
  60     enum class ExecuteScriptMode { Sync, Async };
  61     enum class Timeout { Script, PageLoad, Implicit };
  62
  63     struct Timeouts {
  64         std::optional<Seconds> script;
  65         std::optional<Seconds> pageLoad;
  66         std::optional<Seconds> implicit;
  67     };
  68
  69     void createTopLevelBrowsingContext(Function<void (CommandResult&&)>&&);
  70     void close(Function<void (CommandResult&&)>&&);
  71     void getTimeouts(Function<void (CommandResult&&)>&&);
  72     void setTimeouts(const Timeouts&, Function<void (CommandResult&&)>&&);
  73
  74     void go(const String& url, Function<void (CommandResult&&)>&&);
  75     void getCurrentURL(Function<void (CommandResult&&)>&&);
  76     void back(Function<void (CommandResult&&)>&&);
  77     void forward(Function<void (CommandResult&&)>&&);
  78     void refresh(Function<void (CommandResult&&)>&&);
  79     void getTitle(Function<void (CommandResult&&)>&&);
  80     void getWindowHandle(Function<void (CommandResult&&)>&&);
  81     void closeWindow(Function<void (CommandResult&&)>&&);
  82     void switchToWindow(const String& windowHandle, Function<void (CommandResult&&)>&&);
  83     void getWindowHandles(Function<void (CommandResult&&)>&&);
  84     void switchToFrame(RefPtr<Inspector::InspectorValue>&&, Function<void (CommandResult&&)>&&);
  85     void switchToParentFrame(Function<void (CommandResult&&)>&&);
  86     void getWindowPosition(Function<void (CommandResult&&)>&&);
  87     void setWindowPosition(int windowX, int windowY, Function<void (CommandResult&&)>&&);
  88     void getWindowSize(Function<void (CommandResult&&)>&&);
  89     void setWindowSize(int windowWidth, int windowHeight, Function<void (CommandResult&&)>&&);
  90     void findElements(const String& strategy, const String& selector, FindElementsMode, const String& rootElementID, Function<void (CommandResult&&)>&&);
  91     void isElementSelected(const String& elementID, Function<void (CommandResult&&)>&&);
  92     void getElementText(const String& elementID, Function<void (CommandResult&&)>&&);
  93     void getElementTagName(const String& elementID, Function<void (CommandResult&&)>&&);
  94     void getElementRect(const String& elementID, Function<void (CommandResult&&)>&&);
  95     void isElementEnabled(const String& elementID, Function<void (CommandResult&&)>&&);
  96     void isElementDisplayed(const String& elementID, Function<void (CommandResult&&)>&&);
  97     void getElementAttribute(const String& elementID, const String& attribute, Function<void (CommandResult&&)>&&);
  98     void elementClick(const String& elementID, Function<void (CommandResult&&)>&&);
  99     void elementClear(const String& elementID, Function<void (CommandResult&&)>&&);
 100     void elementSendKeys(const String& elementID, Vector<String>&& keys, Function<void (CommandResult&&)>&&);
 101     void elementSubmit(const String& elementID, Function<void (CommandResult&&)>&&);
 102     void executeScript(const String& script, RefPtr<Inspector::InspectorArray>&& arguments, ExecuteScriptMode, Function<void (CommandResult&&)>&&);
 103
 104 private:
 105     Session(std::unique_ptr<SessionHost>&&);
 106
 107     RefPtr<Inspector::InspectorObject> createElement(RefPtr<Inspector::InspectorValue>&&);
 108     RefPtr<Inspector::InspectorObject> createElement(const String& elementID);
 109     RefPtr<Inspector::InspectorObject> extractElement(Inspector::InspectorValue&);
 110     String extractElementID(Inspector::InspectorValue&);
 111     RefPtr<Inspector::InspectorValue> handleScriptResult(RefPtr<Inspector::InspectorValue>&&);
 112
 113     struct Point {
 114         int x { 0 };
 115         int y { 0 };
 116     };
 117
 118     struct Size {
 119         int width { 0 };
 120         int height { 0 };
 121     };
 122
 123     struct Rect {
 124         Point origin;
 125         Size size;
 126     };
 127
 128     enum class ElementLayoutOption {
 129         ScrollIntoViewIfNeeded = 1 << 0,
 130         UseViewportCoordinates = 1 << 1,
 131     };
 132     void computeElementLayout(const String& elementID, OptionSet<ElementLayoutOption>, Function<void (std::optional<Rect>&&, RefPtr<Inspector::InspectorObject>&&)>&&);
 133
 134     enum class MouseButton { None, Left, Middle, Right };
 135     enum class MouseInteraction { Move, Down, Up, SingleClick, DoubleClick };
 136     void performMouseInteraction(int x, int y, MouseButton, MouseInteraction, Function<void (CommandResult&&)>&&);
 137
 138     enum class KeyboardInteractionType { KeyPress, KeyRelease, InsertByKey };
 139     struct KeyboardInteraction {
 140         KeyboardInteractionType type { KeyboardInteractionType::InsertByKey };
 141         std::optional<String> text;
 142         std::optional<String> key;
 143     };
 144     enum KeyModifier {
 145         None = 0,
 146         Shift = 1 << 0,
 147         Control = 1 << 1,
 148         Alternate = 1 << 2,
 149         Meta = 1 << 3,
 150     };
 151     String virtualKeyForKeySequence(const String& keySequence, KeyModifier&);
 152     void performKeyboardInteractions(Vector<KeyboardInteraction>&&, Function<void (CommandResult&&)>&&);
 153
 154     std::unique_ptr<SessionHost> m_host;
 155     Timeouts m_timeouts;
 156     String m_id;
 157     std::optional<String> m_toplevelBrowsingContext;
 158     std::optional<String> m_browsingContext;
 159 };
 160
 161 } // WebDriver