Viewport testing helper functions
Viewport Presets: cy.viewportPreset(preset, orientation, options)
Source file:
Description:
Presets are available for the top viewports for mobile, tablet, and desktop, derived from VA.gov's Google Analytics data.
Arguments:
preset -- a
String
, the preset nameorientation -- a
String
,portrait
orlandscape
, defaults toportrait
options -- an
Object
,log
property is set to aboolean
, defaults totrue
Preset Names
Top Presets by Traffic Percentage, Descending
The viewport values these presets point to is updated monthly. The last number in the preset name represents the traffic rank where 1 is highest. For example, if you want to set the viewport to the logical width and height of the mobile device most used on VA.gov, use preset va-top-mobile-1
.
Viewport objects that correspond to these presets are also available in the following Cypress environment variable arrays:
vaTopMobileViewports
vaTopTabletViewports
vaTopDesktopViewports
Please note: Iterating through these Cypress environment variable arrays is preferred over using these presets, if your test allows for it.
See Iterate Through Top VA.gov Viewports for more details.
Mobile | Tablet | Desktop |
---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Usage
To set the viewport, simply call cy.viewportPreset()
and pass in one of the above preset names as an argument, like so: cy.viewportPreset('va-top-mobile-1');
.
To set the orientation to landscape, pass in 'landscape' as a second argument, like so: cy.viewportPreset('va-top-mobile-1', 'landscape');
.
To prevent the command from being displayed in the command log, pass in { log: false }
as a third argument, like so: cy.viewportPreset('va-top-mobile-1', 'landscape', { log: false });
.
Please note: Microsoft Windows RT Tablet viewports are reported by Google Analytics in landscape mode, the opposite of most other tablets. As mentioned, the cy.viewportPreset()
orientation
argument is set to portrait
by default. If you change the orientation of a preset that is referencing a Microsoft Windows RT Tablet viewport by passing in landscape
as the orientation
argument, it will have the opposite effect--it be changed to portrait.
Recommended application
By default, Cypress tests run using the most common desktop viewport. It is recommended that all features should be tested using at least one additional viewport to ensure consistent functionality among different viewports, such as the top mobile viewport due to increasing traffic from mobile users. Google Analytics data provides statistics on browser usage per page on VA.gov, which can be used to determine which viewports to test.
Due to substantial increases in test execution time per additional viewport tested, it is not recommended to test all top viewports per Cypress test. As a guideline, it is recommended to select enough viewports that ensure confidence in test coverage without redundant viewports being tested.
Iterate Through Top VA.gov Viewports
To ensure that an application behaves correctly across the viewport sizes most commonly used by http://va.gov users, we've provided the following Cypress environment variables in the config/cypress.json
file that each contain an array of objects, each describing a viewport:
vaTopMobileViewports
vaTopTabletViewports
vaTopDesktopViewports
The objects in the arrays are updated once a month so we're always testing against the viewports VA.gov users are actually using.
Each viewport object contains a list
, rank
, devicesWithViewport
, percentTraffic
, percentTrafficPeriod
, width
and height
property. Here is an example of a mobile viewport object from the vaTopMobileViewports
Cypress environment variable:
{
"list": "VA Top Mobile Viewports",
"rank": 1,
"devicesWithViewport": "iPhone XS Max, iPhone XR, iPhone 11, iPhone 11 Pro Max",
"percentTraffic": 9.75,
"percentTrafficPeriod": "October, 2020",
"viewportPreset": "va-top-mobile-1",
"width": 414,
"height": 896
}
To access Cypress environment variables, simply call Cypress.env()
followed by the name of the variable. For example, Cypress.env().vaTopMobileViewports
returns the following array:
[
{
list: 'VA Top Mobile Viewports',
rank: 1,
devicesWithViewport: 'iPhone 12 Pro, iPhone 12',
percentTraffic: '9.0%',
percentTrafficPeriod: 'From: 12/01/2022, To: 12/31/2022',
viewportPreset: 'va-top-mobile-1',
width: 390,
height: 844,
},
{
list: 'VA Top Mobile Viewports',
rank: 2,
devicesWithViewport: 'iPhone 12 Pro Max',
percentTraffic: '6.51%',
percentTrafficPeriod: 'From: 12/01/2022, To: 12/31/2022',
viewportPreset: 'va-top-mobile-2',
width: 428,
height: 926,
},
{
list: 'VA Top Mobile Viewports',
rank: 3,
devicesWithViewport:
'iPhone XS Max, iPhone XR, iPhone 11, iPhone 11 Pro Max',
percentTraffic: '6.02%',
percentTrafficPeriod: 'From: 12/01/2022, To: 12/31/2022',
viewportPreset: 'va-top-mobile-3',
width: 414,
height: 896,
},
{
list: 'VA Top Mobile Viewports',
rank: 4,
devicesWithViewport: 'iPhone X, iPhone XS, iPhone 11 Pro',
percentTraffic: '4.3%',
percentTrafficPeriod: 'From: 12/01/2022, To: 12/31/2022',
viewportPreset: 'va-top-mobile-4',
width: 375,
height: 812,
},
{
list: 'VA Top Mobile Viewports',
rank: 5,
devicesWithViewport:
'iPhone SE 2nd gen, iPhone 6, iPhone 6s, iPhone 7, iPhone 8',
percentTraffic: '2.54%',
percentTrafficPeriod: 'From: 12/01/2022, To: 12/31/2022',
viewportPreset: 'va-top-mobile-5',
width: 375,
height: 667,
}
];
We’ve also provided the following Cypress environment variables that are set to the maximum index value of the vaTopMobileViewports
, vaTopTabletViewports
, and vaTopDesktopViewports
arrays that we recommend be used for testing:
vaTopMobileViewportsIterateUptoIndex
vaTopTabletViewportsIterateUptoIndex
vaTopDesktopViewportsIterateUptoIndex
At the time of this writing, each of these 'IterateUptoIndex' env vars is set to 0
, meaning only the viewport object at index 0
in each set of viewport objects should be used in your tests. As the platform expands its ability to run Cypress tests more quickly and efficiently, we'll increase the value of these environment variables so your tests automatically run against additional viewports.
Please iterate through the 'vaTopViewport' arrays and break out of the iteration based on the value of 'IterateUptoIndex' like so:
it('should render in mobile layouts', () => {
const mobileViewports = Cypress.env().vaTopMobileViewports;
for (let i = 0; i < mobileViewports.length; i += 1) {
if (i > Cypress.env().vaTopMobileViewportsIterateUptoIndex) break;
const {
list,
rank,
devicesWithViewport,
percentTraffic,
percentTrafficPeriod,
viewportPreset
width,
height,
} = mobileViewports[i];
cy.log(`Viewport list: ${list}`);
cy.log(`Viewport rank: ${rank}`);
cy.log(`Viewport width x height: ${width} x ${height}`);
cy.log(`Devices with viewport: ${devicesWithViewport}`);
cy.log(
`% traffic for the month of ${percentTrafficPeriod}: ${percentTraffic}%`
);
cy.visit('/page');
cy.viewportPreset(viewportPreset);
// Cypress test code follows...
}
});
Even though the width
and height
for each viewport is provided, we recommend that you no longer call cy.viewport()
to set the viewport, and instead call cy.viewportPreset()
by passing in viewportPreset
. It is preferred that cy.viewport()
not be used. width
and height
can be used for conditional logic during each iteration, or they can be logged for contextual purposes.
Help and feedback
Get help from the Platform Support Team in Slack.
Submit a feature idea to the Platform.