TestCafe Mobile Browser Testing: Emulation and Real Devices

TestCafe Mobile Browser Testing: Emulation and Real Devices

Most web apps need to work on mobile. TestCafe supports mobile testing through three mechanisms: Chrome/Firefox device emulation, real device testing via cloud providers like BrowserStack and Sauce Labs, and localhost tunneling for testing local builds on real hardware.

This guide covers all three approaches with practical configuration for each.

Chrome Device Emulation

The fastest mobile testing path is Chrome's built-in device emulation. No extra hardware, no cloud accounts — just a flag:

testcafe "chrome:emulation:device=iPhone X" tests/

Chrome emulates the specified device's viewport, device pixel ratio, user agent, and touch events.

Available Devices

Chrome supports all devices in Chrome DevTools' device list:

# Common mobile targets
testcafe "chrome:emulation:device=iPhone 12" tests/
testcafe "chrome:emulation:device=iPhone SE" tests/
testcafe "chrome:emulation:device=Pixel 5" tests/
testcafe "chrome:emulation:device=Samsung Galaxy S21" tests/
testcafe "chrome:emulation:device=iPad" tests/
testcafe "chrome:emulation:device=iPad Pro" tests/

Device names must match Chrome's internal list. Use DevTools → Device toolbar → device dropdown to find exact names.

Custom Viewport

For custom dimensions without a preset device:

testcafe "chrome:emulation:width=390,height=844,mobile=true,touch=true" tests/

Parameters:

  • width, height — viewport dimensions in pixels
  • mobile — enables mobile UA and meta-viewport handling
  • touch — enables touch events (important for gesture tests)
  • deviceScaleFactor — pixel density multiplier

Headless Emulation for CI

testcafe "chrome:headless:emulation:device=iPhone 12" tests/

Combine :headless and :emulation: in the browser string. Order matters — :headless first, then :emulation:.

Config File

// .testcaferc.js
module.exports = {
  browsers: [
    'chrome:headless:emulation:device=iPhone 12',
    'chrome:headless:emulation:device=iPad',
  ],
  src: ['tests/**/*.test.js'],
};

Running both in one command tests two viewport sizes in parallel:

testcafe "chrome:headless:emulation:device=iPhone 12,chrome:headless:emulation:device=iPad" tests/

Writing Viewport-Aware Tests

Checking Responsive Behavior

import { Selector, ClientFunction } from 'testcafe';

const getViewport = ClientFunction(() => ({
  width: window.innerWidth,
  height: window.innerHeight,
}));

test('Mobile nav is visible on small screens', async t => {
  const viewport = await getViewport();
  
  if (viewport.width < 768) {
    // Mobile layout
    await t.expect(Selector('.hamburger-menu').visible).ok('Hamburger should show on mobile');
    await t.expect(Selector('.desktop-nav').visible).notOk('Desktop nav should be hidden');
  } else {
    // Desktop layout
    await t.expect(Selector('.desktop-nav').visible).ok();
  }
});

Touch Event Testing

Touch events require the device emulation to have touch enabled. With that set:

test('Swipe carousel', async t => {
  const carousel = Selector('.carousel');
  
  // Drag to simulate swipe
  await t.drag(carousel, -300, 0);
  
  await t.expect(Selector('.carousel-slide.active').nth(1).exists).ok();
});

For tap events, t.click() works on touch-enabled emulation — it dispatches touch events when the device has touch enabled.

Scroll Testing

Mobile scroll behavior differs from desktop:

const scrollTo = ClientFunction((x, y) => window.scrollTo(x, y));

test('Sticky header stays visible while scrolling', async t => {
  await scrollTo(0, 500);
  await t.expect(Selector('header.sticky').visible).ok();
  
  await scrollTo(0, 2000);
  await t.expect(Selector('header.sticky').visible).ok();
});

Testing Bottom Navigation

Fixed elements at the bottom of mobile viewports need scroll context:

test('Bottom nav is not covered by content', async t => {
  const bottomNav = Selector('.bottom-navigation');
  const rect = await bottomNav.boundingClientRect;
  const viewport = await getViewport();
  
  // Bottom nav should be at the bottom of the screen
  await t.expect(rect.bottom).lte(viewport.height);
  await t.expect(bottomNav.visible).ok();
});

Testing Multiple Viewports

Run the same tests across multiple viewport sizes to catch responsive breakpoint issues:

// helpers/viewports.js
export const viewports = [
  { name: 'mobile', width: 375, height: 812 },
  { name: 'tablet', width: 768, height: 1024 },
  { name: 'desktop', width: 1440, height: 900 },
];

// tests/responsive.test.js
import { viewports } from '../helpers/viewports';
import { ClientFunction } from 'testcafe';

