Add new-window API to expose WebDriver's New Window endpoint (#680)

* Add workflow_dispatch to test.yml

* Add new-window API to expose WebDriver's New Window endpoint

* Revert "Add workflow_dispatch to test.yml"

This reverts commit dd59ae9.

* Add credit in CHANGELOG

CHANGELOG.adoc

@@ -19,6 +19,9 @@ A release with an intentional breaking changes is marked with:
 //   (adjust these in publish.clj as you see fit)
 == Unreleased
 
+* Changes
+** {issue}679[#679]: Add `new-window` function that exposes WebDriver's New Window endpoint. ({person}dgr[@dgr])
+
 == v1.1.42 - 2024-09-27 [[v1.1.42]]
 
 * Changes

src/etaoin/api.clj

@@ -92,7 +92,7 @@
   - [[get-window-size]] [[set-window-size]]
   - [[maximize]]
   - [[switch-window]] [[switch-window-next]]
-  - [[close-window]]
+  - [[new-window]] [[close-window]]
 
   **Frames**
   - [[switch-frame]] [[switch-frame-first]] [[switch-frame-parent]] [[switch-frame-top]] [[with-frame]]
@@ -372,6 +372,27 @@
                            (recur hs)))]
     (switch-window driver next-handle)))
 
+(defn new-window
+  "Have `driver` create a new window. The `window-type-hint` parameter
+  must be either `:tab` or `:window` and specifies the type of window
+  that is desired, if supported by the browser. If successful, return
+  a map with keys `:handle` indicating the new window handle and
+  `:type` indicating the type of window that was actually
+  created (either `:tab` or `:window`).
+
+  https://www.w3.org/TR/webdriver2/#dfn-new-window"
+  [driver window-type-hint]
+  (if (#{:tab :window} window-type-hint)
+    (-> (execute {:driver driver
+                  :method :post
+                  :path [:session (:session driver) :window :new]
+                  :data {:type window-type-hint}})
+        :value
+        (update :type keyword))
+    (throw+ {:type :etaoin/argument
+             :message "Argument `window-type-hint` must be either `:tab` or `:window`."
+             :window-type-hint window-type-hint})))
+
 (defn close-window
   "Have `driver` close current browser window.
   On last window close, closes the session.

test/etaoin/api_test.clj

@@ -637,6 +637,16 @@
         (is (not= width width'))
         (is (not= height height'))))))
 
+(deftest test-new-window
+  (is (= 1 (count (e/get-window-handles *driver*))))
+  (let [initial-window (e/get-window-handle *driver*)
+        new-windows (for [_ (range 3)]
+                      (-> (e/new-window *driver* :tab)
+                          :handle))
+        windows (into #{initial-window} new-windows)]
+    (is (= 4 (count (e/get-window-handles *driver*))))
+    (is (= windows (set (e/get-window-handles *driver*))))))
+
 (deftest test-switch-window
   (let [init-handle   (e/get-window-handle *driver*)
         init-url      (e/get-url *driver*)]