Playwright iOS Automation Testing on Real Devices

Delivering a consistent experience on iPhones and iPads means testing under the same conditions your users will encounter. Playwright supports this by integrating with Safari through the WebKit browser engine. This allows you to run automated tests for mobile web applications either in an emulated environment or directly on real devices.

When using emulation, Playwright can apply device-specific parameters such as viewport dimensions, user agent strings, touch input support, and even network conditions. This approach is effective in the early stages of testing to validate layout, responsiveness, and essential functionality.

However, emulation cannot fully replicate factors such as rendering accuracy, performance over real network conditions, and hardware-specific behavior. These aspects require testing on actual devices.

That’s where BrowserStack comes in. BrowserStack now supports Playwright testing on real iOS devices running Safari. Teams can run tests on different iPhones, iPads, and Safari versions in the cloud to validate how applications behave in real-world conditions.

This article explains how to configure Playwright for iOS automation and run tests on real iPhones through BrowserStack to achieve reliable and production-ready results.

Setting Up Playwright

Before running Playwright iOS automation tests, you need a basic Playwright setup on your system.

Pre-requisites

• Install Visual Studio Code
• Install Node.js

Follow these steps to set up Playwright.  

1. Create and open a new project folder in VS Code.

2. Open the integrated terminal and run:

npm init playwright@latest

Follow the prompts to choose your language and test configuration.

3. Install Playwright browsers:

npx playwright install

4. (Optional) Adjust playwright.config.ts to match your test requirements.

5. Create a test file inside the tests folder and add your test scripts.

6. Run your test using the following command:

npx playwright test --headed

7. View the HTML report:

npx playwright show-report

Configuring the test environment for Playwright iOS automation

Before running Playwright tests for iOS, you need to decide how the tests will run. There are two main options:

• Emulating mobile devices: Use Playwright’s built-in device profiles to simulate iPhones and iPads in WebKit, allowing quick validation of layouts, responsiveness, and basic functionality.
• Testing on real devices with BrowserStack: Run Playwright scripts on physical iPhones and iPads with Safari to capture accurate performance, rendering, and device-specific behavior.

Emulating Mobile Devices

Playwright supports built-in mobile device emulation to help developers test web applications across popular devices like iPhones, iPads, and Android smartphones. This ensures your site displays and behaves correctly on various screen sizes, resolutions and supports touch interactions.

Mobile emulation in Playwright is based on predefined device profiles. Each profile includes:

• Viewport dimensions (width and height)
• User agent string for the selected mobile browser
• Touch input support
• Device scale factor
• Optional network conditions

You can apply these profiles directly in your test scripts or through the Playwright configuration file.

• For example, using devices[‘iPhone 14’] applies Safari-like settings for that model.
• To view all available device profiles, run the following command:

npx playwright devices

If your target mobile device isn’t in Playwright’s predefined list, you can create a custom profile by specifying:

• Viewport width and height
• User agent string
• Device scale factor
• Touch input capabilities

Limitations of Emulators for Playwright Mobile Testing on iOS

Emulators have significant limitations when it comes to Playwright mobile testing on iOS, which can impact the reliability and accuracy of your test results. Here are the key constraints you should be aware of:

• Hardware features are missing: iOS emulators do not fully support Touch ID, Face ID, camera, GPS, or motion sensors. Tests for these features may not work as expected.
• Performance is not accurate: Emulators use your computer’s hardware, so results will not match real device performance or reveal issues like battery drain or overheating.

• Not all iOS behaviors are replicated: The iOS Simulator handles networking, background apps, push notifications, and some APIs differently from real devices.
• Safari and WebView differences: Rendering, JavaScript performance, and security settings in emulators can differ from Mobile Safari or in-app WebViews on iOS.
• Real-world scenarios are hard to test: Poor connectivity, incoming calls, low battery, and memory pressure cannot be reliably simulated.
• Limited testing environment: iOS Simulators only run on macOS and have fewer configuration options than Android emulators.

Run Playwright iOS Automation Tests on Real Devices with BrowserStack

Playwright users have long struggled with a major testing limitation: Safari browser testing on actual iOS hardware. Until now, development teams were stuck using device simulators, which consistently missed real-world Safari behaviors and iOS-specific issues.

BrowserStack has solved this problem by becoming the first platform to support Playwright automation on physical iOS devices. Teams now have direct access to authentic iPhone and iPad testing environments, covering 100+ device and browser combinations that reveal Safari issues invisible to emulation tools.

BrowserStack integrates directly into current development workflows while providing complete visibility into test execution through detailed logs and debugging data.

Key Features of BrowserStack for Playwright iOS automation testing:

