Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 35 Β· Beyond the Basics

Cross-Browser and Mobile Testing

Run browser tests on Chromium, Firefox and WebKit, emulate phones, set viewports, geolocation and permissions, and plan a sensible test matrix.

Your users do not all browse with the browser you develop in. Some use Safari on an iPhone, some use Firefox on a laptop and some have a small screen where your navigation collapses into a menu. A page that works in one setup can quietly break in another: a CSS feature that Safari renders differently, a layout that overlaps at 360 pixels wide, a script that assumes a mouse. This lesson shows how Cypress and Playwright cover different browsers and devices, and how to decide how much to cover.

Real browsers and device emulation are not available on this site, so the Cypress and Playwright code is read-only. The runnable examples are stand-ins: a viewport matrix that checks a responsive layout against several screen sizes, and a small browser context model that shows how permissions and geolocation behave. The stand-ins illustrate the logic, not the real browser engines.

Which browsers can you test?

Playwright drives three browser engines with one API: Chromium (the base of Chrome and Edge), Firefox and WebKit (the engine of Safari). It downloads its own builds with npx playwright install, so every machine and CI runner tests the same versions. It can also drive installed Chrome and Edge through channels such as channel: 'chrome'. Be aware that Playwright's WebKit is the engine, not the Safari application, so it is a very good approximation but not a perfect replica of Safari on iOS.

Cypress runs tests in the browsers installed on the machine: Chrome-family browsers (Chrome, Chromium, Edge), Firefox and its bundled Electron. You pick one on the command line:

Terminal
# read-only
npx cypress run --browser chrome
npx cypress run --browser firefox
npx cypress run --browser edge

WebKit support in Cypress has been offered as an experimental option (experimentalWebKitSupport). Check the current documentation before relying on it. In practice, a team that must cover Safari engines often finds Playwright the easier route.

In Playwright you express browsers as projects in the config (see Configuration and Environments), and every test runs once per project:

TypeScript
// playwright.config.ts (read-only)
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit',   use: { ...devices['Desktop Safari'] } },
    { name: 'iphone',   use: { ...devices['iPhone 13'] } },
    { name: 'android',  use: { ...devices['Pixel 7'] } },
  ],
});
Terminal
# read-only
npx playwright test                       # all projects
npx playwright test --project=webkit      # only one

A device descriptor such as devices['iPhone 13'] bundles a viewport size, a device pixel ratio, a user agent string, and flags such as isMobile and hasTouch. That is emulation: the desktop browser pretends to be a phone. It is fast and reliable for layout and touch logic, but it is not a real device. It cannot reveal an iOS-specific bug in Safari's own behavior.

Viewports

Many bugs are just about width. In Cypress you set the size with cy.viewport, either with numbers or with a named preset:

JavaScript
// Cypress (read-only)
describe('navigation', () => {
  it('shows the menu button on a phone', () => {
    cy.viewport(375, 667)
    cy.visit('/')
    cy.get('[data-cy=menu-button]').should('be.visible')
    cy.get('[data-cy=desktop-nav]').should('not.be.visible')
  })

  it('shows the full nav on a laptop', () => {
    cy.viewport('macbook-15')
    cy.visit('/')
    cy.get('[data-cy=desktop-nav]').should('be.visible')
  })
})

In Playwright you can set the viewport in a project or per test group:

TypeScript
// Playwright (read-only)
test.describe('on a phone', () => {
  test.use({ viewport: { width: 375, height: 667 } });

  test('shows the menu button', async ({ page }) => {
    await page.goto('/');
    await expect(page.getByRole('button', { name: 'Menu' })).toBeVisible();
  });
});

You can also resize in the middle of a test with await page.setViewportSize({ width: 800, height: 600 }), which is handy for checking how a layout reacts when a window is resized.

The next stand-in models a responsive layout with three rules (like CSS breakpoints) and runs one check across a matrix of devices. A matrix is just the cross product of "what to check" and "where to check it".

JS A viewport matrix for a responsive layout

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The last two lines show why boundary widths deserve a test: the buggy layout shows both navigation bars at exactly 768 pixels because two rules overlap. A matrix that includes the breakpoint values (767, 768 and 769) catches that kind of off-by-one mistake.

Geolocation, permissions, locale and more

Phones bring features desktops do not: location, touch, a different language, dark mode. Playwright makes these part of the browser context options, so each test starts with exactly the environment you describe:

