From 6ca43cf76187a33c62d8822fe363196bc3ebd216 Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <aslushnikov@gmail.com>
Date: Tue, 26 Jun 2018 13:42:50 -0700
Subject: [PATCH] docs(api.md): clarify docs about waitForNavigation (#2788)

---
 docs/api.md       |  2 +-
 lib/Page.js       |  2 +-
 test/page.spec.js | 25 +++++++++++++++----------
 3 files changed, 17 insertions(+), 12 deletions(-)

diff --git a/docs/api.md b/docs/api.md
index 0ff84422..07991ecb 100644
--- a/docs/api.md
+++ b/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:
diff --git a/lib/Page.js b/lib/Page.js
index 78ca2961..87b04190 100644
--- a/lib/Page.js
+++ b/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();
diff --git a/test/page.spec.js b/test/page.spec.js
index b5e20d96..0791527e 100644
--- a/test/page.spec.js
+++ b/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}) => {