• Run parallel tests across hundreds of real iOS device-browser combinations.
• Capture comprehensive debugging artifacts, including network logs, video recordings, and detailed text logs, and access these from a unified dashboard.
• Simulate real-world conditions such as geolocation, network speeds, time zones, and device orientations to ensure robust testing coverage.

Supported iPhones and Safari Versions on BrowserStack

BrowserStack supports a wide range of mobile devices, from iPhone 15 Pro Max to iPhone SE (2020), and Safari versions from 11 to 26 Beta.

Check the full list of supported devices and versions here.

Getting Started With Playwright iOS Automation Testing on BrowserStack

Two integration options are available for Playwright iOS automation testing:

Method 1: Using SDK (Recommended)

The BrowserStack SDK is like a pre-built connector that handles all the technical setup for you. Instead of writing code to connect to devices, authenticate, and configure settings, the SDK does this automatically. It also captures test videos and logs without extra setup.

Method 2: Using Legacy Integration

The legacy method means you write your own code to connect to BrowserStack devices. You manually specify which device to use, handle connection failures, and set up authentication. This requires more coding but gives you complete control over how everything works.

Talk to an Expert

Playwright Mobile Emulation Vs BrowserStack

While Playwright’s built-in mobile emulation simulates device characteristics on desktop browsers, it cannot replicate the actual behavior of Safari on real iOS hardware. BrowserStack’s real device testing reveals iOS-specific issues, hardware interactions, and Safari rendering differences that emulation completely misses.

Here’s a table highlighting the core differences between Playwright mobile emulation and BrowserStack Playwright iOS Automation testing.

Handling iOS‑Specific Challenges in Playwright Tests

When testing on iOS with Playwright, you may see issues that do not occur on desktop browsers or Android devices. This is because all browsers on iOS run on Apple’s WebKit engine, and Safari on iOS behaves differently in several areas.

Below are common challenges and how to handle them.

1. WebKit and device profiles

You cannot run Playwright directly against Mobile Safari on a connected iPhone due to Apple’s restrictions. Playwright can only launch its own WebKit browser, which is very close to Mobile Safari but not identical. As a result, some bugs appear only on real iPhones or iPads and not in Playwright’s WebKit build.

To address this, run Playwright tests on real iOS devices with BrowserStack. You can execute the same Playwright scripts on physical iPhones and iPads running specific Safari versions in the cloud, capture detailed logs and screenshots, and debug issues in conditions identical to end users.

2. Rendering and viewport gotchas

On iOS, the Safari URL bar collapses when scrolling, which changes the reported viewport height. This can break tests for sticky headers, footers, or elements positioned using 100vh units.

Here’s how to handle it:

• Scroll the target element into view before interacting with it.
• Base assertions on element visibility instead of exact coordinates.
• If your app uses 100vh, use smaller viewport units in testing or scroll before asserting visibility.
• Prevent zoom on input focus by setting a fixed scale in your test environment.

After making these adjustments, use BrowserStack’s real-device cloud to see how Safari’s viewport resizing behaves across iOS versions and devices, and confirm that sticky elements and full-height layouts remain stable.

3. Soft keyboard behavior

When the iOS keyboard appears, it reduces the viewport height and can shift the layout. It also enables auto-capitalization and auto-correction by default, which can cause text input mismatches.

Here’s how to handle it:

• Disable auto-correct and auto-capitalization in test builds if possible.
• Fill inputs in one command and validate the input.value property instead of relying on visible text.
• Click the input directly instead of clicking labels that move focus indirectly.

Once you’ve made these changes, use BrowserStack’s real-device cloud to verify how the iOS keyboard affects layout, viewport size, and text entry on different devices and OS versions.

4. Scrolling physics and the “rubber‑band” effect

iOS applies elastic scrolling at page edges, and desktop-style wheel events do not behave like touch gestures. This can cause unexpected results in lists, carousels, and other touch-driven UI.

BrowserStack’s real-device cloud lets you test Safari’s elastic scrolling and gesture handling on different iPhones and iPads, so you can confirm how lists, carousels, and other touch-based UI respond in actual use. If you find issues, apply the following changes:

• Use scrollIntoViewIfNeeded() on locators instead of simulating wheel events.
• For carousels, use drag actions instead of JavaScript scroll commands.
• For pinch or multi-touch gestures, verify the resulting state, such as a zoomed image, instead of automating the gesture itself.

5. Inputs, file uploads, and camera roll

On real iOS devices, selecting a file opens the system picker for photos or the camera. In Playwright WebKit, setInputFiles bypasses this picker, which means format-specific checks, such as HEIC or EXIF data validation, may be skipped.

BrowserStack’s real-device cloud lets you open the native iOS picker, capture a photo or select one from the camera roll, and verify that the file format, metadata, and upload flow behave exactly as they do for end users. If you encounter issues, try the following:

