From 7c80b77c57881e9fdd7f7c504877a9a11e589b03 Mon Sep 17 00:00:00 2001
From: Dmitry Gozman <dgozman@gmail.com>
Date: Thu, 10 Nov 2022 12:29:14 -0800
Subject: [PATCH] feat(clear): remove `clear()` methods from all classes except
 `Locator` (#18703)

The preferred way is to use the locator, so we should not encourage the
use of `ElementHandle` or `Page` in the new APIs.
---
 docs/src/api/class-androiddevice.md           |  14 --
 docs/src/api/class-elementhandle.md           |  14 --
 docs/src/api/class-frame.md                   |  18 ---
 docs/src/api/class-page.md                    |  19 ---
 .../playwright-core/src/client/android.ts     |   4 -
 .../src/client/elementHandle.ts               |   4 -
 packages/playwright-core/src/client/frame.ts  |   4 -
 packages/playwright-core/src/client/page.ts   |   4 -
 packages/playwright-core/types/types.d.ts     | 126 ------------------
 tests/library/slowmo.spec.ts                  |   3 -
 tests/page/elementhandle-misc.spec.ts         |   9 --
 tests/page/page-fill.spec.ts                  |  25 ----
 12 files changed, 244 deletions(-)

diff --git a/docs/src/api/class-androiddevice.md b/docs/src/api/class-androiddevice.md
index 73f35a7d04..258946fe92 100644
--- a/docs/src/api/class-androiddevice.md
+++ b/docs/src/api/class-androiddevice.md
@@ -16,20 +16,6 @@ Emitted when the device connection gets closed.
 
 Emitted when a new WebView instance is detected.
 
-## async method: AndroidDevice.clear
-* since: v1.28
-
-Clears the specific [`param: selector`] input box.
-
-### param: AndroidDevice.clear.selector
-* since: v1.28
-- `selector` <[AndroidSelector]>
-
-Selector to clear.
-
-### option: AndroidDevice.clear.timeout = %%-android-timeout-%%
-* since: v1.28
-
 ## async method: AndroidDevice.close
 * since: v1.9
 
diff --git a/docs/src/api/class-elementhandle.md b/docs/src/api/class-elementhandle.md
index 82bcd44f99..484ea9f4e1 100644
--- a/docs/src/api/class-elementhandle.md
+++ b/docs/src/api/class-elementhandle.md
@@ -184,20 +184,6 @@ When all steps combined have not finished during the specified [`option: timeout
 ### option: ElementHandle.check.trial = %%-input-trial-%%
 * since: v1.11
 
-## async method: ElementHandle.clear
-* since: v1.28
-
-This method waits for [actionability](../actionability.md) checks, focuses the element, clears it and triggers an `input` event after clearing.
-
-If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared instead.
-
-### option: ElementHandle.clear.force = %%-input-force-%%
-* since: v1.28
-### option: ElementHandle.clear.noWaitAfter = %%-input-no-wait-after-%%
-* since: v1.28
-### option: ElementHandle.clear.timeout = %%-input-timeout-%%
-* since: v1.28
-
 ## async method: ElementHandle.click
 * since: v1.8
 
diff --git a/docs/src/api/class-frame.md b/docs/src/api/class-frame.md
index 78280304ec..347d75584c 100644
--- a/docs/src/api/class-frame.md
+++ b/docs/src/api/class-frame.md
@@ -224,24 +224,6 @@ When all steps combined have not finished during the specified [`option: timeout
 * since: v1.8
 - returns: <[Array]<[Frame]>>
 
-## async method: Frame.clear
-* since: v1.28
-
-This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, focuses the element, clears it and triggers an `input` event after clearing.
-
-If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared instead.
-
-### param: Frame.clear.selector = %%-input-selector-%%
-* since: v1.28
-
-### option: Frame.clear.force = %%-input-force-%%
-* since: v1.28
-### option: Frame.clear.noWaitAfter = %%-input-no-wait-after-%%
-* since: v1.28
-### option: Frame.clear.strict = %%-input-strict-%%
-* since: v1.28
-### option: Frame.clear.timeout = %%-input-timeout-%%
-* since: v1.28
 
 ## async method: Frame.click
 * since: v1.8
diff --git a/docs/src/api/class-page.md b/docs/src/api/class-page.md
index 6d432afc39..7535cf7507 100644
--- a/docs/src/api/class-page.md
+++ b/docs/src/api/class-page.md
@@ -737,25 +737,6 @@ Shortcut for main frame's [`method: Frame.check`].
 ### option: Page.check.trial = %%-input-trial-%%
 * since: v1.11
 
-## async method: Page.clear
-* since: v1.28
-
-This method waits for an element matching [`param: selector`], waits for [actionability](../actionability.md) checks, focuses the element, clears it and triggers an `input` event after clearing. Note that you can pass an empty string to clear the input field.
-
-If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error. However, if the element is inside the `<label>` element that has an associated [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared instead.
-
-### param: Page.clear.selector = %%-input-selector-%%
-* since: v1.28
-
-### option: Page.clear.force = %%-input-force-%%
-* since: v1.28
-### option: Page.clear.noWaitAfter = %%-input-no-wait-after-%%
-* since: v1.28
-### option: Page.clear.strict = %%-input-strict-%%
-* since: v1.28
-### option: Page.clear.timeout = %%-input-timeout-%%
-* since: v1.28
-
 ## async method: Page.click
 * since: v1.8
 
diff --git a/packages/playwright-core/src/client/android.ts b/packages/playwright-core/src/client/android.ts
index 2cb4136fb5..6b8d6327eb 100644
--- a/packages/playwright-core/src/client/android.ts
+++ b/packages/playwright-core/src/client/android.ts
@@ -186,10 +186,6 @@ export class AndroidDevice extends ChannelOwner<channels.AndroidDeviceChannel> i
     await this._channel.fill({ selector: toSelectorChannel(selector), text, ...options });
   }
 
-  async clear(selector: api.AndroidSelector, options?: types.TimeoutOptions) {
-    await this.fill(selector, '', options);
-  }
-
   async press(selector: api.AndroidSelector, key: api.AndroidKey, options?: types.TimeoutOptions) {
     await this.tap(selector, options);
     await this.input.press(key);
diff --git a/packages/playwright-core/src/client/elementHandle.ts b/packages/playwright-core/src/client/elementHandle.ts
index 3a11dfd4b2..3cd6efaac9 100644
--- a/packages/playwright-core/src/client/elementHandle.ts
+++ b/packages/playwright-core/src/client/elementHandle.ts
@@ -142,10 +142,6 @@ export class ElementHandle<T extends Node = Node> extends JSHandle<T> implements
     return await this._elementChannel.fill({ value, ...options });
   }
 
-  async clear(options: channels.ElementHandleFillOptions = {}): Promise<void> {
-    return this.fill('', options);
-  }
-
   async selectText(options: channels.ElementHandleSelectTextOptions = {}): Promise<void> {
     await this._elementChannel.selectText(options);
   }
diff --git a/packages/playwright-core/src/client/frame.ts b/packages/playwright-core/src/client/frame.ts
index 8044bf0da7..fc49e2ff45 100644
--- a/packages/playwright-core/src/client/frame.ts
+++ b/packages/playwright-core/src/client/frame.ts
@@ -295,10 +295,6 @@ export class Frame extends ChannelOwner<channels.FrameChannel> implements api.Fr
     return await this._channel.fill({ selector, value, ...options });
   }
 
-  async clear(selector: string, options: channels.FrameFillOptions = {}) {
-    return this.fill(selector, '', options);
-  }
-
   async _highlight(selector: string) {
     return await this._channel.highlight({ selector });
   }
diff --git a/packages/playwright-core/src/client/page.ts b/packages/playwright-core/src/client/page.ts
index a2fbc09f20..d3eb929dcd 100644
--- a/packages/playwright-core/src/client/page.ts
+++ b/packages/playwright-core/src/client/page.ts
@@ -568,10 +568,6 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
     return this._mainFrame.fill(selector, value, options);
   }
 
