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 pixelsmobile— enables mobile UA and meta-viewport handlingtouch— 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-browserstackSet credentials:
export BROWSERSTACK_USERNAME=your_username
export BROWSERSTACK_ACCESS_KEY=your_keyRun on a real device:
testcafe "browserstack:iPhone 14@16" tests/The format is browserstack:deviceName@osVersion.
Finding Available Devices
testcafe --list-browsers browserstackReturns 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-saucelabsexport 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-ipTestCafe 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:
- Mobile layout changes break independently of desktop layout
- OS/browser updates change touch behavior subtly
- 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.