Introduction
Modern web applications must work seamlessly on desktops, tablets, and smartphones. A website that looks perfect on a laptop may have layout issues, broken navigation, or usability problems on smaller screens. This is where a Playwright Mobile Emulation Tutorial becomes valuable.
Playwright includes powerful built-in mobile device emulation that allows you to simulate popular Android phones, iPhones, iPads, and custom devices without needing physical hardware. Using Playwright Mobile Testing, you can validate responsive layouts, touch interactions, orientation changes, geolocation, permissions, and mobile browser behavior directly from your automation framework.
In this Playwright Mobile Emulation Tutorial, you’ll learn how to emulate mobile devices with TypeScript, configure device profiles, test responsive user interfaces, debug mobile issues, integrate tests into CI/CD pipelines, and apply enterprise automation best practices.
What Is Mobile Emulation in Playwright?
Mobile emulation is the process of simulating a mobile device within a desktop browser. Playwright changes browser characteristics such as:
- Viewport size
- User agent
- Device scale factor
- Touch support
- Mobile browser behavior
This enables realistic testing without requiring actual phones or tablets.
Mobile Testing Workflow
Playwright Test
│
▼
Device Profile
│
▼
Chromium / Firefox / WebKit
│
▼
Responsive Website
│
▼
Assertions & Reports
Although emulation closely matches real devices, it’s still a simulation. For hardware-specific features or performance testing, complement emulation with testing on physical devices.
Why Use Mobile Emulation for Responsive Testing?
Responsive testing ensures your application works correctly across different screen sizes and orientations.
Benefits
- Validate responsive layouts
- Detect CSS issues
- Test mobile navigation menus
- Verify forms on small screens
- Simulate touch interactions
- Reduce testing costs
- Faster execution than physical devices
- Easy integration into CI/CD pipelines
| Desktop Testing | Mobile Emulation |
| Large viewport | Mobile viewport |
| Mouse interaction | Touch interaction |
| Desktop layout | Responsive layout |
| Standard user agent | Mobile user agent |
Prerequisites (Node.js, Playwright, TypeScript, VS Code)
Before starting this Playwright Mobile Emulation Tutorial, install:
- Node.js (LTS version)
- npm
- Playwright
- TypeScript
- Visual Studio Code
Verify Node.js:
node -v
npm -v
Create a Playwright project:
npm init playwright@latest
Choose TypeScript when prompted.
Setting Up a Playwright TypeScript Project
A recommended project structure:
playwright-mobile-project
│
├── tests
├── pages
├── fixtures
├── utils
├── playwright.config.ts
├── package.json
├── tsconfig.json
├── playwright-report
└── test-results
Folder Overview
| Folder | Purpose |
| tests | Test scripts |
| pages | Page Object Model classes |
| fixtures | Shared setup |
| utils | Helper methods |
| playwright-report | HTML reports |
| test-results | Screenshots, videos, traces |
This structure scales well for both small and enterprise automation projects.
Using Built-in Device Descriptors (devices)
Playwright provides predefined device profiles through the devices object.
Example configuration:
import { defineConfig, devices } from ‘@playwright/test’;
export default defineConfig({
projects: [
{
name: ‘iPhone 14’,
use: {
…devices[‘iPhone 14’]
}
}
]
});
Step-by-Step Explanation
- Import devices from Playwright.
- Create a browser project.
- Apply the built-in device profile.
- Playwright automatically configures viewport, user agent, and touch support.
This is the simplest way to start Playwright Device Emulation.
Emulating iPhone, Android, iPad, and Custom Devices
iPhone Example
projects: [
{
name: ‘iPhone 13’,
use: {
…devices[‘iPhone 13’]
}
}
]
Android Example
projects: [
{
name: ‘Pixel 7’,
use: {
…devices[‘Pixel 7’]
}
}
]
iPad Example
projects: [
{
name: ‘iPad Pro 11’,
use: {
…devices[‘iPad Pro 11’]
}
}
]
Custom Device
use: {
viewport: {
width: 390,
height: 844
},
isMobile: true,
hasTouch: true
}
Custom profiles are useful for testing devices that are not included in Playwright’s predefined list.
Testing Responsive Layouts and Viewports
A responsive application should adapt to different screen sizes.
Example:
import { test, expect } from ‘@playwright/test’;
test(‘Verify mobile navigation’, async ({ page }) => {
await page.goto(‘https://example.com’);
await page.getByRole(‘button’, { name: ‘Menu’ }).click();
await expect(
page.getByRole(‘navigation’)
).toBeVisible();
});
What This Test Does
- Opens the application.
- Clicks the mobile menu icon.
- Confirms that the navigation menu becomes visible.
This is a common responsive testing scenario.
Handling Touch Events, Geolocation, Permissions, and Orientation
Touch Support
When using a mobile device profile, touch support is automatically enabled.
Geolocation
use: {
geolocation: {
latitude: 40.7128,
longitude: -74.0060
},
permissions: [‘geolocation’]
}
This allows you to test location-based features.
Permissions
Grant browser permissions:
permissions: [
‘notifications’,
‘geolocation’
]
Landscape Orientation
use: {
viewport: {
width: 844,
height: 390
}
}
Switching viewport dimensions helps validate landscape layouts.
Running Tests Across Multiple Mobile Devices
You can execute the same tests on several devices.
projects: [
{
name:’iPhone 14′,
use:{…devices[‘iPhone 14’]}
},
{
name:’Pixel 7′,
use:{…devices[‘Pixel 7’]}
},
{
name:’iPad Mini’,
use:{…devices[‘iPad Mini’]}
}
]
Execution Flow
Playwright Test
│
┌──────┼──────────┐
▼ ▼ ▼
iPhone Pixel iPad
│
▼
Combined Report
This helps identify device-specific UI issues while keeping a single test suite.
Debugging with Playwright Inspector, Trace Viewer, Screenshots, and Videos
Enable debugging features:
use: {
screenshot:’only-on-failure’,
video:’retain-on-failure’,
trace:’on-first-retry’
}
Useful tools include:
- Playwright Inspector
- Trace Viewer
- HTML Reports
- Screenshots
- Videos
These artifacts simplify troubleshooting when responsive layouts fail.
Integrating Mobile Tests into CI/CD Pipelines
Example GitHub Actions workflow:
name: Mobile Tests
on:
push:
jobs:
test:
runs-on: ubuntu-latest
steps:
– uses: actions/checkout@v4
– uses: actions/setup-node@v4
with:
node-version: 20
– run: npm ci
– run: npx playwright install –with-deps
– run: npx playwright test
This pipeline installs dependencies, downloads browsers, and executes your mobile tests automatically.
The same principles apply when using Jenkins or Azure DevOps.
Enterprise Best Practices for Mobile Automation
- Use built-in Playwright device descriptors whenever possible.
- Keep responsive tests independent and repeatable.
- Use semantic locators such as getByRole().
- Test both portrait and landscape orientations.
- Validate mobile-specific navigation and gestures.
- Capture screenshots and traces for failed tests.
- Run mobile tests in CI/CD pipelines.
- Separate smoke and regression suites.
- Reuse Page Object Models across desktop and mobile tests.
- Test multiple viewport sizes during regression.
Common Mobile Emulation Issues and Troubleshooting
| Problem | Solution |
| Mobile menu not visible | Verify viewport size and responsive breakpoints |
| Wrong device profile | Confirm the correct device descriptor is used |
| Touch events not working | Ensure hasTouch or a mobile device profile is enabled |
| Geolocation not available | Grant geolocation permission |
| Layout differs from a real device | Validate with physical devices for hardware-specific behavior |
| Screenshots missing | Enable screenshots in the Playwright configuration |
| Responsive CSS issues | Inspect media queries and viewport settings |
Real-Time Responsive Testing Project Example
E-Commerce Website
Test scenario:
- Open the home page on an iPhone profile.
- Open the hamburger menu.
- Search for a product.
- Open the product details page.
- Add the item to the cart.
- Verify the cart badge updates.
Additional mobile scenarios include:
- Registration form validation
- Mobile checkout flow
- Sticky header behavior
- Responsive product filters
- Mobile search suggestions
Playwright Mobile Emulation Interview Questions
- What is mobile emulation in Playwright?
- What is the devices object?
- How do you emulate an iPhone?
- How do you emulate an Android device?
- What is a custom viewport?
- What is responsive testing?
- How do you test landscape mode?
- How do you test portrait mode?
- What is hasTouch?
- How do you configure geolocation?
- How do you grant browser permissions?
- What are Playwright projects?
- How do you run tests across multiple devices?
- What is Trace Viewer?
- How do you capture screenshots?
- How do you record videos?
- How do you debug responsive issues?
- How do you integrate mobile tests with CI/CD?
- What are common mobile automation challenges?
- Why use semantic locators?
- What is the difference between emulation and real-device testing?
- How do you organize mobile Page Objects?
- How do you reduce flaky mobile tests?
- What enterprise practices improve mobile automation?
- How would you test a responsive navigation menu?
FAQs
What is the Playwright Mobile Emulation Tutorial?
It is a step-by-step guide to testing responsive web applications using Playwright’s built-in mobile device emulation features.
Does Playwright support Android and iPhone emulation?
Yes. Playwright provides built-in device descriptors for many Android phones, iPhones, and iPads.
Can I create custom devices?
Yes. You can define custom viewport dimensions, touch support, and other settings.
Does mobile emulation replace real-device testing?
No. Mobile emulation is excellent for functional and responsive testing, but physical device testing is still recommended for validating hardware-specific behavior, browser differences, and performance.
Can I run mobile tests in CI/CD?
Yes. Mobile emulation works well with GitHub Actions, Jenkins, Azure DevOps, and other CI platforms.
Can I use the Page Object Model for mobile testing?
Yes. The same Page Object Model can often be reused for both desktop and mobile automation, with adjustments for mobile-specific UI when necessary.
Can Playwright test orientation changes?
Yes. You can emulate portrait and landscape layouts by using appropriate device profiles or custom viewport settings.
Is mobile emulation suitable for enterprise automation?
Yes. It provides a scalable way to include responsive testing in automated regression suites and CI/CD pipelines.