TypeScript
// Playwright (read-only)
test.use({
  geolocation: { latitude: 52.52, longitude: 13.405 },
  permissions: ['geolocation'],
  locale: 'de-DE',
  timezoneId: 'Europe/Berlin',
  colorScheme: 'dark',
});

test('shows stores near Berlin', async ({ page }) => {
  await page.goto('/stores');
  await expect(page.getByRole('heading', { name: 'GeschΓ€fte in Ihrer NΓ€he' })).toBeVisible();
});

For touch devices, hasTouch: true (included in device descriptors) lets you use await locator.tap(). You can change the location during a test with await context.setGeolocation(...) and grant or clear permissions with context.grantPermissions and context.clearPermissions.

Cypress does not offer one switch for these. The usual way is to stub the browser API before the page loads:

JavaScript
// Cypress (read-only)
cy.visit('/stores', {
  onBeforeLoad(win) {
    cy.stub(win.navigator.geolocation, 'getCurrentPosition').callsFake((success) => {
      success({ coords: { latitude: 52.52, longitude: 13.405 } })
    })
  },
})

Touch is also limited in Cypress: you can fire touch events with .trigger('touchstart') and friends, but there is no real touch emulation. Dark mode and language can be set through browser launch options or visit options, depending on the version; check the documentation of yours.

The stand-in below models a browser context in plain JavaScript: a permission set, a geolocation and a function requestLocation() that behaves like the real API (it fails without permission). It shows why tests must decide on these values deliberately instead of depending on the machine they run on.

JS A browser context with permissions and geolocation

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Each new context starts from scratch, which mirrors how Playwright gives every test an isolated browser context. Tests for the "permission denied" path are just as important as the happy path, and with context options you can run both deterministically.

flowchart TD
  T["One test file"] --> M{"Project matrix"}
  M --> C["Chromium desktop"]
  M --> F["Firefox desktop"]
  M --> W["WebKit desktop"]
  M --> P["Phone emulation<br/>touch, small viewport"]

The same tests run under several projects; each project changes the browser engine or the device profile.

Choosing what to cover

Running everything everywhere multiplies your run time. A pragmatic plan:

  1. Run the full suite on one browser, normally Chromium, on every change.
  2. Run a small smoke suite (sign in, search, buy) on Firefox and WebKit on every change, or the full suite nightly.
  3. Add phone projects for flows that matter on mobile, and tag them so they run only where relevant.
  4. Look at your analytics to decide which browsers and sizes your users really have.
  5. Test boundary widths around each CSS breakpoint, not just "typical" phones.
  6. Keep a real-device check (manual or via a cloud device service) for features emulation cannot cover, such as the iOS keyboard or true Safari quirks.

Visual layout checks across sizes fit nicely with screenshot comparison, covered in Visual and Accessibility Testing. How to run projects in parallel without slowing CI is in Parallel Runs, Sharding and Speed.

Check your understanding

Quick check Β· 5 questions

of 5 answered You scored / 5 Β· perfect!

  1. 1. Which browser engines can Playwright drive with one API?

    Playwright bundles builds of Chromium, Firefox and WebKit, so a project can target each of them.
  2. 2. What does a device descriptor like devices['iPhone 13'] provide?

    It configures a desktop browser to behave like that phone. It is emulation, not a physical device.
  3. 3. How do you choose the browser for a Cypress run?

    The browser is selected when the run starts, using the command-line option.
  4. 4. Why test widths such as 767, 768 and 769 pixels if the breakpoint is 768?

    Off-by-one mistakes at breakpoints are common, and tests at the boundary find them.
  5. 5. A page asks for the user's location and your test must check the denied case. What is the best approach?

    Controlling permissions in the test makes both outcomes deterministic instead of depending on the machine.

Summary

  • Playwright covers Chromium, Firefox and WebKit through projects; Cypress runs installed browsers chosen with --browser, and WebKit support is experimental.
  • Device descriptors emulate phones and tablets; emulation is fast but not a replacement for real devices.
  • Set viewports with cy.viewport or Playwright's viewport option, and test the widths around each breakpoint.
  • Playwright context options set geolocation, permissions, locale, time zone and color scheme; in Cypress you usually stub browser APIs.
  • Plan a matrix: full suite on one browser, a smoke suite on others, targeted mobile flows and a real-device check.

Next: Visual and Accessibility Testing