devtools-docs/docs/mobile-emulation.html

{{+bindTo:partials.standard_devtools_article}}
<h1>Mobile emulation</h1>

<p>The mobile web has evolved to enable increasingly sophisticated applications,
which we often wish to debug during development on the desktop. The DevTools
include support for a number of features that can help with this which we will
walk through in this section.</p>


<p class="note"><b>Note</b>: Some of our documentation may be ahead of the stable version of Chrome. If you are unable to locate a feature listed, we recommend trying <a href="https://www.google.com/intl/en/chrome/browser/canary.html">Chrome Canary</a> which contains the latest version of the DevTools.</p>

<div class="collapsible">
<h2 id="enable-emulation-panel">Enabling the Emulation Panel</h2>

<p><a href="https://www.google.com/intl/en/chrome/browser/canary.html" title="Chrome Canary">Chrome Canary</a> has received a number of improved mobile emulation tools which can be accessed by enabling the Emulation panel through the Settings panel. To enable:</p>

<ol>
  <li>Open the Settings panel within the DevTools.</li>
  <li>Enable "Show 'Emulation' view in console drawer."</li>
</ol>

<p><div class="screenshot"><img width="330" src="mobile-emulation/enable-emulation.png" alt="Enabling emulation"/></div></p>

<p>Bring up the DevTools console drawer by hitting the <span class="kbd">Esc</span> key and then select the Emulation panel.</p>

<p><div class="screenshot"><img width="468" src="mobile-emulation/emulation-panel.png" alt="Emulation panel"/></div></p>

<p class="note"><b>Note</b>: Emulation tools within DevTools were previously contained within an <strong>Overrides</strong> pane inside the Settings panel. The Emulation panel is the new Overrides pane.</p>



</div>
<div class="collapsible">
<h2 id="emulate-devices">Emulating Devices</h2>

<p>It's often easier to start prototyping on the desktop and then tackle the
mobile-specific parts on the devices you intend to support. Device emulation can
make this process more straightforward.</p>

<iframe width="640" height="360" src="//www.youtube.com/embed/z7sTRdSpA04" frameborder="0" allowfullscreen=""></iframe>

<p>DevTools contains built in presets for a number of devices, this allows you to emulate and debug mobile viewport issues like CSS media query breakpoints. Selecting a device preset automatically enables a number of settings:</p>

<ul>
  <li><strong>User agent</strong> - a string available at <code>navigator.userAgent</code> and also sent as a request header for page resources. See <a href="#useragent-spoofing">Useragent Spoofing</a>.</li>
  <li><strong>Screen resolution</strong> - matches the actual dimensions (width and height) of the selected device. For example, selecting the Nexus S will emulate a resolution of 480x800.</li>
  <li><strong>Device Pixel Ratio</strong> - matches the DPR of the selected device. Allows emulation of a retina device from a non-retina machine. This also means media queries such as <code>@media only screen and (min-device-pixel-ratio: 2)</code> can be tested.</li>
  <li><strong>Emulate viewport</strong> - zooms the page out to the physical default viewport of that device. In the case of the Nexus 4 this is 768x1280. </li>
  <li><strong>Text autosizing</strong> - emulate font boosting which occurs on mobile devices.</li>
    <li><strong>Android font metrics</strong> - Android artificially increases the font metrics used by text autosizing based on the system settings and screen size. Enabled by default only when emulating an Android device.</li>
  <li><strong>Touch screen</strong> (part of the Sensors pane) - uses touch events, see <a href="#emulate-touch-events">Emulating Touch Events</a>.</li>
</ul>

<p><div class="screenshot"><img width="746" src="mobile-emulation/viewport-emulation.gif" alt="Viewport emulation"/></div></p>



<p>Emulate a device via a preset using the following steps:</p>

<ol>
  <li>Open the Emulation panel within the DevTools</li>
  <li>With the Device pane selected, select "Google Nexus S".</li>
  <li>Click Emulate.</li>
</ol>

<p><div class="screenshot"><img width="550" src="mobile-emulation/image_3.png" alt="Viewport Overrides"/></div></p>

<p>You are now in device emulation mode. The Screen, User Agent, and Sensors panes reflect the device settings which are now enabled. </p>

