Rename page.evaluateOnInitialized into page.evaluateOnNewDocument

This patch renames page.evaluateOnInitialized into
page.evaluateOnNewDocument to better align with the protocol and with
what the method is actually doing.

Fixes #119.

docs/api.md

@@ -32,7 +32,7 @@
     + [page.click(selector[, options])](#pageclickselector-options)
     + [page.close()](#pageclose)
     + [page.evaluate(pageFunction, ...args)](#pageevaluatepagefunction-args)
-    + [page.evaluateOnInitialized(pageFunction, ...args)](#pageevaluateoninitializedpagefunction-args)
+    + [page.evaluateOnNewDocument(pageFunction, ...args)](#pageevaluateonnewdocumentpagefunction-args)
     + [page.focus(selector)](#pagefocusselector)
     + [page.frames()](#pageframes)
     + [page.goBack(options)](#pagegobackoptions)
@@ -374,12 +374,16 @@ Adds a `<script></script>` tag to the page with the desired url. Alternatively,
 
 This is a shortcut for [page.mainFrame().evaluate()](#frameevaluatefun-args) method.
 
-#### page.evaluateOnInitialized(pageFunction, ...args)
+#### page.evaluateOnNewDocument(pageFunction, ...args)
 - `pageFunction` <[function]> Function to be evaluated in browser context
 - `...args` <...[string]> Arguments to pass to `pageFunction`
 - returns: <[Promise]<[Object]>> Promise which resolves to function
 
-`page.evaluateOnInitialized` adds a function which would run on every page navigation before any page's javascript. This is useful to amend javascript environment, e.g. to seed [Math.random](https://github.com/GoogleChrome/puppeteer/blob/master/examples/unrandomize.js)
+Adds a function which would be invoked in one of the following scenarios:
+- whenever the page gets navigated
+- whenever the child frame gets attached or navigated. In this case, the function gets invoked in the context of the newly attached frame
+
+The function is invoked after the document was created but before any of its scripts were run. This is useful to amend javascript environment, e.g. to seed [Math.random](https://github.com/GoogleChrome/puppeteer/blob/master/examples/unrandomize.js)
 
 #### page.focus(selector)
 - `selector` <[string]> A query selector of element to focus. If there are multiple elements satisfying the selector, the first will be focused.

examples/detectsniff.js

@@ -26,7 +26,7 @@ console.log('Checking ' + address + '...');
 
 var browser = new Browser();
 browser.newPage().then(async page => {
-    await page.evaluateOnInitialized(function() {
+    await page.evaluateOnNewDocument(function() {
         (function () {
             var userAgent = window.navigator.userAgent,
                 platform = window.navigator.platform;

examples/unrandomize.js

@@ -18,7 +18,7 @@ var Browser = require('../lib/Browser');
 var browser = new Browser();
 
 browser.newPage().then(async page => {
-    await page.evaluateOnInitialized(function() {
+    await page.evaluateOnNewDocument(function() {
         Math.random = () => 42 / 100;
     });
     var result = await page.navigate('http://ariya.github.com/js/random/');

lib/Page.js

@@ -368,7 +368,7 @@ class Page extends EventEmitter {
    * @param {!Array<*>} args
    * @return {!Promise}
    */
-  async evaluateOnInitialized(pageFunction, ...args) {
+  async evaluateOnNewDocument(pageFunction, ...args) {
     let scriptSource = helper.evaluationString(pageFunction, ...args);
     await this._client.send('Page.addScriptToEvaluateOnLoad', { scriptSource });
   }

phantom_shim/WebPage.js

@@ -536,7 +536,7 @@ class WebPage {
    */
   evaluate(fun, ...args) {
     if (this._deferEvaluate)
-      return await(this._page.evaluateOnInitialized(fun, ...args));
+      return await(this._page.evaluateOnNewDocument(fun, ...args));
     return await(this._currentFrame.evaluate(fun, ...args));
   }
 

test/test.js

@@ -238,7 +238,7 @@ describe('Puppeteer', function() {
     }));
 
     it('should throw if evaluation failed', SX(async function() {
-      await page.evaluateOnInitialized(function() {
+      await page.evaluateOnNewDocument(function() {
         document.querySelector = null;
       });
       await page.navigate(EMPTY_PAGE);
@@ -1160,9 +1160,9 @@ describe('Puppeteer', function() {
     }));
   });
 
-  describe('Page.evaluateOnInitialized', function() {
+  describe('Page.evaluateOnNewDocument', function() {
     it('should evaluate before anything else on the page', SX(async function() {
-      await page.evaluateOnInitialized(function(){
+      await page.evaluateOnNewDocument(function(){
         window.injected = 123;
       });
       await page.navigate(PREFIX + '/tamperable.html');