• Use test files that match iOS photo formats when your backend validates them.
• Keep pre-converted fixtures in your repository to avoid slow file conversions during tests.

Best Practices for Playwright iOS Automation Tests

Reliable iOS tests depend on targeting the right environment, writing Playwright selectors that are compatible with small screens, and handling iOS-specific behaviors. The following Playwright iOS automation best practices will help you design tests that remain stable on both iPhone and iPad.

1. Target the Right Browser and Device Profile

iOS users may access your app over a variety of network conditions, from high-speed Wi-Fi to slower or more variable mobile connections. These changes can affect how quickly pages load, whether they load completely, and whether content appears fresh or from Safari’s cache.

To reliably catch these issues, you need to recreate real-world network conditions on actual devices. BrowserStack supports advanced network testing, like offline conditions, slow network, and latency simulation. Run your Playwright tests on real iPhones and iPads with these profiles enabled to confirm how Safari handles load times, caching, and offline behavior.

2. Use Stable, Mobile-Friendly Locators

On smaller screens, text can wrap, labels can be shortened, and elements can be hidden under sticky toolbars. If your selectors depend on exact text or element position, they may fail on iOS layouts.

Use semantic locators that target an element’s role or a test-specific attribute, rather than visual position or styling. This makes them resilient to responsive design changes.

// Good: targets the button by its role and name

await page.getByRole('button', { name: 'Add to cart' }).click();



// Also good: use a data-test attribute for custom icons or widgets

await page.getByTestId('cart-icon').click();

You can then run your Playwright tests on iOS devices in BrowserStack to see how selectors respond to actual Safari rendering, and verify they remain reliable when UI elements shift on smaller screens.

3. Test Payment Workflows on iOS Safari

Apple Pay is built into iOS Safari, but configuration differences between environments can cause payment buttons to disappear, fail authentication, or loop back to the cart without processing. These issues rarely show up in desktop tests.

In BrowserStack, you can test payment and security workflows on real iOS devices. You can trigger payments with both debit and credit cards, complete the authentication step (Face ID, Touch ID, or passcode), and verify that order confirmation pages load with the correct details.

You can also test edge cases like canceling mid-transaction, changing payment methods, or failing authentication to confirm that error handling works correctly.

4. Validate Location and Device Settings

Geofencing and localization can break silently if the app detects the wrong location or fails to load region-specific resources. This can result in users seeing incorrect language, currency, or restricted content.

With BrowserStack’s location and device settings, you can run Playwright tests across 100+ countries to ensure that localized prices, formats, and layouts display correctly.

In the same session, use the in-session toolbar to switch the device’s language and region. Verify that translations apply across the app, dynamic elements like date and currency adjust instantly, and geo-restricted features respond appropriately when the simulated location changes.

5. Handle Navigation and New Tabs for iOS

Some links are designed to open a new browser tab or window when clicked. In HTML, this is done using the target=”_blank” attribute. On desktop Safari, this usually works as expected and opens a new tab. On iOS Safari, the same link may instead load in the current tab. This difference can cause Playwright tests to fail if they are written to expect one specific behavior.

To make tests reliable across both environments:

• Wait for a pop-up, but don’t fail the test if one doesn’t appear.
• If a pop-up opens, run assertions in the new page.
• If no pop-up appears, run assertions in the current page after navigation completes.

The following code handles both new-tab and same-tab navigation, so the test works in Safari and other desktop browsers as well as on iOS devices.

const link = page.getByRole('link', { name: 'Open statement' });



// Wait for a possible popup, but allow timeout without failure

const maybePopupPromise = page

  .waitForEvent('popup', { timeout: 3000 })

  .catch(() => null);



// Click the link and wait for whichever navigation happens

const [popup] = await Promise.all([

  maybePopupPromise,

  link.click(),

]);



if (popup) {

  await popup.waitForLoadState('domcontentloaded');

  await expect(popup.getByRole('heading', { name: 'Statement' })).toBeVisible();

} else {

  await page.waitForLoadState('domcontentloaded');

  await expect(page.getByRole('heading', { name: 'Statement' })).toBeVisible();

}

Conclusion

Running Playwright tests for iOS Safari comes with unique challenges. Native automation support for Mobile Safari is not available directly, and WebKit emulation is useful but cannot fully replicate the behavior of real iPhones and iPads. This gap makes it harder for teams to validate critical user journeys on Apple’s mobile browsers with complete confidence.

BrowserStack now enables Playwright tests to run on real iOS Safari devices. Teams can verify their applications in the same conditions that end users experience, catch platform-specific issues before release, and deliver a consistent experience across both desktop and mobile Safari.

Try BrowserStack for Free