feat(api): remove 'mutation' polling option (#2048)

It is not compatible with shadow dom.

Author: dgozman

docs/api.md

@@ -1702,9 +1702,7 @@ is fired.
 - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
 - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction`
 - `options` <[Object]> Optional waiting parameters
-  - `polling` <[number]|"raf"|"mutation"> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
-    - `'raf'` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
-    - `'mutation'` - to execute `pageFunction` on every DOM mutation.
+  - `polling` <[number]|"raf"> If `polling` is `'raf'`, then `pageFunction` is constantly executed in `requestAnimationFrame` callback. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. Defaults to `raf`.
   - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) method.
 - returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
 
@@ -2371,9 +2369,7 @@ Returns frame's url.
 - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
 - `arg` <[Serializable]|[JSHandle]> Optional argument to pass to `pageFunction`
 - `options` <[Object]> Optional waiting parameters
-  - `polling` <[number]|"raf"|"mutation"> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
-    - `'raf'` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
-    - `'mutation'` - to execute `pageFunction` on every DOM mutation.
+  - `polling` <[number]|"raf"> If `polling` is `'raf'`, then `pageFunction` is constantly executed in `requestAnimationFrame` callback. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. Defaults to `raf`.
   - `timeout` <[number]> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout. The default value can be changed by using the [browserContext.setDefaultTimeout(timeout)](#browsercontextsetdefaulttimeouttimeout) or [page.setDefaultTimeout(timeout)](#pagesetdefaulttimeouttimeout) methods.
 - returns: <[Promise]<[JSHandle]>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
 

src/frames.ts

@@ -770,7 +770,7 @@ export class Frame {
     const { polling = 'raf' } = options;
     const deadline = this._page._timeoutSettings.computeDeadline(options);
     if (helper.isString(polling))
-      assert(polling === 'raf' || polling === 'mutation', 'Unknown polling option: ' + polling);
+      assert(polling === 'raf', 'Unknown polling option: ' + polling);
     else if (helper.isNumber(polling))
       assert(polling > 0, 'Cannot poll with non-positive interval: ' + polling);
     else

src/injected/injected.ts

@@ -35,37 +35,6 @@ export class Injected {
     return rect.width > 0 && rect.height > 0;
   }
 
-  private _pollMutation<T>(predicate: Predicate<T>, timeout: number): Promise<T | undefined> {
-    let timedOut = false;
-    if (timeout)
-      setTimeout(() => timedOut = true, timeout);
-
-    const success = predicate();
-    if (success)
-      return Promise.resolve(success);
-
-    let fulfill: (result?: any) => void;
-    const result = new Promise<T | undefined>(x => fulfill = x);
-    const observer = new MutationObserver(() => {
-      if (timedOut) {
-        observer.disconnect();
-        fulfill();
-        return;
-      }
-      const success = predicate();
-      if (success) {
-        observer.disconnect();
-        fulfill(success);
-      }
-    });
-    observer.observe(document, {
-      childList: true,
-      subtree: true,
-      attributes: true
-    });
-    return result;
-  }
-
   private _pollRaf<T>(predicate: Predicate<T>, timeout: number): Promise<T | undefined> {
     let timedOut = false;
     if (timeout)
@@ -113,11 +82,9 @@ export class Injected {
     return result;
   }
 
-  poll<T>(polling: 'raf' | 'mutation' | number, timeout: number, predicate: Predicate<T>): Promise<T | undefined> {
+  poll<T>(polling: 'raf' | number, timeout: number, predicate: Predicate<T>): Promise<T | undefined> {
     if (polling === 'raf')
       return this._pollRaf(predicate, timeout);
-    if (polling === 'mutation')
-      return this._pollMutation(predicate, timeout);
     return this._pollInterval(polling, predicate, timeout);
   }
 

src/types.ts

@@ -39,7 +39,7 @@ export type TimeoutOptions = { timeout?: number };
 
 export type WaitForElementOptions = TimeoutOptions & { waitFor?: 'attached' | 'detached' | 'visible' | 'hidden' };
 
-export type Polling = 'raf' | 'mutation' | number;
+export type Polling = 'raf' | number;
 export type WaitForFunctionOptions = TimeoutOptions & { polling?: Polling };
 
 export type LifecycleEvent = 'load' | 'domcontentloaded' | 'networkidle';

test/waittask.spec.js

@@ -52,14 +52,9 @@ describe('Frame.waitForFunction', function() {
     }, {}, {polling});
     expect(timeDelta).not.toBeLessThan(polling);
   });
-  it('should poll on mutation', async({page, server}) => {
-    let success = false;
-    const watchdog = page.waitForFunction(() => window.__FOO === 'hit', {}, {polling: 'mutation'})
-        .then(() => success = true);
-    await page.evaluate(() => window.__FOO = 'hit');
-    expect(success).toBe(false);
-    await page.evaluate(() => document.body.appendChild(document.createElement('div')));
-    await watchdog;
+  it('should throw on polling:mutation', async({page, server}) => {
+    const error = await page.waitForFunction(() => true, {}, {polling: 'mutation'}).catch(e => e);
+    expect(error.message).toBe('Unknown polling option: mutation');
   });
   it('should poll on raf', async({page, server}) => {
     const watchdog = page.waitForFunction(() => window.__FOO === 'hit', {}, {polling: 'raf'});