<p><div class="screenshot"><img width="375" src="mobile-emulation/device_metrics.png" alt="Viewport Overrides"/></div></p>

<h4>Notes</h4>
<ul>
  <li>The <strong>Swap dimensions</strong> button in between the <em>Resolution</em> values (<img src="mobile-emulation/image_6.png"/>) will swap the width and height.</li>
  <li><b>Shrink to fit</b> ensures the emulated device screen is completely visible within your browser window. This setting does not emulate the device differently.</li>
  <li>Device media queries (e.g <code>@media only screen and (min-device-width:768px)</code>) will be enabled according to the values defined in the Resolution settings.</li>
  <li>You may want to undock DevTools or dock it to the right while working with emulated viewport settings.
  <li>Device settings can be configured independently of a device preset.</li>
  <li>If you would like to contribute patches to support new device presets, please see our <a href="contributing.md">contribution docs</a>.</li>
</ul>

</div>
<div class="collapsible">
<h2 id="emulate-touch-events">Emulating Touch Events</h2>

<p>Touch is an input method that's difficult to test on the desktop, since most
desktops don't have touch input. Having to test on mobile can lengthen your
development cycle, since every change you make needs to be pushed out to a
server and then loaded on the device.</p>

<p>A solution to this problem is to simulate touch events on your development
machine. For single-touches, the Chrome DevTools supports single<a href="http://www.w3.org/TR/touch-events/">
</a><a href="http://www.w3.org/TR/touch-events/">touch
event</a> emulation to make it easier to debug
mobile applications on the desktop.</p>

<p><strong>To enable support for touch event emulation:</strong></p>

<ol>
<li>Open the Emulation panel in the DevTools.</li>
<li>Enable "Emulate touch screen" in the Sensors pane.</li>
</ol>

<div class="screenshot"><img width="480" src="mobile-emulation/image_0.png" alt="Emulating touch events in the Overrides panel"/></img></div>

<p>Your mouse actions will now also trigger the relevant touch events: <code>touchstart</code>, <code>touchmove</code> and <code>touchend</code>.</p>

<h4>Notes</h4>

<ul>
<li>Feature detects such as <code><a href="http://modernizr.com">Modernizr.touch</a></code> will now
succeed on page refresh.</li>
<li>This feature, like many other overrides, will only work while the DevTools are open.</li>
<li>The cursor will change to a small circle to emulate a fingertip size.</li>
<li>Use <span class="kbd">Shift</span> + Drag to emulate a "pinch".</li>
<li>Enabling "Emulate touch screen" does not disable mouse events entirely, as they are fired on touch devices. Try this <a href="http://patrickhlauke.github.io/touch/tests/event-listener.html">touch event listener test page</a>, touch is another option we can debug with.</li>
<li>On click, the order of events fired is currently: <code>touchstart > mousedown > touchmove > touchend > mouseup > click</code>. On touch devices, this order is slightly different. The tools will shortly be <a href="https://code.google.com/p/chromium/issues/detail?id=181204">updated with the right order.</li>
<li><code>elem.ontouch<i>*</i></code> handlers will currently <a href="https://code.google.com/p/chromium/issues/detail?id=133915">not fire</a> with this feature. Use the <code>--touch-events</code> <a href="http://www.chromium.org/developers/how-tos/run-chromium-with-flags">command line flag</a> to let Chrome trigger these handlers.
</ul>
<div class="screenshot"><img width="495" src="mobile-emulation/scrolling-emulation.gif" alt="Emulating pinch to zoom"/></img></div>

<p><strong>Debugging touch events</strong></p>

<ol>
<li>Open up the<a href="http://paulirish.com/demo/multi"> </a><a href="http://paulirish.com/demo/multi">Canvas Fingerpaint
Demo</a></li>
<li>Navigate to the Sources panel</li>
<li>Expand the "Event Listener Breakpoints" sub-panel</li>
<li>Check the "touchstart" and "touchmove" events under "Touch"</li>
<li>Move your cursor over the paint area</li>
<li>The debugger should successfully pause on the <span class=
  "source-code">draw()</span> method</li>