-  async clear(selector: string, options?: channels.FrameFillOptions) {
-    return this.fill(selector, '', options);
-  }
-
   locator(selector: string, options?: LocatorOptions): Locator {
     return this.mainFrame().locator(selector, options);
   }
diff --git a/packages/playwright-core/types/types.d.ts b/packages/playwright-core/types/types.d.ts
index 52c20b3d48..d3365eb9ab 100644
--- a/packages/playwright-core/types/types.d.ts
+++ b/packages/playwright-core/types/types.d.ts
@@ -1886,46 +1886,6 @@ export interface Page {
     trial?: boolean;
   }): Promise<void>;
 
-  /**
-   * This method waits for an element matching `selector`, waits for [actionability](https://playwright.dev/docs/actionability) checks, focuses the
-   * element, clears it and triggers an `input` event after clearing. Note that you can pass an empty string to clear the
-   * input field.
-   *
-   * If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
-   * However, if the element is inside the `<label>` element that has an associated
-   * [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared
-   * instead.
-   * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
-   * @param options
-   */
-  clear(selector: string, options?: {
-    /**
-     * Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
-     */
-    force?: boolean;
-
-    /**
-     * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can
-     * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to
-     * inaccessible pages. Defaults to `false`.
-     */
-    noWaitAfter?: boolean;
-
-    /**
-     * When true, the call requires selector to resolve to a single element. If given selector resolves to more than one
-     * element, the call throws an exception.
-     */
-    strict?: boolean;
-
-    /**
-     * Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
-     * using the
-     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
-     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
-     */
-    timeout?: number;
-  }): Promise<void>;
-
   /**
    * This method clicks an element matching `selector` by performing the following steps:
    * 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
@@ -5233,45 +5193,6 @@ export interface Frame {
 
   childFrames(): Array<Frame>;
 
-  /**
-   * This method waits for an element matching `selector`, waits for [actionability](https://playwright.dev/docs/actionability) checks, focuses the
-   * element, clears it and triggers an `input` event after clearing.
-   *
-   * If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
-   * However, if the element is inside the `<label>` element that has an associated
-   * [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared
-   * instead.
-   * @param selector A selector to search for an element. If there are multiple elements satisfying the selector, the first will be used. See [working with selectors](https://playwright.dev/docs/selectors) for more details.
-   * @param options
-   */
-  clear(selector: string, options?: {
-    /**
-     * Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
-     */
-    force?: boolean;
-
-    /**
-     * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can
-     * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to
-     * inaccessible pages. Defaults to `false`.
-     */
-    noWaitAfter?: boolean;
-
-    /**
-     * When true, the call requires selector to resolve to a single element. If given selector resolves to more than one
-     * element, the call throws an exception.
-     */
-    strict?: boolean;
-
-    /**
-     * Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
-     * using the
-     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
-     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
-     */
-    timeout?: number;
-  }): Promise<void>;
-
   /**
    * This method clicks an element matching `selector` by performing the following steps:
    * 1. Find an element matching `selector`. If there is none, wait until a matching element is attached to the DOM.
@@ -8627,38 +8548,6 @@ export interface ElementHandle<T=Node> extends JSHandle<T> {
     trial?: boolean;
   }): Promise<void>;
 
-  /**
-   * This method waits for [actionability](https://playwright.dev/docs/actionability) checks, focuses the element, clears it and triggers an
-   * `input` event after clearing.
-   *
-   * If the target element is not an `<input>`, `<textarea>` or `[contenteditable]` element, this method throws an error.
-   * However, if the element is inside the `<label>` element that has an associated
-   * [control](https://developer.mozilla.org/en-US/docs/Web/API/HTMLLabelElement/control), the control will be cleared
-   * instead.
-   * @param options
-   */
-  clear(options?: {
-    /**
-     * Whether to bypass the [actionability](https://playwright.dev/docs/actionability) checks. Defaults to `false`.
-     */
-    force?: boolean;
-
-    /**
-     * Actions that initiate navigations are waiting for these navigations to happen and for pages to start loading. You can
-     * opt out of waiting via setting this flag. You would only need this option in the exceptional cases such as navigating to
-     * inaccessible pages. Defaults to `false`.
-     */
-    noWaitAfter?: boolean;
-
-    /**
-     * Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
-     * using the
-     * [browserContext.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-browsercontext#browser-context-set-default-timeout)
-     * or [page.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-page#page-set-default-timeout) methods.
-     */
-    timeout?: number;
-  }): Promise<void>;
-
   /**
    * This method clicks the element by performing the following steps:
    * 1. Wait for [actionability](https://playwright.dev/docs/actionability) checks on the element, unless `force` option is set.
@@ -12631,21 +12520,6 @@ export interface AndroidDevice {
    */
   prependListener(event: 'webview', listener: (androidWebView: AndroidWebView) => void): this;
 
