How to Use Viewport in Cypress for Responsive Testing

In Cypress, you use the cy.viewport() command to set the browser's viewport size or device type for testing responsive layouts. You can specify width and height in pixels or use predefined device names like 'iphone-6'. This helps simulate different screen sizes during test runs.

Syntax

The cy.viewport() command sets the size of the browser window or simulates a device screen size. It accepts either width and height in pixels or a device name string.

• cy.viewport(width, height): Sets viewport to specific pixel dimensions.
• cy.viewport(deviceName): Sets viewport to a predefined device size (e.g., 'iphone-6').
• cy.viewport(width, height, orientation): Optional third argument to set orientation ('portrait' or 'landscape').

javascript

cy.viewport(width, height)
cy.viewport(deviceName)
cy.viewport(width, height, orientation)

Example

This example shows how to set the viewport size to 1280x720 pixels and then to an iPhone 6 screen size. It demonstrates testing a responsive page by changing viewport sizes.

javascript

describe('Viewport Test Example', () => {
  it('sets viewport to 1280x720', () => {
    cy.viewport(1280, 720)
    cy.visit('https://example.cypress.io')
    cy.get('header').should('be.visible')
  })

  it('sets viewport to iPhone 6', () => {
    cy.viewport('iphone-6')
    cy.visit('https://example.cypress.io')
    cy.get('header').should('be.visible')
  })
})

Output

Test run passes if the header is visible at both viewport sizes.

Common Pitfalls

Common mistakes when using cy.viewport() include:

• Setting viewport before cy.visit() to ensure the page loads with the correct size.
• Using incorrect device names or misspelling them causes errors.
• Not specifying orientation when testing devices that support portrait and landscape modes.
• Assuming viewport changes affect the entire browser window; it only changes the viewport size inside the browser.

javascript

/* Wrong: viewport after visit may cause inconsistent layout */
cy.visit('https://example.com')
cy.viewport(375, 667) // iPhone 6 size

/* Right: viewport before visit */
cy.viewport(375, 667)
cy.visit('https://example.com')

Quick Reference

Usage	Description	Example
Set viewport size	Set width and height in pixels	cy.viewport(1024, 768)
Set device viewport	Use predefined device name	cy.viewport('ipad-2')
Set orientation	Add 'portrait' or 'landscape'	cy.viewport(375, 667, 'landscape')
Common devices	Examples of device names	'iphone-6', 'ipad-2', 'macbook-15', 'samsung-note9'

Key Takeaways

Use cy.viewport() before cy.visit() to set the screen size correctly.

You can specify viewport by pixel size or device name for responsive testing.

Include orientation when testing devices that support portrait and landscape modes.

Common device names include 'iphone-6', 'ipad-2', and 'macbook-15'.

Viewport changes simulate screen size but do not resize the entire browser window.