</ol>


<p><div class="screenshot"><img width="700" src="mobile-emulation/image_2.png" alt="Debugging touch events"/></div></p>

You may also monitor touch events as they fire on an element in the console. Use <a href="commandline-api.md#monitoreventsobject-events"><code>monitorEvents</code> from the command line API</a>:

<pre class="prettyprint"><code>monitorEvents(document.body, 'touch')</code></pre>


<p><strong>Multi-touch</strong></p>

<p>Multi-touch events can be simulated if you have a device with touch input, such
as a modern Apple MacBook. For further assistance with multi-touch event
simulation, see the "Developer tools" chapter of the <a href="http://www.html5rocks.com/en/mobile/touch/"><b>Multi-touch web
development</b> guide on HTML5 Rocks</a>.</p>



</div>
<div class="collapsible">
<h2 id="useragent-spoofing">Useragent Spoofing</h2>


<p><strong>Emulating The User Agent</strong></p>

<ol>
<li>Navigate to the <a href="http://www.google.com">Google</a> homepage.</li>
<li>In the DevTools, open up the User Agent pane within the Emulation panel.</li>
<li>Check "Spoof user agent" and select "Android 2.3 - Nexus S".</li>
<li>Refresh the page.</li>
</ol>

<p>An updated user-agent field is now sent as part of the request headers for page resources. Some websites may decide to serve optimized versions of the page depending on the user-agent, this is one case where spoofing a user-agent may be useful.</p>

<table>
<thead>
<tr><th>
Before:
</th><th>
After:
</th></tr>
</thead>
<tbody> <tr>
<td><img style="max-width: 100%" src="mobile-emulation/image_4.png" alt="Before user agent and device metric emulation have been applied"/></td>
<td><img style="max-width: 100%" src="mobile-emulation/image_5.png" alt="After user agent and device metric emulation are applied"/></td>
</tr></tbody>
</table>


</div>
<div class="collapsible">
<h2 id="network-throttling">Network Bandwidth Throttling</h2>


<p>The DevTools does not currently support network throttling, however it's important to understand and test the impact of slower connections on your site.

 <p> On Mac, we recommend using the <a href="http://nshipster.com/network-link-conditioner/">Network Link Conditioner</a> that is available via <a href="https://developer.apple.com/xcode/">Xcode</a>. It has presets for network conditions like EDGE, 3G, DSL, WiFi, High Latency DNS, Very Bad Network, and 100% Loss. Changes made within Network Link Conditioner will affect all system network traffic, including Chrome or any running emulators and simulators.</p>

<img src="mobile-emulation/network-link-conditioner-system-preference.png" alt="Network Link Conditioner preference panel" style="max-height: 300px">

 <p>On Windows, we recommend using <a href="http://jagt.github.io/clumsy/index.html">Clumsy</a>, which can add extra lag, drop packets, throttle and manipulate other network conditions.</p>

<img src="http://jagt.github.io/clumsy/clumsy-demo.gif" alt="Clumsy Options" style="max-height: 300px">

<p>On Linux, there are many options for traffic shaping; <a href="http://info.iet.unipi.it/~luigi/dummynet/">dummynet</a> is the recommended option. </p>

</div>
<div class="collapsible">
<h2 id="device-geolocation-overrides">Geolocation Overrides</h2>

<p>When working with HTML5 geolocation support in an application, it can be useful
to debug the output received when using different values for longitude and
latitude. The DevTools support both overriding position values for <em>navigator.geolocation
</em>and simulating geolocation not being available via the Sensors pane.</p>

<p><strong>Overriding geolocation positions</strong></p>

<ol>
<li>Navigate to the <a href="http://html5demos.com/geo">Geolocation</a> demo and allow the page access to your position.</li>
<li>In the DevTools, open up the Sensors pane within the Emulation panel.</li>
<li>Check "Emulate geolocation coordinates" and enter 41.4949819 in the Lat field and -0.1461206 in the Lon field.</li>
</ol>


<p><div class="screenshot"><img src="mobile-emulation/image_11.png"/></div></p>

<ol start="4">
<li>Refresh the page. The demo will now use your overridden position for geolocation.</li>
</ol>


