docs(api.md): clarify docs about waitForNavigation (#2788)

docs/api.md

@@ -1556,7 +1556,7 @@ Shortcut for [page.mainFrame().waitForFunction(pageFunction[, options[, ...args]
     - `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
     - `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
     - `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
-- returns: <[Promise]<[Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
+- returns: <[Promise]<[?Response]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
 
 This resolves when the page navigates to a new URL or reloads. It is useful for when you run code
 which will indirectly cause the page to navigate. Consider this example:

lib/Page.js

@@ -616,7 +616,7 @@ class Page extends EventEmitter {
 
   /**
    * @param {!Object=} options
-   * @return {!Promise<!Puppeteer.Response>}
+   * @return {!Promise<?Puppeteer.Response>}
    */
   async waitForNavigation(options = {}) {
     const mainFrame = this._frameManager.mainFrame();

test/page.spec.js

@@ -708,10 +708,11 @@ module.exports.addTests = function({testRunner, expect, puppeteer, DeviceDescrip
     it('should work with clicking on anchor links', async({page, server}) => {
       await page.goto(server.EMPTY_PAGE);
       await page.setContent(`<a href='#foobar'>foobar</a>`);
-      await Promise.all([
+      const [response] = await Promise.all([
+        page.waitForNavigation(),
         page.click('a'),
-        page.waitForNavigation()
       ]);
+      expect(response).toBe(null);
       expect(page.url()).toBe(server.EMPTY_PAGE + '#foobar');
     });
     it('should work with history.pushState()', async({page, server}) => {
@@ -722,10 +723,11 @@ module.exports.addTests = function({testRunner, expect, puppeteer, DeviceDescrip
           function pushState() { history.pushState({}, '', 'wow.html') }
         </script>
       `);
-      await Promise.all([
+      const [response] = await Promise.all([
+        page.waitForNavigation(),
         page.click('a'),
-        page.waitForNavigation()
       ]);
+      expect(response).toBe(null);
       expect(page.url()).toBe(server.PREFIX + '/wow.html');
     });
     it('should work with history.replaceState()', async({page, server}) => {
@@ -736,10 +738,11 @@ module.exports.addTests = function({testRunner, expect, puppeteer, DeviceDescrip
           function replaceState() { history.replaceState({}, '', '/replaced.html') }
         </script>
       `);
-      await Promise.all([
+      const [response] = await Promise.all([
+        page.waitForNavigation(),
         page.click('a'),
-        page.waitForNavigation()
       ]);
+      expect(response).toBe(null);
       expect(page.url()).toBe(server.PREFIX + '/replaced.html');
     });
     it('should work with DOM history.back()/history.forward()', async({page, server}) => {
@@ -755,15 +758,17 @@ module.exports.addTests = function({testRunner, expect, puppeteer, DeviceDescrip
         </script>
       `);
       expect(page.url()).toBe(server.PREFIX + '/second.html');
-      await Promise.all([
+      const [backResponse] = await Promise.all([
+        page.waitForNavigation(),
         page.click('a#back'),
-        page.waitForNavigation()
       ]);
+      expect(backResponse).toBe(null);
       expect(page.url()).toBe(server.PREFIX + '/first.html');
-      await Promise.all([
+      const [forwardResponse] = await Promise.all([
+        page.waitForNavigation(),
         page.click('a#forward'),
-        page.waitForNavigation()
       ]);
+      expect(forwardResponse).toBe(null);
       expect(page.url()).toBe(server.PREFIX + '/second.html');
     });
     it('should work when subframe issues window.stop()', async({page, server}) => {