chore: roll 1.42.1 (#1511)

playwright/src/main/java/com/microsoft/playwright/Page.java

@@ -5918,34 +5918,40 @@ public interface Page extends AutoCloseable {
    */
   List<ElementHandle> querySelectorAll(String selector);
   /**
-   * Sometimes, the web page can show an overlay that obstructs elements behind it and prevents certain actions, like click,
-   * from completing. When such an overlay is shown predictably, we recommend dismissing it as a part of your test flow.
-   * However, sometimes such an overlay may appear non-deterministically, for example certain cookies consent dialogs behave
-   * this way. In this case, {@link Page#addLocatorHandler Page.addLocatorHandler()} allows handling an overlay during an
-   * action that it would block.
+   * When testing a web page, sometimes unexpected overlays like a coookie consent dialog appear and block actions you want
+   * to automate, e.g. clicking a button. These overlays don't always show up in the same way or at the same time, making
+   * them tricky to handle in automated tests.
    *
-   * <p> This method registers a handler for an overlay that is executed once the locator is visible on the page. The handler
-   * should get rid of the overlay so that actions blocked by it can proceed. This is useful for nondeterministic
-   * interstitial pages or dialogs, like a cookie consent dialog.
+   * <p> This method lets you set up a special function, called a handler, that activates when it detects that overlay is
+   * visible. The handler's job is to remove the overlay, allowing your test to continue as if the overlay wasn't there.
    *
-   * <p> Note that execution time of the handler counts towards the timeout of the action/assertion that executed the handler.
+   * <p> Things to keep in mind:
+   * <ul>
+   * <li> When an overlay is shown predictably, we recommend explicitly waiting for it in your test and dismissing it as a part of
+   * your normal test flow, instead of using {@link Page#addLocatorHandler Page.addLocatorHandler()}.</li>
+   * <li> Playwright checks for the overlay every time before executing or retrying an action that requires an <a
+   * href="https://playwright.dev/java/docs/actionability">actionability check</a>, or before performing an auto-waiting
+   * assertion check. When overlay is visible, Playwright calls the handler first, and then proceeds with the
+   * action/assertion.</li>
+   * <li> The execution time of the handler counts towards the timeout of the action/assertion that executed the handler. If your
+   * handler takes too long, it might cause timeouts.</li>
+   * <li> You can register multiple handlers. However, only a single handler will be running at a time. Make sure the actions
+   * within a handler don't depend on another handler.</li>
+   * </ul>
    *
-   * <p> You can register multiple handlers. However, only a single handler will be running at a time. Any actions inside a
-   * handler must not require another handler to run.
-   *
-   * <p> <strong>NOTE:</strong> Running the interceptor will alter your page state mid-test. For example it will change the currently focused element
-   * and move the mouse. Make sure that the actions that run after the interceptor are self-contained and do not rely on the
-   * focus and mouse state. <br /> <br /> For example, consider a test that calls {@link Locator#focus Locator.focus()}
+   * <p> <strong>NOTE:</strong> Running the handler will alter your page state mid-test. For example it will change the currently focused element and
+   * move the mouse. Make sure that actions that run after the handler are self-contained and do not rely on the focus and
+   * mouse state being unchanged. <br /> <br /> For example, consider a test that calls {@link Locator#focus Locator.focus()}
    * followed by {@link Keyboard#press Keyboard.press()}. If your handler clicks a button between these two actions, the
    * focused element most likely will be wrong, and key press will happen on the unexpected element. Use {@link Locator#press
    * Locator.press()} instead to avoid this problem. <br /> <br /> Another example is a series of mouse actions, where {@link
    * Mouse#move Mouse.move()} is followed by {@link Mouse#down Mouse.down()}. Again, when the handler runs between these two
-   * actions, the mouse position will be wrong during the mouse down. Prefer methods like {@link Locator#click
-   * Locator.click()} that are self-contained.
+   * actions, the mouse position will be wrong during the mouse down. Prefer self-contained actions like {@link Locator#click
+   * Locator.click()} that do not rely on the state being unchanged by a handler.
    *
    * <p> **Usage**
    *
-   * <p> An example that closes a cookie dialog when it appears:
+   * <p> An example that closes a cookie consent dialog when it appears:
    * <pre>{@code
    * // Setup the handler.
    * page.addLocatorHandler(page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Accept all cookies")), () => {

scripts/CLI_VERSION

@@ -1 +1 @@
-1.42.0
+1.42.1