Cypress viewport desktop
Hem / Teknik & Digitalt / Cypress viewport desktop
A great example of how to do this is in the Real World App (RWA). Tests will also consistently run in because all of the viewports will be the same no matter what machine Cypress runs on.
Reset viewport via
You can change the size of the viewport height and width for the remainder of the tests by setting the new values for or within Cypress.config().
Set viewport in the test configuration
You can configure the size of the viewport height and width within a suite or test by passing the new configuration value within the test configuration.
This will set the height and width throughout the duration of the tests, then return it to the default and when complete.
Rules
Requirements
- requires being chained off of .
Assertions
- cannot have any assertions chained.
Timeouts
- cannot time out.
Command Log
Change viewport size to test responsive nav
The commands above will display in the Command Log as:
When clicking on within the command log, the console outputs the following:
History
| Version | Changes |
|---|---|
| 5.5.0 | Added support for preset. |
| 5.4.0 | Added support for presets , , and . |
| 3.8.0 | Removed max viewport size and lowered min viewport size to . |
| 3.5.0 | Added support for presets , , , and |
| 3.5.0 | Increased max viewport size to |
| 0.9.0 | command added |
See also
viewport
Control the size and orientation of the screen for your application.
cy.viewport(width, height) cy.viewport(preset, orientation) cy.viewport(width, height, options) cy.viewport(preset, orientation, options)You can set the viewport’s width and height globally by defining and in the configuration.
Usage
Correct Usage
cy.viewport(550, 750) // Set viewport to 550px x 750px cy.viewport('iphone-6') // Set viewport to 375px x 667pxArguments
width(Number)
Width of viewport in pixels (must be a non-negative, finite number).
height(Number)
Height of viewport in pixels (must be a non-negative, finite number).
preset(String)
A preset dimension to set the viewport.
Currently, Cypress supports Chrome-family browsers (including Electron and Chromium-based Microsoft Edge), WebKit (Safari's browser engine, currently in experimental status in Cypress) and Firefox.
You can also configure Cypress to run your tests within a specific window size with custom configurations.
viewport
Cypress App
Control the size and orientation of the screen for your application.
info
You can set the viewport's width and height globally by defining and in the Cypress configuration.
Syntax
Usage
Correct Usage
Arguments
width (Number)
Width of viewport in pixels (must be a non-negative, finite number).
height (Number)
Height of viewport in pixels (must be a non-negative, finite number).
preset (String)
A preset dimension to set the viewport.
The default orientation is .
Within the , we have custom scripts to launch Cypress with mobile dimensions.
As you can see, when these commands are executed, we are passing along some custom configuration that tells Cypress the viewportWidth and viewportHeight to use when launching our tests.
We also have a utility function called which determines if our tests are being run at the mobile viewport.
Preset supports the following options:
| Preset | width | height |
|---|---|---|
| 768 | 1024 | |
| 768 | 1024 | |
| 320 | 480 | |
| 320 | 480 | |
| 320 | 568 | |
| 375 | 667 | |
| 414 | 736 | |
| 375 | 667 | |
| 375 | 667 | |
| 375 | 812 | |
| 414 | 896 | |
| 375 | 667 | |
| 1366 | 768 | |
| 1280 | 800 | |
| 1440 | 900 | |
| 1536 | 960 | |
| 414 | 846 | |
| 360 | 760 |
orientation(String)
The orientation of the screen.
Follow #7075 if you need this supported.
Restores
Cypress will restore the viewport in the snapshot
When hovering over each command, Cypress will automatically display the snapshot in the viewport dimensions that existed when that command ran.
Defaults
Default sizing
By default, until you issue a command, Cypress sets the width to and the height to by default.
You can change these default dimensions by adding the following to your configuration file ( by default):
{ "viewportWidth": 1000, "viewportHeight": 660 }Additionally, Cypress automatically sets the viewport to its default size between each test.
Scaling
Auto Scaling
By default, if your screen is not large enough to display all of the current dimension’s pixels, Cypress will scale and center your application within the Cypress runner to accommodate.
Scaling the app should not affect any calculations or behavior of your application (in fact it won’t even know it’s being scaled).
The upsides to this are that tests should consistently pass or fail regardless of a developers’ screen size.
Here is what that function looks like:
The environment variable is located within the config file.
In our tests, we can use this function to determine if the tests are being executed within our mobile viewport and react accordingly using a conditional.
In the case of the RWA, the sidebar is hidden by default on mobile.
Pass as the orientation to reverse the width/height.
options (Object)
Pass in an options object to change the default behavior of .
| Option | Default | Description |
|---|---|---|
| Displays the command in the Command log |
Yields
- yields .
Examples
Width, Height
Resize the viewport to 1024px x 768px
Organize desktop vs mobile tests separately
Dynamically test multiple viewports
- End-to-End Test
- Component Test
Preset
Resize the viewport to iPhone 6 width and height
Orientation
Change the orientation to landscape
Notes
devicePixelRatio
is not simulated
Follow #7075 if you need this supported.
Restores
Cypress will restore the viewport in the snapshot
When hovering over each command, Cypress will automatically display the snapshot in the viewport dimensions that existed when that command ran.
Defaults
Default sizing
By default, until you issue a command, Cypress sets the width to and the height to by default.
You can change these default dimensions by adding the following to your Cypress configuration:
- cypress.config.js
- cypress.config.ts
Additionally, Cypress automatically sets the viewport to its default size between each test.
Scaling
Auto Scaling
By default, if your screen is not large enough to display all of the current dimension's pixels, Cypress will scale and center your application within the preview pane to accommodate.
Scaling the app should not affect any calculations or behavior of your application (in fact it won't even know it's being scaled).
The upsides to this are that tests should consistently pass or fail regardless of a developers' screen size.
Preset supports the following options:
| Preset | width | height |
|---|---|---|
| 768 | 1024 | |
| 768 | 1024 | |
| 320 | 480 | |
| 320 | 480 | |
| 320 | 568 | |
| 375 | 667 | |
| 414 | 736 | |
| 375 | 667 | |
| 375 | 667 | |
| 375 | 812 | |
| 414 | 896 | |
| 375 | 667 | |
| 1366 | 768 | |
| 1280 | 800 | |
| 1440 | 900 | |
| 1536 | 960 | |
| 414 | 846 | |
| 360 | 760 |
orientation (String)
The orientation of the screen.
If you look at the GitHub Actions workflow, we will run the tests within the RWA in Chrome Desktop, Chrome Mobile, Firefox Desktop, and Firefox Mobile.
We can tell Cypress to use a specific browser for testing by specifying the browser we want like so:
This works excellent in CI, but what if you want to do this locally?
You can pass in which browser you would like Cypress to run in via the command line like so:
You can also select which browser to run via the UI.
You can even do this on a test by test basis by passing an options object to your tests.
You can even do this for all tests located within a block like so:
In this example, Firefox will run all tests located within this .
Testing Mobile
All of the tests within the RWA are written for Desktop by default.
This function will fire whenever our viewport width is less than 414px.
This allows the same test to be used in both Desktop and Mobile orientations instead of coding mobile-specific tests.
For more info, check out these articles within our docs.
Test Configuration
Cross Browser Testing
.
Pass as the orientation to reverse the width/height.options(Object)
Pass in an options object to change the default behavior of .
| Option | Default | Description |
|---|---|---|
| Displays the command in the Command log |
Yields
yields .
cannot be chained further.
Width, Height
Resize the viewport to 1024px x 768px
cy.viewport(1024, 768)Organize desktop vs mobile tests separately
describe('Nav Menus', () => { context('720p resolution', () => { beforeEach(() => { // run these tests as if in a desktop // browser with a 720p monitor cy.viewport(1280, 720) }) it('displays full header', () => { cy.get('nav .desktop-menu').should('be.visible') cy.get('nav .mobile-menu').should('not.be.visible') }) }) context('iphone-5 resolution', () => { beforeEach(() => { // run these tests as if in a mobile browser // and ensure our responsive UI is correct cy.viewport('iphone-5') }) it('displays mobile menu on click', () => { cy.get('nav .desktop-menu').should('not.be.visible') cy.get('nav .mobile-menu') .should('be.visible') .find('i.hamburger').click() cy.get('ul.slideout-menu').should('be.visible') }) }) })Dynamically test multiple viewports
const sizes = ['iphone-6', 'ipad-2', [1024, 768]] describe('Logo', () => { sizes.forEach((size) => { // make assertions on the logo using // an array of different viewports it(`Should display logo on ${size} screen`, () => { if (Cypress._.isArray(size)) { cy.viewport(size[0], size[1]) } else { cy.viewport(size) } cy.visit('https://www.cypress.io') cy.get('#logo').should('be.visible') }) }) })Preset
Resize the viewport to iPhone 6 width and height
cy.viewport('iphone-6') // viewport will change to 414px x 736pxOrientation
Change the orientation to landscape
// the viewport will now be changed to 736px x 414px // and simulates the user holding the iPhone in landscape cy.viewport('iphone-6', 'landscape')devicePixelRatio
is not simulated
This is something Cypress will eventually do, which will match how Chrome’s responsive mobile browsing simulation works.
Tests will also consistently run in because all of the viewports will be the same no matter what machine Cypress runs on.
Reset viewport via
You can change the size of the viewport height and width for the remainder of the tests by setting the new values for or within .
Cypress.config('viewportWidth', 800) Cypress.config('viewportWidth') // => 800Set viewport in the test configuration
You can configure the size of the viewport height and width within a suite or test by passing the new configuration value within the test configuration.
This will set the height and width throughout the duration of the tests, then return it to the default and when complete.
describe('page display on medium size screen', { viewportHeight: 1000, viewportWidth: 400 }, () => { it('does not display sidebar', () => { cy.get('#sidebar').should('not.be.visible') }) it('shows hamburger menu', () => { cy.get('#header').find('i.menu').should('be.visible') }) })Requirements
requires being chained off of .
Assertions
cannot have any assertions chained.
Timeouts
cannot time out.
Change viewport size to test responsive nav
cy.get('#navbar').should('be.visible') cy.viewport(320, 480) // the navbar should have collapse since our screen is smaller cy.get('#navbar').should('not.be.visible') cy.get('.navbar-toggle').should('be.visible').click() cy.get('.nav').find('a').should('be.visible')The commands above will display in the Command Log as:
When clicking on within the command log, the console outputs the following:
| Version | Changes |
|---|---|
| 5.5.0 | Added support for preset. |
| 5.4.0 | Added support for presets , , and . |
| 3.8.0 | Removed max viewport size and lowered min viewport size to . |
| 3.5.0 | Added support for presets , , , and |
| 3.5.0 | Increased max viewport size to |
| 0.9.0 | command added |
Viewport and Browser Testing Tips
Different Browsers
Running all of your tests within multiple browsers and across various screen sizes is incredibly important.
The default orientation is .