-  /**
-   * Clears the specific `selector` input box.
-   * @param selector Selector to clear.
-   * @param options
-   */
-  clear(selector: AndroidSelector, options?: {
-    /**
-     * Maximum time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by
-     * using the
-     * [androidDevice.setDefaultTimeout(timeout)](https://playwright.dev/docs/api/class-androiddevice#android-device-set-default-timeout)
-     * method.
-     */
-    timeout?: number;
-  }): Promise<void>;
-
   /**
    * Disconnects from the device.
    */
diff --git a/tests/library/slowmo.spec.ts b/tests/library/slowmo.spec.ts
index e2fe99b5a0..e4a561c543 100644
--- a/tests/library/slowmo.spec.ts
+++ b/tests/library/slowmo.spec.ts
@@ -138,9 +138,6 @@ it.describe('slowMo', () => {
   it('Frame SlowMo fill', async ({ page, server, toImpl }) => {
     await checkFrameSlowMo(toImpl, page, server, frame => frame.fill('.fill', 'foo'));
   });
-  it('Frame SlowMo clear', async ({ page, server, toImpl }) => {
-    await checkFrameSlowMo(toImpl, page, server, frame => frame.clear('.fill'));
-  });
   it('Frame SlowMo focus', async ({ page, server, toImpl }) => {
     await checkFrameSlowMo(toImpl, page, server, frame => frame.focus('button'));
   });
diff --git a/tests/page/elementhandle-misc.spec.ts b/tests/page/elementhandle-misc.spec.ts
index 24a2aa8f3f..2be0d10c8a 100644
--- a/tests/page/elementhandle-misc.spec.ts
+++ b/tests/page/elementhandle-misc.spec.ts
@@ -47,15 +47,6 @@ it('should fill input when Node is removed', async ({ page, server }) => {
   expect(await page.evaluate(() => window['result'])).toBe('some value');
 });
 
-it('should clear input', async ({ page, server }) => {
-  await page.goto(server.PREFIX + '/input/textarea.html');
-  const handle = await page.$('input');
-  await handle.fill('some value');
-  expect(await page.evaluate(() => window['result'])).toBe('some value');
-  await handle.clear();
-  expect(await page.evaluate(() => window['result'])).toBe('');
-});
-
 it('should check the box', async ({ page }) => {
   await page.setContent(`<input id='checkbox' type='checkbox'></input>`);
   const input = await page.$('input');
diff --git a/tests/page/page-fill.spec.ts b/tests/page/page-fill.spec.ts
index ae4f4b1f4f..556ff8cd97 100644
--- a/tests/page/page-fill.spec.ts
+++ b/tests/page/page-fill.spec.ts
@@ -44,16 +44,6 @@ it('should throw on unsupported inputs', async ({ page, server }) => {
   }
 });
 
-it('should throw on unsupported inputs when clear()', async ({ page, server }) => {
-  await page.goto(server.PREFIX + '/input/textarea.html');
-  for (const type of ['button', 'checkbox', 'file', 'image', 'radio', 'reset', 'submit']) {
-    await page.$eval('input', (input, type) => input.setAttribute('type', type), type);
-    let error = null;
-    await page.clear('input').catch(e => error = e);
-    expect(error.message).toContain(`input of type "${type}" cannot be filled`);
-  }
-});
-
 it('should fill different input types', async ({ page, server }) => {
   await page.goto(server.PREFIX + '/input/textarea.html');
   for (const type of ['password', 'search', 'tel', 'text', 'url', 'invalid-type']) {
@@ -202,13 +192,6 @@ it('should throw nice error without injected script stack when element is not an
   expect(error.message).toContain('page.fill: Error: Element is not an <input>, <textarea> or [contenteditable] element\n=========================== logs');
 });
 
-it('should throw nice error without injected script stack when element is not an <input> when clear()', async ({ page, server }) => {
-  let error = null;
-  await page.goto(server.PREFIX + '/input/textarea.html');
-  await page.clear('body').catch(e => error = e);
-  expect(error.message).toContain('page.clear: Error: Element is not an <input>, <textarea> or [contenteditable] element\n=========================== logs');
-});
-
 it('should throw if passed a non-string value', async ({ page, server }) => {
   let error = null;
   await page.goto(server.PREFIX + '/input/textarea.html');
@@ -317,14 +300,6 @@ it('should be able to clear using fill()', async ({ page, server }) => {
   expect(await page.evaluate(() => window['result'])).toBe('');
 });
 
-it('should be able to clear using clear()', async ({ page, server }) => {
-  await page.goto(server.PREFIX + '/input/textarea.html');
-  await page.fill('input', 'some value');
-  expect(await page.evaluate(() => window['result'])).toBe('some value');
-  await page.clear('input');
-  expect(await page.evaluate(() => window['result'])).toBe('');
-});
-
 it('should not throw when fill causes navigation', async ({ page, server }) => {
   await page.goto(server.PREFIX + '/input/textarea.html');
   await page.setContent('<input type=date>');