const setViewport = ClientFunction((width, height) => {
  // This won't actually resize the browser window — use emulation flags instead
  // Use this to check current viewport and make conditional assertions
});

Note: You can't resize the browser window from test code in TestCafe — viewport is set at browser startup via emulation flags. For multi-viewport coverage, run the same test file with different browser configurations:

# In package.json
"test:mobile": "testcafe 'chrome:headless:emulation:device=iPhone 12' tests/",
"test:tablet": "testcafe 'chrome:headless:emulation:device=iPad' tests/",
"test:desktop": "testcafe chrome:headless tests/",
"test:all-viewports": "npm run test:mobile && npm run test:tablet && npm run test:desktop"

Real Device Testing with BrowserStack

Chrome emulation catches most issues, but real devices surface WebKit differences (Safari on iOS) and actual hardware behavior.

BrowserStack Configuration

Install the TestCafe BrowserStack plugin:

npm install testcafe-browser-provider-browserstack

Set credentials:

export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_key

Run on a real device:

testcafe "browserstack:iPhone 14@16" tests/

The format is browserstack:deviceName@osVersion.

Finding Available Devices

testcafe --list-browsers browserstack

Returns all available device/browser combinations.

BrowserStack Config in .testcaferc

module.exports = {
  browsers: [
    'browserstack:iPhone 14@16',
    'browserstack:Samsung Galaxy S23@13.0',
    'browserstack:iPad Pro 12.9 2022@16',
  ],
  concurrency: 3,
};

Set BROWSERSTACK_BUILD_ID environment variable for grouping runs in the BrowserStack dashboard:

BROWSERSTACK_BUILD_ID=my-pr-123 npx testcafe ...

Real Device Testing with Sauce Labs

npm install testcafe-browser-provider-saucelabs
export SAUCE_USERNAME=your_username
export SAUCE_ACCESS_KEY=your_key

testcafe "saucelabs:iPhone Simulator@iOS 16.0" tests/

Local Builds on Real Devices

To test a locally running app on a real device, use TestCafe's built-in remote testing feature:

testcafe remote tests/ --hostname your-machine-ip

TestCafe prints a URL like http://192.168.1.100:1337/.... Open that URL on your real device. The test runs in your device's native browser.

Automated Remote Testing

For CI with real devices connected to the machine:

# Detect connected iOS device (requires xcrun)
DEVICE_COUNT=$(xcrun simctl list devices booted | grep -c "Booted")

testcafe remote --qr-code tests/

For automated device connections, the BrowserStack or Sauce Labs providers are more reliable than managing physical device connections in CI.

Common Mobile Test Issues

Touch vs Click Events

Some apps listen to touchstart/touchend rather than click. With touch emulation enabled, t.click() dispatches both — but if only touchstart is handled, the interaction may not trigger correctly. Use t.drag() with zero distance to simulate a tap that only dispatches touch events:

// If t.click() doesn't work on a touch-only handler:
await t.drag(Selector('#touch-button'), 0, 0);

Viewport Meta Tag

If emulation produces unexpected results, check that your app's <meta name="viewport"> tag is set correctly. Without it, mobile browsers apply their own viewport scaling:

<meta name="viewport" content="width=device-width, initial-scale=1">

You can verify:

const viewportMeta = await t.eval(() => {
  const meta = document.querySelector('meta[name="viewport"]');
  return meta ? meta.getAttribute('content') : null;
});
console.log('Viewport meta:', viewportMeta);

Font Size on Mobile

Mobile browsers auto-adjust font size to improve readability. This can cause text to appear in unexpected sizes and affect layout assertions. Disable with CSS: -webkit-text-size-adjust: none in your app during tests, or use screenshot assertions to catch visual regressions rather than pixel-specific size assertions.

Continuous Mobile Testing

Mobile regressions are especially common because:

  1. Mobile layout changes break independently of desktop layout
  2. OS/browser updates change touch behavior subtly
  3. Mobile network conditions expose race conditions

Running mobile tests on a schedule with HelpMeTest catches regressions between deployments without relying on team members to manually test on devices. Pair scheduled mobile tests with real-device coverage on BrowserStack for production-confidence testing.

Summary

TestCafe mobile testing starts with Chrome device emulation for fast, local feedback. Add BrowserStack or Sauce Labs for real-device coverage of iOS Safari and Android Chrome. Use t.drag() for touch-specific interactions, and structure responsive tests to run the same test files across multiple browser configurations rather than branching inside tests.

The most common mobile-specific failures — broken responsive layouts, touch handler issues, and viewport scaling — are all caught by basic emulation testing in CI before they reach users.

Read more

Start now free