api(waitForSelector): bring it back

docs/api.md

@@ -94,7 +94,7 @@ const iPhone = devices['iPhone 6'];
 - returns: <[Object]>
   - `TimeoutError` <[function]> A class of [TimeoutError].
 
-Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForElement(selector[, options])](#pagewaitforelementselector-options)
+Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](#pagewaitforelementselector-options)
 might fail if the selector doesn't match any nodes during the given timeframe.
 
 For certain types of errors Playwright uses specific error classes.
@@ -103,7 +103,7 @@ These classes are available via [`browserType.errors`](#browsertypeerrors) or [`
 An example of handling a timeout error:
 ```js
 try {
-  await page.waitForElement('.foo');
+  await page.waitForSelector('.foo');
 } catch (e) {
   if (e instanceof playwright.errors.TimeoutError) {
     // Do something if this is a timeout.
@@ -683,7 +683,7 @@ page.removeListener('request', logRequest);
 - [page.url()](#pageurl)
 - [page.viewportSize()](#pageviewportsize)
 - [page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#pagewaitforselectororfunctionortimeout-options-args)
-- [page.waitForElement(selector[, options])](#pagewaitforelementselector-options)
+- [page.waitForSelector(selector[, options])](#pagewaitforelementselector-options)
 - [page.waitForEvent(event[, optionsOrPredicate])](#pagewaitforeventevent-optionsorpredicate)
 - [page.waitForFunction(pageFunction[, options[, ...args]])](#pagewaitforfunctionpagefunction-options-args)
 - [page.waitForLoadState([options])](#pagewaitforloadstateoptions)
@@ -1664,7 +1664,7 @@ This is a shortcut for [page.mainFrame().url()](#frameurl)
 - returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
 
 This method behaves differently with respect to the type of the first parameter:
-- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] and the method is a shortcut for [page.waitForElement](#pagewaitforelementselector-options)
+- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] and the method is a shortcut for [page.waitForSelector](#pagewaitforelementselector-options)
 - if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [page.waitForFunction()](#pagewaitforfunctionpagefunction-options-args).
 - if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
 - otherwise, an exception is thrown
@@ -1687,7 +1687,7 @@ await page.waitFor(selector => !!document.querySelector(selector), {}, selector)
 
 Shortcut for [page.mainFrame().waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforelementorfunctionortimeout-options-args).
 
-#### page.waitForElement(selector[, options])
+#### page.waitForSelector(selector[, options])
 - `selector` <[string]> A selector of an element to wait for
 - `options` <[Object]>
   - `waitFor` <"attached"|"detached"|"visible"|"hidden"> Wait for element to become visible (`visible`), hidden (`hidden`), present in dom (`attached`) or not present in dom (`detached`). Defaults to `attached`.
@@ -1705,15 +1705,15 @@ const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.
   const page = await browser.newPage();
   let currentURL;
   page
-    .waitForElement('img')
+    .waitForSelector('img')
     .then(() => console.log('First URL with image: ' + currentURL));
   for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
     await page.goto(currentURL);
   }
   await browser.close();
 })();
 ```
-Shortcut for [page.mainFrame().waitForElement(selector[, options])](#framewaitforelementselector-options).
+Shortcut for [page.mainFrame().waitForSelector(selector[, options])](#framewaitforelementselector-options).
 
 #### page.waitForEvent(event[, optionsOrPredicate])
 - `event` <[string]> Event name, same one would pass into `page.on(event)`.
@@ -1915,7 +1915,7 @@ An example of getting text from an iframe element:
 - [frame.uncheck(selector, [options])](#frameuncheckselector-options)
 - [frame.url()](#frameurl)
 - [frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])](#framewaitforselectororfunctionortimeout-options-args)
-- [frame.waitForElement(selector[, options])](#framewaitforelementselector-options)
+- [frame.waitForSelector(selector[, options])](#framewaitforelementselector-options)
 - [frame.waitForFunction(pageFunction[, options[, ...args]])](#framewaitforfunctionpagefunction-options-args)
 - [frame.waitForLoadState([options])](#framewaitforloadstateoptions)
 - [frame.waitForNavigation([options])](#framewaitfornavigationoptions)
@@ -2375,7 +2375,7 @@ Returns frame's url.
 - returns: <[Promise]<[JSHandle]>> Promise which resolves to a JSHandle of the success value
 
 This method behaves differently with respect to the type of the first parameter:
-- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] and the method is a shortcut for [frame.waitForElement](#framewaitforelementselector-options)
+- if `selectorOrFunctionOrTimeout` is a `string`, then the first argument is treated as a [selector] and the method is a shortcut for [frame.waitForSelector](#framewaitforelementselector-options)
 - if `selectorOrFunctionOrTimeout` is a `function`, then the first argument is treated as a predicate to wait for and the method is a shortcut for [frame.waitForFunction()](#framewaitforfunctionpagefunction-options-args).
 - if `selectorOrFunctionOrTimeout` is a `number`, then the first argument is treated as a timeout in milliseconds and the method returns a promise which resolves after the timeout
 - otherwise, an exception is thrown
@@ -2396,7 +2396,7 @@ const selector = '.foo';
 await page.waitFor(selector => !!document.querySelector(selector), {}, selector);
 ```
 
-#### frame.waitForElement(selector[, options])
+#### frame.waitForSelector(selector[, options])
 - `selector` <[string]> A selector of an element to wait for
 - `options` <[Object]>
   - `waitFor` <"attached"|"detached"|"visible"|"hidden"> Wait for element to become visible (`visible`), hidden (`hidden`), present in dom (`attached`) or not present in dom (`detached`). Defaults to `attached`.
@@ -2414,7 +2414,7 @@ const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.
   const page = await browser.newPage();
   let currentURL;
   page.mainFrame()
-    .waitForElement('img')
+    .waitForSelector('img')
     .then(() => console.log('First URL with image: ' + currentURL));
   for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) {
     await page.goto(currentURL);
@@ -3515,7 +3515,7 @@ const { selectors, firefox } = require('playwright');  // Or 'chromium' or 'webk
 
 * extends: [Error]
 
-TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. [page.waitForElement(selector[, options])](#pagewaitforelementselector-options) or [browserType.launch([options])](#browsertypelaunchoptions).
+TimeoutError is emitted whenever certain operations are terminated due to timeout, e.g. [page.waitForSelector(selector[, options])](#pagewaitforelementselector-options) or [browserType.launch([options])](#browsertypelaunchoptions).
 
 ### class: Accessibility
 
@@ -3743,7 +3743,7 @@ Download browser binary if it is missing.
 - returns: <[Object]>
   - `TimeoutError` <[function]> A class of [TimeoutError].
 
-Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForElement(selector[, options])](#pagewaitforelementselector-options)
+Playwright methods might throw errors if they are unable to fulfill a request. For example, [page.waitForSelector(selector[, options])](#pagewaitforelementselector-options)
 might fail if the selector doesn't match any nodes during the given timeframe.
 
 For certain types of errors Playwright uses specific error classes.
@@ -3753,7 +3753,7 @@ An example of handling a timeout error:
 ```js
 const { webkit } = require('playwright');  // Or 'chromium' or 'firefox'.
 try {
-  await page.waitForElement('.foo');
+  await page.waitForSelector('.foo');
 } catch (e) {
   if (e instanceof webkit.errors.TimeoutError) {
     // Do something if this is a timeout.

src/frames.ts

@@ -580,7 +580,7 @@ export class Frame {
     return handle;
   }
 
-  async waitForElement(selector: string, options?: types.WaitForElementOptions): Promise<dom.ElementHandle<Element> | null> {
+  async waitForSelector(selector: string, options?: types.WaitForElementOptions): Promise<dom.ElementHandle<Element> | null> {
     if (options && (options as any).visibility)
       throw new Error('options.visibility is not supported, did you mean options.waitFor?');
     const handle = await this._waitForSelectorInUtilityContext(selector, options);
@@ -870,7 +870,7 @@ export class Frame {
 
   async waitFor(selectorOrFunctionOrTimeout: (string | number | Function), options: types.WaitForFunctionOptions & types.WaitForElementOptions = {}, ...args: any[]): Promise<js.JSHandle | null> {
     if (helper.isString(selectorOrFunctionOrTimeout))
-      return this.waitForElement(selectorOrFunctionOrTimeout, options) as any;
+      return this.waitForSelector(selectorOrFunctionOrTimeout, options) as any;
     if (helper.isNumber(selectorOrFunctionOrTimeout))
       return new Promise(fulfill => setTimeout(fulfill, selectorOrFunctionOrTimeout));
     if (typeof selectorOrFunctionOrTimeout === 'function')

src/page.ts

@@ -230,8 +230,8 @@ export class Page extends platform.EventEmitter {
     return this.mainFrame().$(selector);
   }
 
-  async waitForElement(selector: string, options?: types.WaitForElementOptions): Promise<dom.ElementHandle<Element> | null> {
-    return this.mainFrame().waitForElement(selector, options);
+  async waitForSelector(selector: string, options?: types.WaitForElementOptions): Promise<dom.ElementHandle<Element> | null> {
+    return this.mainFrame().waitForSelector(selector, options);
   }
 
   evaluateHandle: types.EvaluateHandle = async (pageFunction, ...args) => {

test/chromium/oopif.spec.js

@@ -85,7 +85,7 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
         document.body.appendChild(frame);
         return new Promise(x => frame.onload = x);
       });
-      await page.waitForElement('iframe[src="https://google.com/"]');
+      await page.waitForSelector('iframe[src="https://google.com/"]');
       const urls = page.frames().map(frame => frame.url()).sort();
       expect(urls).toEqual([
         server.EMPTY_PAGE,

test/launcher.spec.js

@@ -171,15 +171,15 @@ module.exports.describe = function({testRunner, expect, defaultBrowserOptions, p
       expect(error.message).toContain('Navigation failed because browser has disconnected!');
       await browserServer.close();
     });
-    it('should reject waitForElement when browser closes', async({server}) => {
+    it('should reject waitForSelector when browser closes', async({server}) => {
       server.setRoute('/empty.html', () => {});
       const browserServer = await playwright.launchServer({...defaultBrowserOptions });
       const remote = await playwright.connect({ wsEndpoint: browserServer.wsEndpoint() });
       const page = await remote.newPage();
-      const watchdog = page.waitForElement('div', { timeout: 60000 }).catch(e => e);
+      const watchdog = page.waitForSelector('div', { timeout: 60000 }).catch(e => e);
 
-      // Make sure the previous waitForElement has time to make it to the browser before we disconnect.
-      await page.waitForElement('body');
+      // Make sure the previous waitForSelector has time to make it to the browser before we disconnect.
+      await page.waitForSelector('body');
 
       await remote.close();
       const error = await watchdog;