Mobile Emulation

Chrome allows users to emulate Chrome on a mobile device (e.g. a “Nexus 7” tablet, or an “iPhone 5”) from the desktop version of Chrome, by enabling the Mobile Emulation feature in Chrome DevTools. This feature speeds up web development, allows developers to quickly test how a website will render in a mobile device, without requiring a real device. ChromeDriver can also enable Mobile Emulation, via the “mobileEmulation” capability, specified with a dictionary value.


Just as in the DevTools Emulation panel, there are two ways in ChromeDriver to enable Mobile Emulation: by specifying a known device, or by specifying individual device attributes. The format of the “mobileEmulation” dictionary depends on which method is desired.

Specifying a Known Mobile Device

To enable Mobile Emulation with a specific device name, the “mobileEmulation” dictionary must contain a “deviceName.” Use a valid device name from the DevTools Emulation panel as the value for “deviceName.”


Java

Map<String, String> mobileEmulation = new HashMap<String, String>();

mobileEmulation.put("deviceName", "Nexus 5");


Map<String, Object> chromeOptions = new HashMap<String, Object>();

chromeOptions.put("mobileEmulation", mobileEmulation);

DesiredCapabilities capabilities = DesiredCapabilities.chrome();

capabilities.setCapability(ChromeOptions.CAPABILITY, chromeOptions);

WebDriver driver = new ChromeDriver(capabilities);

Ruby

mobile_emulation = { "deviceName" => "Nexus 5" }

caps = Selenium::WebDriver::Remote::Capabilities.chrome(

   "chromeOptions" => { "mobileEmulation" => mobile_emulation })

driver = Selenium::WebDriver.for :remote, url: 'http://localhost:4444/wd/hub', desired_capabilities: caps

Python

from selenium import webdriver

mobile_emulation = { "deviceName": "Nexus 5" }

chrome_options = webdriver.ChromeOptions()

chrome_options.add_experimental_option("mobileEmulation", mobile_emulation)

driver = webdriver.Remote(command_executor='http://127.0.0.1:4444/wd/hub',

                         desired_capabilities = chrome_options.to_capabilities())


Note: ChromeDriver’s list of known devices is generated from those found in the DevTools Emulation panel. However, it is possible to use a version of ChromeDriver against a version of Chrome that has a newer or older list of devices. If you try to use a device name that ChromeDriver doesn’t recognize, you will see an error: “<your device name> must be a valid device.” To emulate a device that ChromeDriver doesn’t know of, enable Mobile Emulation using individual device metrics, as described below.

Specifying Individual Device Attributes

It is also possible to enable Mobile Emulation by specifying individual attributes. To enable Mobile Emulation this way, the “mobileEmulation” dictionary can contain a “deviceMetrics” dictionary and a “userAgent” string. The following device metrics must be specified in the “deviceMetrics” dictionary:

  • “width” - the width in pixels of the device’s screen

  • “height” - the height in pixels of the device’s screen

  • “pixelRatio” - the device’s pixel ratio

  • "touch" - whether to emulate touch events (defaults to true, usually does not need to be set)


The phones and tablets that are available under the Mobile Emulation panel can be found in the DevTools source code.

Java

Map<String, String> deviceMetrics = new HashMap<String, Object>();

deviceMetrics.put("width", 360);

deviceMetrics.put("height", 640);

deviceMetrics.put("pixelRatio", 3.0);

Map<String, String> mobileEmulation = new HashMap<String, String>();


mobileEmulation.put("deviceMetrics", deviceMetrics);

mobileEmulation.put("userAgent", "Mozilla/5.0 (Linux; Android 4.2.1; en-us; Nexus 5 Build/JOP40D) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.166 Mobile Safari/535.19");


Map<String, Object> chromeOptions = new Map<String, Object>();

chromeOptions.put("mobileEmulation", mobileEmulation);

DesiredCapabilities capabilities = DesiredCapabilities.chrome();

capabilities.setCapability(ChromeOptions.CAPABILITY, chromeOptions);

WebDriver driver = new ChromeDriver(capabilities);

Ruby

mobile_emulation = {

   "deviceMetrics" => { "width" => 360, "height" => 640, "pixelRatio" => 3.0 },

   "userAgent" => "Mozilla/5.0 (Linux; Android 4.2.1; en-us; Nexus 5 Build/JOP40D) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.166 Mobile Safari/535.19"

}


caps = Selenium::WebDriver::Remote::Capabilities.chrome("chromeOptions" => mobile_emulation)

driver = Selenium::WebDriver.for :remote, url: 'http://localhost:4444/wd/hub', desired_capabilities: caps

Python

from selenium import webdriver

from selenium.webdriver.chrome.options import Options

mobile_emulation = {

   "deviceMetrics": { "width": 360, "height": 640, "pixelRatio": 3.0 },

   "userAgent": "Mozilla/5.0 (Linux; Android 4.2.1; en-us; Nexus 5 Build/JOP40D) AppleWebKit/535.19 (KHTML, like Gecko) Chrome/18.0.1025.166 Mobile Safari/535.19" }

chrome_options = Options()

chrome_options.add_experimental_option("mobileEmulation", mobile_emulation)

driver = webdriver.Chrome(chrome_options = chrome_options)

Differences between mobile emulation and real devices

Testing a mobile website on a desktop using mobile emulation can be useful, but testers should be aware that there are many subtle differences such as:

  • entirely different GPU, which may lead to big performance changes;
  • mobile UI is not emulated (in particular, the hiding url bar affects page height);
  • disambiguation popup (where you select one of a few touch targets) is not supported;
  • many hardware APIs (for example, orientationchange event) are unavailable.