From 65b7e8ecc067d0f309c4e8d4adec3a517edc57b5 Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <lushnikov@chromium.org>
Date: Mon, 10 Jun 2019 18:07:24 -0700
Subject: [PATCH] docs(api.md): add notes on race condition in page.setViewport
 (#4319)

Fixes #2755.
---
 docs/api.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/api.md b/docs/api.md
index 0f8933873fa..bd4fbb063d8 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1249,7 +1249,8 @@ Emulates given device metrics and user agent. This method is a shortcut for call
 - [page.setViewport(viewport)](#pagesetviewportviewport)
 
 To aid emulation, puppeteer provides a list of device descriptors which can be obtained via the [`puppeteer.devices`](#puppeteerdevices).
-Below is an example of emulating an iPhone 6 in puppeteer:
+
+`page.emulate` will resize the page. A lot of websites don't expect phones to change size, so you should emulate before navigating to the page.
 
 ```js
 const puppeteer = require('puppeteer');
@@ -1815,6 +1816,18 @@ puppeteer.launch().then(async browser => {
 
 In the case of multiple pages in a single browser, each page can have its own viewport size.
 
+`page.setViewport` will resize the page. A lot of websites don't expect phones to change size, so you should set the viewport before navigating to the page.
+
+```js
+const page = await browser.newPage();
+await page.setViewport({
+  width: 640,
+  height: 480,
+  deviceScaleFactor: 1,
+});
+await page.goto('https://example.com');
+```
+
 #### page.tap(selector)
 - `selector` <[string]> A [selector] to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.
 - returns: <[Promise]>