README

A library that extends and improves the default options provided by BackstopJS.

Installation

composer require --dev metadrop/backstopjs-addons

Add the path of the "bacsktopjs-addons" folder to the project's .gitignore, for example:

/tests/backstopjs/common/libraries/

You can override the default destination of the library ("tests/backstopjs/common/libraries/backstopjs-addons") by adding the following parameter to the extra section of your project's composer.json file:

"extra": {
  "backstopjs-addons": {
    "path": "custom/destination"
  }
}

Options and features

Scenario setup

By default, the library applies the following optimisations to the scenarios to avoid common loading issues:

• Avoid lazy CSS loading
• Remove lazy loading and force eager on all images and iframes
• Avoid asynchronous image decoding
• Force Drupal.blazy to load all images
• Pause the Slick slider autoplay
• Pause the Swiper slider autoplay
• Force oembed-lazyload videos to not load
• Stop the HTML video and go to the second one
• Wait for fonts to load
• Wait for the page to load completely
• Allow setting the cookiePath for the cookies.json globally to apply to all scenarios. If set in the scenario configuration, it will override the global configuration.

Stop animations

It allows stopping the CSS animations on the provided CSS selectors. This can be set on each scenario using the stopAnimationsSelectors property.

"scenarios": [
  {
    "label": "Stop animations example",
    "stopAnimationsSelectors": ".selector, .selector-2"
  }
]

Disable filters

CSS filters can be disabled on the provided CSS selectors. This can be set on each scenario using the disableFiltersSelectors property.

"scenarios": [
  {
    "label": "Disable filters example",
    "disableFiltersSelectors": ".selector, .selector-2"
  }
]

Log in and navigate to a specific page

It allows users to log in and navigate to a specific page before taking a screenshot. To use this feature you need to set at least the following options:

• loginWrapperSelector - The selector of the element that wraps the login form.
• loginUser - The username to login with
• loginPass - The password to login with

Optionally, loginRedirectTo can be set to navigate to a specific page after login.

"scenarios": [
  {
    "label": "Login and navigate to a specific page",
    "loginWrapperSelector": ".login-form",
    "loginUser": "user",
    "loginPass": "pass",
    "loginRedirectTo": "/admin"
  }
]

loginUser and loginPass can be set globally in the 'backstopjsAddons' settings or in the scenario configuration. If you set the login in the global configuration, you can override it in the scenario configuration.

"backstopjsAddons": {
  "loginUser": "global username",
  "loginPass": "global pass"
}

The removeSelectors option is applied after login and navigation.

Wait for selector after interaction

This option allows to wait for a selector to appear after an interaction. This feature is configured within a scenario using the `waitForSelectorAfterInteraction' property, which takes a CSS selector.

"scenarios": [
  {
    "label": "Click an wait for selector example",
    "waitForSelectorAfterInteraction": ".selector"
  }
]

Custom user agent by viewport

Allow a user agent to be set on the viewport.

"viewports": [
  {
    "label": "phone",
    "width": 375,
    "height": 667
    "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_3_1 like Mac OS X) AppleWebKit/603.1.30 (KHTML, like Gecko) Version/10.0 Mobile/14E304 Safari/602.1"
  },
]

Hide iframe content

This option replaces the specified iframe(s) with a grey background, maintaining the size of the iframe. This feature is configured within a scenario using the `hideIframeContent' property, which takes a comma-separated list of CSS selectors.

"scenarios": [
  {
    "label": "Hide iframe content example",
    "hideIframeContent": ".iframe-container-selector, .iframe-container-selector-2"
  }
]

Scenario load options

After all the scenario optimisations have been performed, the BackstopJS addons wait for the page to load completely. This uses the waitForNetworkIdle() function in Puppeteer to wait for the network to become idle. The 'networkOptions' option allows you to override this setting either globally or on a per-scenario basis.

If not set, the "default" value will be applied.

"scenarios": [
  {
    "label": "Hide iframe content example",
    "networkOptions": {"concurrency" : 1 }
  }
]