From 05cdafd0cc43b159ed977de63696e34ccfb9e047 Mon Sep 17 00:00:00 2001 From: lpeidro Date: Mon, 28 Oct 2024 10:27:26 +0100 Subject: [PATCH] Issue #0: Move and merge README --- README.md | 105 +++++++++++++++++++++++++++++++++++++++++++++-- addons/README.md | 98 ------------------------------------------- 2 files changed, 101 insertions(+), 102 deletions(-) delete mode 100644 addons/README.md diff --git a/README.md b/README.md index 449dec4..1ed041f 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ # BackstopJS Addons A library that extends and improves the default options provided by [BackstopJS](https://github.com/garris/BackstopJS). -### Composer +## Installation -``composer require --dev metadrop/backstopjs-addons`` +```bash +composer require --dev metadrop/backstopjs-addons +``` -You can override the default destination of the library ("tests/backstopjs/common/libraries/backstopjs-addons") by adding the following parameter to the extra section +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: ```json @@ -14,4 +16,99 @@ of your project's composer.json file: "path": "custom/destination" } ``` - \ No newline at end of file + +## 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 +- 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 +Allow stopping the CSS animations on the provided CSS selectors, can be set on each scenario using the `stopAnimationsSelectors` property. + +```json + "scenarios": [ + { + "label": "Stop animations example", + "stopAnimationsSelectors": ".selector, .selector-2" +``` + +### Disable filters +CSS filters can be disabled on the provided CSS selectors, can be set on each scenario using the `disableFiltersSelectors` property. + +```json + "scenarios": [ + { + "label": "Disable filters example", + "disableFiltersSelectors": ".selector, .selector-2" +``` + +### Log in and navigate to a specific page +Allow 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. + +```json + "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. + +```json + "backstopjsAddons": { + "loginUser": "global username", + "loginPass": "global pass" + } +``` + +The `removeSelectors` option is applied after login and navigation. + +### Wait for selector after interaction +This option allows you 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. + +```json + "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. + +```json + "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. + +```json + "scenarios": [ + { + "label": "Hide iframe content example", + "hideIframeContent": ".iframe-container-selector, .iframe-container-selector-2" +``` diff --git a/addons/README.md b/addons/README.md deleted file mode 100644 index ae468b5..0000000 --- a/addons/README.md +++ /dev/null @@ -1,98 +0,0 @@ -# BackstopJS Addons -A library that extends and improves the default options provided by [BackstopJS](https://github.com/garris/BackstopJS). - -## 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 - - 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 -Allow stopping the CSS animations on the provided CSS selectors, can be set on each scenario using the `stopAnimationsSelectors` property. - -```json - "scenarios": [ - { - "label": "Stop animations example", - "stopAnimationsSelectors": ".selector, .selector-2" -``` - -### Disable filters -CSS filters can be disabled on the provided CSS selectors, can be set on each scenario using the `disableFiltersSelectors` property. - -```json - "scenarios": [ - { - "label": "Disable filters example", - "disableFiltersSelectors": ".selector, .selector-2" -``` - -### Log in and navigate to a specific page -Allow 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. - -```json - "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. - -```json - "backstopjsAddons": { - "loginUser": "global username", - "loginPass": "global pass" - } -``` - -The `removeSelectors` option is applied after login and navigation. - -### Wait for selector after interaction -This option allows you 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. - -```json - "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. - -```json - "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. - -```json - "scenarios": [ - { - "label": "Hide iframe content example", - "hideIframeContent": ".iframe-container-selector, .iframe-container-selector-2" -```