diff --git a/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java b/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java index eef4a2ca..c20b13fd 100644 --- a/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java +++ b/playwright/src/main/java/com/microsoft/playwright/ElementHandle.java @@ -23,6 +23,8 @@ import java.util.*; /** * ElementHandle represents an in-page DOM element. ElementHandles can be created with the {@link Page#querySelector * Page.querySelector()} method. + * + *

NOTE: The use of ElementHandle is discouraged, use {@code Locator} objects and web-first assertions instead. * 

{@code
  * ElementHandle hrefElement = page.querySelector("a");
  * hrefElement.click();
@@ -34,10 +36,6 @@ import java.util.*;
  * 
 ElementHandle instances can be used as an argument in {@link Page#evalOnSelector Page.evalOnSelector()} and {@link
  * Page#evaluate Page.evaluate()} methods.
  *
- * 
 NOTE: In most cases, you would want to use the {@code Locator} object instead. You should only use {@code ElementHandle} if you want to
- * retain a handle to a particular DOM Node that you intend to pass into {@link Page#evaluate Page.evaluate()} as an
- * argument.
- *
  * 
 The difference between the {@code Locator} and ElementHandle is that the ElementHandle points to a particular element, while
  * {@code Locator} captures the logic of how to retrieve an element.
  *
diff --git a/playwright/src/main/java/com/microsoft/playwright/Frame.java b/playwright/src/main/java/com/microsoft/playwright/Frame.java
index 65bd6de1..b803e8db 100644
--- a/playwright/src/main/java/com/microsoft/playwright/Frame.java
+++ b/playwright/src/main/java/com/microsoft/playwright/Frame.java
@@ -2329,6 +2329,9 @@ public interface Frame {
   /**
    * Returns the return value of {@code expression}.
    *
+   * 
 NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use
+   * {@link Locator#evaluate Locator.evaluate()}, other {@code Locator} helper methods or web-first assertions instead.
+   *
    * 
 The method finds an element matching the specified selector within the frame and passes it as a first argument to
    * {@code expression}. See Working with selectors for more details. If
    * no elements match the selector, the method throws an error.
@@ -2356,6 +2359,9 @@ public interface Frame {
   /**
    * Returns the return value of {@code expression}.
    *
+   * 
 NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use
+   * {@link Locator#evaluate Locator.evaluate()}, other {@code Locator} helper methods or web-first assertions instead.
+   *
    * 
 The method finds an element matching the specified selector within the frame and passes it as a first argument to
    * {@code expression}. See Working with selectors for more details. If
    * no elements match the selector, the method throws an error.
@@ -2382,6 +2388,9 @@ public interface Frame {
   /**
    * Returns the return value of {@code expression}.
    *
+   * 
 NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use
+   * {@link Locator#evaluate Locator.evaluate()}, other {@code Locator} helper methods or web-first assertions instead.
+   *
    * 
 The method finds an element matching the specified selector within the frame and passes it as a first argument to
    * {@code expression}. See Working with selectors for more details. If
    * no elements match the selector, the method throws an error.
@@ -2407,6 +2416,9 @@ public interface Frame {
   /**
    * Returns the return value of {@code expression}.
    *
+   * 
 NOTE: In most cases, {@link Locator#evaluateAll Locator.evaluateAll()}, other {@code Locator} helper methods and web-first
+   * assertions do a better job.
+   *
    * 
 The method finds all elements matching the specified selector within the frame and passes an array of matched elements
    * as a first argument to {@code expression}. See Working with
    * selectors for more details.
@@ -2431,6 +2443,9 @@ public interface Frame {
   /**
    * Returns the return value of {@code expression}.
    *
+   * 
 NOTE: In most cases, {@link Locator#evaluateAll Locator.evaluateAll()}, other {@code Locator} helper methods and web-first
+   * assertions do a better job.
+   *
    * 
 The method finds all elements matching the specified selector within the frame and passes an array of matched elements
    * as a first argument to {@code expression}. See Working with
    * selectors for more details.
@@ -2475,7 +2490,7 @@ public interface Frame {
    *
    * 
 {@code ElementHandle} instances can be passed as an argument to the {@link Frame#evaluate Frame.evaluate()}:
    * 
{@code
-   * ElementHandle bodyHandle = frame.querySelector("body");
+   * ElementHandle bodyHandle = frame.evaluate("document.body");
    * String html = (String) frame.evaluate("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(bodyHandle, "hello"));
    * bodyHandle.dispose();
    * }

@@ -2510,7 +2525,7 @@ public interface Frame {
    *
    * 
 {@code ElementHandle} instances can be passed as an argument to the {@link Frame#evaluate Frame.evaluate()}:
    * 
{@code
-   * ElementHandle bodyHandle = frame.querySelector("body");
+   * ElementHandle bodyHandle = frame.evaluate("document.body");
    * String html = (String) frame.evaluate("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(bodyHandle, "hello"));
    * bodyHandle.dispose();
    * }

@@ -3010,6 +3025,8 @@ public interface Frame {
   /**
    * Returns the ElementHandle pointing to the frame element.
    *
+   * 
 NOTE: The use of {@code ElementHandle} is discouraged, use {@code Locator} objects and web-first assertions instead.
+   *
    * 
 The method finds an element matching the specified selector within the frame. See Working with selectors for more details. If no elements match the
    * selector, returns {@code null}.
@@ -3023,6 +3040,8 @@ public interface Frame {
   /**
    * Returns the ElementHandle pointing to the frame element.
    *
+   * 
 NOTE: The use of {@code ElementHandle} is discouraged, use {@code Locator} objects and web-first assertions instead.
+   *
    * 
 The method finds an element matching the specified selector within the frame. See Working with selectors for more details. If no elements match the
    * selector, returns {@code null}.
@@ -3034,6 +3053,8 @@ public interface Frame {
   /**
    * Returns the ElementHandles pointing to the frame elements.
    *
+   * 
 NOTE: The use of {@code ElementHandle} is discouraged, use {@code Locator} objects instead.
+   *
    * 
 The method finds all elements matching the specified selector within the frame. See Working with selectors for more details. If no elements match the
    * selector, returns empty array.
@@ -3904,6 +3925,9 @@ public interface Frame {
    * Returns when element specified by selector satisfies {@code state} option. Returns {@code null} if waiting for {@code hidden} or
    * {@code detached}.
    *
+   * 
 NOTE: Playwright automatically waits for element to be ready before performing an action. Using {@code Locator} objects and
+   * web-first assertions make the code wait-for-selector-free.
+   *
    * 
 Wait for the {@code selector} to satisfy {@code state} option (either appear/disappear from dom, or become visible/hidden). If at
    * the moment of calling the method {@code selector} already satisfies the condition, the method will return immediately. If the
    * selector doesn't satisfy the condition for the {@code timeout} milliseconds, the function will throw.
@@ -3939,6 +3963,9 @@ public interface Frame {
    * Returns when element specified by selector satisfies {@code state} option. Returns {@code null} if waiting for {@code hidden} or
    * {@code detached}.
    *
+   * 
 NOTE: Playwright automatically waits for element to be ready before performing an action. Using {@code Locator} objects and
+   * web-first assertions make the code wait-for-selector-free.
+   *
    * 
 Wait for the {@code selector} to satisfy {@code state} option (either appear/disappear from dom, or become visible/hidden). If at
    * the moment of calling the method {@code selector} already satisfies the condition, the method will return immediately. If the
    * selector doesn't satisfy the condition for the {@code timeout} milliseconds, the function will throw.
diff --git a/playwright/src/main/java/com/microsoft/playwright/Page.java b/playwright/src/main/java/com/microsoft/playwright/Page.java
index d5002845..5eb2402e 100644
--- a/playwright/src/main/java/com/microsoft/playwright/Page.java
+++ b/playwright/src/main/java/com/microsoft/playwright/Page.java
@@ -3467,7 +3467,10 @@ public interface Page extends AutoCloseable {
    */
   void emulateMedia(EmulateMediaOptions options);
   /**
-   * The method finds an element matching the specified selector within the page and passes it as a first argument to
+   * NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use
+   * {@link Locator#evaluate Locator.evaluate()}, other {@code Locator} helper methods or web-first assertions instead.
+   *
+   * 
 The method finds an element matching the specified selector within the page and passes it as a first argument to
    * {@code expression}. If no elements match the selector, the method throws an error. Returns the value of {@code expression}.
    *
    * 
 If {@code expression} returns a NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use
+   * {@link Locator#evaluate Locator.evaluate()}, other {@code Locator} helper methods or web-first assertions instead.
+   *
+   * 
 The method finds an element matching the specified selector within the page and passes it as a first argument to
    * {@code expression}. If no elements match the selector, the method throws an error. Returns the value of {@code expression}.
    *
    * 
 If {@code expression} returns a NOTE: This method does not wait for the element to pass actionability checks and therefore can lead to the flaky tests. Use
+   * {@link Locator#evaluate Locator.evaluate()}, other {@code Locator} helper methods or web-first assertions instead.
+   *
+   * 
 The method finds an element matching the specified selector within the page and passes it as a first argument to
    * {@code expression}. If no elements match the selector, the method throws an error. Returns the value of {@code expression}.
    *
    * 
 If {@code expression} returns a NOTE: In most cases, {@link Locator#evaluateAll Locator.evaluateAll()}, other {@code Locator} helper methods and web-first
+   * assertions do a better job.
+   *
+   * 
 The method finds all elements matching the specified selector within the page and passes an array of matched elements as
    * a first argument to {@code expression}. Returns the result of {@code expression} invocation.
    *
    * 
 If {@code expression} returns a NOTE: In most cases, {@link Locator#evaluateAll Locator.evaluateAll()}, other {@code Locator} helper methods and web-first
+   * assertions do a better job.
+   *
+   * 
 The method finds all elements matching the specified selector within the page and passes an array of matched elements as
    * a first argument to {@code expression}. Returns the result of {@code expression} invocation.
    *
    * 
 If {@code expression} returns a  {@code ElementHandle} instances can be passed as an argument to the {@link Page#evaluate Page.evaluate()}:
    * 
{@code
-   * ElementHandle bodyHandle = page.querySelector("body");
+   * ElementHandle bodyHandle = page.evaluate("document.body");
    * String html = (String) page.evaluate("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(bodyHandle, "hello"));
    * bodyHandle.dispose();
    * }

@@ -3647,7 +3662,7 @@ public interface Page extends AutoCloseable {
    *
    * 
 {@code ElementHandle} instances can be passed as an argument to the {@link Page#evaluate Page.evaluate()}:
    * 
{@code
-   * ElementHandle bodyHandle = page.querySelector("body");
+   * ElementHandle bodyHandle = page.evaluate("document.body");
    * String html = (String) page.evaluate("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(bodyHandle, "hello"));
    * bodyHandle.dispose();
    * }

@@ -4535,9 +4550,10 @@ public interface Page extends AutoCloseable {
    */
   void press(String selector, String key, PressOptions options);
   /**
-   * The method finds an element matching the specified selector within the page. If no elements match the selector, the
-   * return value resolves to {@code null}. To wait for an element on the page, use {@link Page#waitForSelector
-   * Page.waitForSelector()}.
+   * NOTE: The use of {@code ElementHandle} is discouraged, use {@code Locator} objects and web-first assertions instead.
+   *
+   * 
 The method finds an element matching the specified selector within the page. If no elements match the selector, the
+   * return value resolves to {@code null}. To wait for an element on the page, use {@link Locator#waitFor Locator.waitFor()}.
    *
    * 
 Shortcut for main frame's {@link Frame#querySelector Frame.querySelector()}.
    *
@@ -4548,9 +4564,10 @@ public interface Page extends AutoCloseable {
     return querySelector(selector, null);
   }
   /**
-   * The method finds an element matching the specified selector within the page. If no elements match the selector, the
-   * return value resolves to {@code null}. To wait for an element on the page, use {@link Page#waitForSelector
-   * Page.waitForSelector()}.
+   * NOTE: The use of {@code ElementHandle} is discouraged, use {@code Locator} objects and web-first assertions instead.
+   *
+   * 
 The method finds an element matching the specified selector within the page. If no elements match the selector, the
+   * return value resolves to {@code null}. To wait for an element on the page, use {@link Locator#waitFor Locator.waitFor()}.
    *
    * 
 Shortcut for main frame's {@link Frame#querySelector Frame.querySelector()}.
    *
@@ -4559,7 +4576,9 @@ public interface Page extends AutoCloseable {
    */
   ElementHandle querySelector(String selector, QuerySelectorOptions options);
   /**
-   * The method finds all elements matching the specified selector within the page. If no elements match the selector, the
+   * NOTE: The use of {@code ElementHandle} is discouraged, use {@code Locator} objects and web-first assertions instead.
+   *
+   * 
 The method finds all elements matching the specified selector within the page. If no elements match the selector, the
    * return value resolves to {@code []}.
    *
    * 
 Shortcut for main frame's {@link Frame#querySelectorAll Frame.querySelectorAll()}.
@@ -6343,6 +6362,9 @@ public interface Page extends AutoCloseable {
    * Returns when element specified by selector satisfies {@code state} option. Returns {@code null} if waiting for {@code hidden} or
    * {@code detached}.
    *
+   * 
 NOTE: Playwright automatically waits for element to be ready before performing an action. Using {@code Locator} objects and
+   * web-first assertions make the code wait-for-selector-free.
+   *
    * 
 Wait for the {@code selector} to satisfy {@code state} option (either appear/disappear from dom, or become visible/hidden). If at
    * the moment of calling the method {@code selector} already satisfies the condition, the method will return immediately. If the
    * selector doesn't satisfy the condition for the {@code timeout} milliseconds, the function will throw.
@@ -6378,6 +6400,9 @@ public interface Page extends AutoCloseable {
    * Returns when element specified by selector satisfies {@code state} option. Returns {@code null} if waiting for {@code hidden} or
    * {@code detached}.
    *
+   * 
 NOTE: Playwright automatically waits for element to be ready before performing an action. Using {@code Locator} objects and
+   * web-first assertions make the code wait-for-selector-free.
+   *
    * 
 Wait for the {@code selector} to satisfy {@code state} option (either appear/disappear from dom, or become visible/hidden). If at
    * the moment of calling the method {@code selector} already satisfies the condition, the method will return immediately. If the
    * selector doesn't satisfy the condition for the {@code timeout} milliseconds, the function will throw.
diff --git a/playwright/src/main/java/com/microsoft/playwright/Selectors.java b/playwright/src/main/java/com/microsoft/playwright/Selectors.java
index c69b4e85..f4a63c2c 100644
--- a/playwright/src/main/java/com/microsoft/playwright/Selectors.java
+++ b/playwright/src/main/java/com/microsoft/playwright/Selectors.java
@@ -62,11 +62,11 @@ public interface Selectors {
    * Page page = browser.newPage();
    * page.setContent("
");
    * // Use the selector prefixed with its name.
-   * ElementHandle button = page.querySelector("tag=button");
+   * Locator button = page.locator("tag=button");
    * // Combine it with other selector engines.
    * page.click("tag=div >> text=\"Click me\"");
    * // Can use it in any methods supporting selectors.
-   * int buttonCount = (int) page.evalOnSelectorAll("tag=button", "buttons => buttons.length");
+   * int buttonCount = (int) page.locator("tag=button").count();
    * browser.close();
    * }
* @@ -97,11 +97,11 @@ public interface Selectors { * Page page = browser.newPage(); * page.setContent("
"); * // Use the selector prefixed with its name. - * ElementHandle button = page.querySelector("tag=button"); + * Locator button = page.locator("tag=button"); * // Combine it with other selector engines. * page.click("tag=div >> text=\"Click me\""); * // Can use it in any methods supporting selectors. - * int buttonCount = (int) page.evalOnSelectorAll("tag=button", "buttons => buttons.length"); + * int buttonCount = (int) page.locator("tag=button").count(); * browser.close(); * } * @@ -130,11 +130,11 @@ public interface Selectors { * Page page = browser.newPage(); * page.setContent("
"); * // Use the selector prefixed with its name. - * ElementHandle button = page.querySelector("tag=button"); + * Locator button = page.locator("tag=button"); * // Combine it with other selector engines. * page.click("tag=div >> text=\"Click me\""); * // Can use it in any methods supporting selectors. - * int buttonCount = (int) page.evalOnSelectorAll("tag=button", "buttons => buttons.length"); + * int buttonCount = (int) page.locator("tag=button").count(); * browser.close(); * } * @@ -165,11 +165,11 @@ public interface Selectors { * Page page = browser.newPage(); * page.setContent("
"); * // Use the selector prefixed with its name. - * ElementHandle button = page.querySelector("tag=button"); + * Locator button = page.locator("tag=button"); * // Combine it with other selector engines. * page.click("tag=div >> text=\"Click me\""); * // Can use it in any methods supporting selectors. - * int buttonCount = (int) page.evalOnSelectorAll("tag=button", "buttons => buttons.length"); + * int buttonCount = (int) page.locator("tag=button").count(); * browser.close(); * } * diff --git a/scripts/CLI_VERSION b/scripts/CLI_VERSION index 5bab889c..3c33c0c6 100644 --- a/scripts/CLI_VERSION +++ b/scripts/CLI_VERSION @@ -1 +1 @@ -1.17.0-next-1636496060000 +1.17.0-1637005716000