How to Perform Mobile Testing in Playwright

Mobile-first applications dominate today’s digital world. Ensuring your web app works smoothly on mobile devices is no longer optional. Mobile testing in Playwright makes this easy with its built-in mobile testing capabilities. You can simulate iOS and Android devices, adjust viewport sizes, and set a custom user agent, all without needing a real device.

In this guide, we’ll explore everything you need to know about Playwright mobile testing, including how to use devices, configure the viewport, and run tests effectively.

Why Mobile Testing Matters

More than 60% of global web traffic now comes from mobile devices. Users expect smooth, responsive, and fast applications on both iOS and Android. If your app is not optimized for smaller screens, touch interactions, and different browsers, you risk losing users to competitors who deliver a better mobile experience.

This is where Playwright Mobile Testing becomes essential. It helps you simulate real devices, adjust viewport sizes, and test with different user agents. By doing so, you can identify mobile-specific bugs early, ensure consistent performance across devices, and provide users with a reliable experience regardless of the device they use.

Playwright Mobile Testing Capabilities

Playwright comes with built-in support for mobile emulation, allowing you to test your app on popular iOS and Android devices without needing real hardware. It provides ready-made device descriptors such as iPhone 12, Pixel 5, or iPad, which include screen size, viewport, and user agent details. This makes it simple to validate how your web application looks and behaves in real mobile environments. You can also adjust the viewport for responsiveness, set a custom user agent, and test how your app handles touch events with ease.

Another advantage of Playwright mobile testing is that it works across different browser engines like Chromium, WebKit, and Firefox. This means you can verify mobile performance and compatibility on browsers behind Chrome, Safari, and Firefox using the same framework. By leveraging these Playwright mobile testing capabilities, you ensure that your application delivers a seamless and consistent user experience across multiple devices and platforms.

Performing Mobile Testing in Playwright: Two Approaches

When it comes to Playwright mobile testing, you can set up your environment in two different ways. Both are simple and allow you to run tests on simulated mobile devices like an iPhone or an Android.

1. Configure Mobile Devices in playwright.config.js

This method is useful if you want to run tests across multiple devices consistently. You define mobile projects in your Playwright configuration file.

// playwright.config.js
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Mobile Safari',
      use: {
        ...devices['iPhone 13'],
      },
    },
    {
      name: 'Pixel 5',
      use: {
        ...devices['Pixel 5'],
      },
    },
  ],
});

// playwright.config.js
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Mobile Safari',
      use: {
        ...devices['iPhone 13'],
      },
    },
    {
      name: 'Pixel 5',
      use: {
        ...devices['Pixel 5'],
      },
    },
  ],
});

Now, when you run the test below, Playwright will execute it in the simulated environments of both iPhone 13 and Pixel 5. You can also set other popular devices such as iPhone 14, Pixel 7, Galaxy S9+, or iPad Pro, depending on your testing needs.

const { test, devices } = require('@playwright/test');

test('Playwright mobile emulation demo', async ({ page }) => {
  await page.goto('https://www.google.com');
  const Title = await page.title();
  console.log("Page title is: "+Title);  
});

const { test, devices } = require('@playwright/test');

test('Playwright mobile emulation demo', async ({ page }) => {
  await page.goto('https://www.google.com');
  const Title = await page.title();
  console.log("Page title is: "+Title);  
});

2. Define Mobile Device Inside the Test File

If you only want mobile simulation for a specific test case, you can directly apply the device profile inside your test.

Example:

const { test, devices } = require('@playwright/test');

//iPhone 13 device simulation
test.use({ ...devices['iPhone 13'] });

test('Playwright mobile emulation demo', async ({ page }) => {
  await page.goto('https://www.google.com');
  const Title = await page.title();
  console.log("Page title is: "+Title);  
});

const { test, devices } = require('@playwright/test');

//iPhone 13 device simulation
test.use({ ...devices['iPhone 13'] });

test('Playwright mobile emulation demo', async ({ page }) => {
  await page.goto('https://www.google.com');
  const Title = await page.title();
  console.log("Page title is: "+Title);  
});

This approach gives you flexibility to apply mobile testing only when needed without changing the global config.

Setting Playwright Viewport

You can define the viewport size inside playwright.config.js and the test file itself as well. This gives you control over how your web application appears on different mobile devices or screen resolutions. By customizing the viewport, you can simulate real-world scenarios such as small screens, tablets, or large phones, which is essential for accurate Playwright Mobile Testing.

For example, adding viewport settings in playwright.config.js applies globally to all tests, while defining it inside a specific test file gives you flexibility to target unique cases. This dual approach ensures that you can fine-tune both overall test behavior and individual test conditions.

Example: Setting viewport in playwright.config.js

// playwright.config.js
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    viewport: { width: 810, height: 1080 }, // iPhone X viewport
  },
});

// playwright.config.js
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    viewport: { width: 810, height: 1080 }, // iPhone X viewport
  },
});

Example: Setting the viewport inside a test file

const { test, devices } = require('@playwright/test');

test.use({
  viewport: { width: 810, height: 1080 }, // iPhone 11 viewport
});

test('Get Page Title', async ({ page }) => {
  await page.goto('https://www.google.com');
  const Title = await page.title();
  console.log("Page title is: "+Title);  
});

const { test, devices } = require('@playwright/test');

test.use({
  viewport: { width: 810, height: 1080 }, // iPhone 11 viewport
});

test('Get Page Title', async ({ page }) => {
  await page.goto('https://www.google.com');
  const Title = await page.title();
  console.log("Page title is: "+Title);  
});

With these configurations, you can easily test how your application adapts to different mobile screens.

Common Mobile Viewport Sizes

Here are some commonly used viewport dimensions you can set in Playwright tests:

Best Practices for Playwright Mobile Testing

• Use Realistic Devices: Always simulate commonly used devices like iPhone 15 Pro Max, Pixel 8, or Galaxy S24 to ensure your app works for most users.
• Test Multiple Viewports: Don’t rely on just one screen size. Modern users switch between smartphones, tablets, and desktops.
• Set Consistent Configurations: Define devices and viewport sizes inside playwright.config.js for better maintainability.
• Leverage Parallel Testing: Run tests across multiple devices in parallel to save time and catch more bugs quickly.
• Combine with Visual Testing: Use screenshots to verify UI consistency across devices.

Troubleshooting Common Issues

• Elements not visible on smaller screens: Check your viewport settings. Try scrolling into view before interacting.
• Layout breaks on certain devices: Review your CSS and responsive design. Sometimes device pixel ratio (DPR) causes misalignment.
• Slow tests on mobile emulation: Reduce heavy animations or mock APIs for faster execution.
• Authentication failing in device simulation: Some apps behave differently with mobile headers. Ensure cookies, storage, and session data are set properly.
• Viewport not applying correctly: Confirm you haven’t overridden the viewport in both the config and the test file at the same time.

Final Words

Playwright mobile testing makes it simple to ensure your web apps work perfectly on iOS and Android. With built-in devices and viewport features, you can simulate real-world mobile experiences without physical devices. By following best practices and solving common issues, you’ll achieve reliable and fast mobile automation testing.

Aravind

Hi, I’m Aravind — a seasoned Automation Test Engineer with over 17 years of hands-on experience in the software testing industry. I specialize in tech troubleshooting and tools like Selenium, Playwright, Appium, JMeter, and Excel automation. Through this blog, I share practical tutorials, expert tips, and real-world insights to help testers and developers improve their automation skills.In addition to software testing, I also explore tech trends and user-focused topics, including Snapchat guides, codeless test automation, and more.