<p><div class="screenshot"><img src="mobile-emulation/image_12.png"/></div></p>

<ol start="5">
<li>Check the "Emulate position unavailable" option.</li>
<li>Refresh the page. The demo will now inform you that finding your location has failed.</li>
</ol>


<p><div class="screenshot"><img src="mobile-emulation/image_13.png"/></div></p>



</div>
<div class="collapsible">
<h2 id="device-orientation-overrides">Device Orientation Overrides</h2>

<p>Many new mobile devices are now shipping with accelerometers, gyroscopes,
compasses and other hardware designed to determine capture motion and
orientation data. Many web browsers have access to that new hardware,
such as via the <a href="http://dev.w3.org/geo/api/spec-source-orientation">HTML5
DeviceOrientation</a> events.
These events provide developers with information about the orientation, motion
and acceleration of the device.</p>

<p>If your application is taking advantage of device orientation events, it can
also be useful to override the values received by these events during debugging
to avoid the need to test them on a physical mobile device.</p>

<p><strong>Overriding orientation values</strong></p>

<ol>
<li>Navigate to the<a href="http://www.html5rocks.com/en/tutorials/device/orientation/deviceorientationsample.html">
</a><a href="http://www.html5rocks.com/en/tutorials/device/orientation/deviceorientationsample.html">Device
Orientation</a> demo and notice the standard HTML5 logo along with the current orientation
values listed above it.</li>
<li>Open the Emulation panel in the DevTools and click the Sensors pane.</li>
<li>Check "Accelerometer".</li>
<li>You will see three fields:
  <ul>
    <li><b>α</b>: how much the device has been rotated around the z-axis.
    <li><b>β</b>: how much the device is tilted left-to-right.
    <li><b>γ</b>: how much it's tilted front-to-back.</li>
  </ul>
<li>Change the values to the following:

<ol>
<li>α - 0</li>
<li>β - 60</li>
<li>γ - 60</li>
</ol>
</li>
</ol>


<p><div class="screenshot"><img width="401" src="mobile-emulation/image_14.png" alt="Enabling device orientation overrides"/></div></p>

<p>We have altered the left/right tilt and front/back tilt, in this case resulting
in our application being emulated as rotating in a clockwise direction.</p>

<p><div class="screenshot"><img width="369" src="mobile-emulation/image_15.png" alt="Device orientation allows us to emulate the directions a device may be turned" /></div></p>



</div>
<div class="collapsible">
<h2 id="css-media-type-emulation">CSS Media Type Emulation</h2>

<p>CSS media types allow you to apply different styles to a page depending on the
medium it is being used through (e.g print, screen, tv, braille and so on).</p>

<p><strong>Emulating media types</strong></p>

<ol>
<li>Navigate to <a href="http://www.html5rocks.com/en/tutorials/developertools/novdigest/">HTML5 Rocks</a>.</li>
<li>Open the Emulation panel in the DevTools.</li>
<li>Enable "CSS media" on the "Screen" pane and select the "print" media type option from the drop-down
box.</li>
<li>The page will adjust to using a stylesheet for the chosen CSS media type if
one is available.</li>
</ol>


<table>
<thead>
<tr><th>
Before:
</th><th>
After:
</th></tr>
</thead>
<tbody> <tr>
<td><img style="max-width: 100%" src="mobile-emulation/emulatecss_before.jpg" alt="Before enabling CSS media type emulation"/></td>
<td><img style="max-width: 100%" src="mobile-emulation/emulatecss_after.jpg" alt="After enabling CSS media type emulation"/></td>
</tr></tbody>
</table>

</div>
<div class="collapsible">
<h2 id="faq">Frequently Asked Questions</h2>

<p><strong>Q: Do the DevTools supports remote debugging?</strong><br/>
A: Yes. Please see our <a href="remote-debugging.html">remote debugging</a>
documentation for more information.</p>

<p><strong>Q: Can the DevTools emulate lower GPU memory limits or slower CPUs, as found on mobile devices?</strong><br>
A: Currently there is no means within DevTools or Chrome to emulate these characteristics. </p>

</div>
{{/partials.standard_devtools_article}}