Viewport testing helper functions

Viewport Presets: cy.viewportPreset(preset, orientation, options)

Source file:

https://github.com/department-of-veterans-affairs/vets-website/blob/master/src/platform/testing/e2e/cypress/support/commands/viewportPreset.js

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 name

• orientation -- a String, portrait or landscape, defaults to portrait

• options -- an Object, log property is set to a boolean, defaults to true

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.

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

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.