From 59d1f850f73c7d0fe38653f39d45f111270e8bac Mon Sep 17 00:00:00 2001
From: Yury Semikhatsky <yurys@chromium.org>
Date: Thu, 16 Apr 2020 10:44:43 -0700
Subject: [PATCH] docs: emulation guide

---
 docs/emulation.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 132 insertions(+)
 create mode 100644 docs/emulation.md

diff --git a/docs/emulation.md b/docs/emulation.md
new file mode 100644
index 0000000000000..526cde196831b
--- /dev/null
+++ b/docs/emulation.md
@@ -0,0 +1,132 @@
+# Device and environment emulation
+Playwright allows overriding various parameters that depend on the device where the browser is running (such as viewport size, touch support, dpr etc.) as well as custom system settings such as locale and timezone. Most of these parameters are configured during context construction but some of them (e.g. viewport size) can be changed for individual pages.
+
+## Emulating popular devices
+Playwright comes with a registry of device parameters for some popular mobile devices. It can be used to simulate browser behavior on a mobile device like this:
+```js
+  const { chromium, devices } = require('playwright');
+  const browser = await chromium.launch();
+
+  const pixel2 = devices['Pixel 2'];
+  const context = await browser.newContext({
+    ...pixel2,
+  });
+```
+All pages created in the context above will share the same device parameters.
+
+#### API reference
+
+- [`playwright.devices`](./api.md#playwrightdevices)
+- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+
+<br/>
+<br/>
+
+## Configuring screen size(viewport), touch support, isMobile ...
+Create a context with custom viewport size:
+```js
+  const context = await browser.newContext({
+    viewport: {
+      width: 1280,
+      height: 1024
+    }
+  });
+```
+Resize viewport for individual pages:
+
+```js
+  await page.setViewportSize({ 'width': 1600, 'height': 1200 });
+```
+
+Emulate custom mobile device _without_ touch support:
+```js
+  const context = await browser.newContext({
+    viewport: {
+      width: 400,
+      height: 900,
+    },
+    deviceScaleFactor: 2,
+    isMobile: true,
+    hasTouch: false
+  });
+```
+
+#### API reference
+
+- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+- [`page.setViewportSize(viewportSize)`](./api.md#pagesetviewportsizeviewportsize)
+
+<br/>
+<br/>
+
+
+## Geolocation
+Create a context with 'geolocation' permissions granted:
+```js
+  const context = await browser.newContext({
+    geolocation: { longitude: 48.858455, latitude: 2.294474 },
+    permissions: ['geolocation']
+  });
+```
+Change the location later:
+
+```js
+  await context.setGeolocation({ longitude: 29.979097, latitude: 31.134256 };
+```
+**Note** you can only change geolocation for all pages in the context.
+
+#### API reference
+
+- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+- [`browserContext.setGeolocation(geolocation)`](./api.md#browsercontextsetgeolocationgeolocation)
+
+<br/>
+<br/>
+
+## Permissions
+Allow all pages in the context to show system notifications:
+```js
+  const context = await browser.newContext({
+    permissions: ['notifications'],
+  });
+```
+
+Grant all pages in the existing context access to current location:
+```js
+  await context.grantPermissions(['geolocation']);
+```
+
+Grant camera and mic access from a specific domain:
+```js
+  await context.grantPermissions(['camera', 'microphone'], {origin: 'https://skype.com'} );
+```
+Revoke all permissions:
+```js
+  await context.clearPermissions();
+```
+
+#### API reference
+
+- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+- [`browserContext.grantPermissions(permissions[][, options])`](./api.md#browsercontextgrantpermissionspermissions-options)
+- [`browserContext.clearPermissions()`](./api.md#browsercontextclearpermissions)
+
+<br/>
+<br/>
+
+## Locale and timzeone
+
+```js
+  const context = await browser.newContext({
+    locale: 'ru-RU',
+    timezoneId: 'Europe/Moscow',
+  });
+```
+
+#### API reference
+
+- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+
+<br/>
+<br/>
+