@applitools/eyes-storybook 3.26.1 → 3.27.0

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 ## Unreleased
 
 
+## 3.27.0 - 2021/12/6
+
+- support custom properties and query params
+- remove `queryParams` api from story and global config
+
 ## 3.26.1 - 2021/11/28
 
 - add custom test properties to stories with query params

package/README.md

@@ -28,7 +28,6 @@ Applitools Eyes SDK for [Storybook](http://storybook.js.org).
       - [global](#global)
       - [component](#component)
     - [`variations`](#variations)
-    - [`queryParams`](#queryparams)
     - [`waitBeforeCapture`](#waitbeforecapture)
     - [`properties`](#properties)
     - [`ignoreRegions`](#ignoreregions)
@@ -181,7 +180,6 @@ In addition to command-line arguments, it's possible to define the following con
 | `waitBeforeCapture`    | undefined                   | Selector, function or timeout.<br/>If ```number``` then the argument is treated as time in milliseconds to wait before all screenshots.<br/>If ```string``` then the argument is treated as a selector for elements to wait for before all screenshots.<br/>If ```function```, then the argument is treated as a predicate to wait for before all screenshots.<br/><hr/>For per component configuration see [waitBeforeCapture.](#waitBeforeCapture)<br/>Note that we use Puppeteer's [page.waitForTimeout()](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagewaitfortimeoutmilliseconds), [page.waitForSelector()](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagewaitforselectorselector-options), [page.waitForXPath()](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagewaitforxpathxpath-options) and [page.waitForFunction()](https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagewaitforfunctionpagefunction-options-args), checkout it's API for more details. |
 | `include`                 | true                        | A predicate function, a string or a regular expression specifying which stories should be visually tested.<br/>Visual baselines will be created only for the components specified.<br/>The function receives an object with ```name```, ```kind```, ```storyTitle```  and ```parameters``` properties.<br/>For example (exclude all stories with a name that start with [SKIP]):<br/>```({name,  kind, storyTitle, parameters}) => !/^\[SKIP\]/.test(name)```<br/>For more information, see [per component configuration - include](#include). |
 | `variations`              | undefined                   | Specifies additional variations for all or some of the stories. For example, RTL. For more information, see [per component  configuration - variations](#variations).|
-| `queryParam`              | undefined                   | Specifies additional query parameters for all or some of the stories. For more information, see [per component  configuration - queryParams](#queryParams).|
 | `notifyOnCompletion`      | false                       | If `true` batch completion notifications are sent. |
 | `dontCloseBatches`        | false                       | If true, batches are not closed for notifyOnCompletion.|
 | `testConcurrency`             | 5                          | The maximum number of tests that can run concurrently. The default value is the allowed amount for free accounts. For paid accounts, set this number to the quota set for your account. |
@@ -425,10 +423,9 @@ storiesOf('Some kind', module)
 
 ### `variations`
 
-An array of string values, which specifies which variations to add for this story. For each value, an additional visual test will be executed for the component. It will have the same name only with a `[<variation name>]` suffix, and when the component is loaded, the URL will have an additional param: `eyes-variation=<variation name>`.
+An array of object values, which specifies which variations to add for this story. For each value, an additional visual test will be executed for the component. Each variation could contain `queryParams` and `properties` fields to specifies custom query parameters and eyes properties respectfully. Variation tests will have the same name.
 
-This can accommodate many use cases, for example RTL (right to left).
-It's now possible for the component to render its variation version when the relevant URL param is present. For Example, here's a storybook that handles an RTL variation:
+This can accommodate many use cases, for example `@storybook/addon-contexts`. With addons like this it is possible to render components in a different way depends on query parameters in URL. For Example, here's a storybook that handles an RTL variation:
 
 ```js
 const isRTL = new URL(window.location).searchParams.get('eyes-variation') === 'RTL';
@@ -445,17 +442,10 @@ storiesOf('Components that support RTL', module)
         <span>I am visually perfect!</span>
         <span>{isRTL ? ' and rendered right to left as well :)' : ''}</span>
       </div>,
-    {eyes: {variations: ['RTL']}}
+    {eyes: {variations: [{queryParams: {'eyes-variation': 'RTL'}, properties: {name: 'isRTL', value: 'true'}, {properties: {name: 'isRTL', value: 'false'}}]}}
   )
 ```
 
-### `queryParams`
-
-An array of object values, which specifies `name` and `value` of query parameter which will be added to the story. For each value, an additional visual test will be executed for the component. It will have the same name display name, but still generate a different baseline.
-
-This can accommodate many use cases, for example `@storybook/addon-contexts`.
-With addons like this it is possible to render components in a different way depends on query parameters in URL.
-
 ### `waitBeforeCapture`
 
 Selector or timeout, see [advanced configuration](#advanced-configuration) for more details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@applitools/eyes-storybook",
-  "version": "3.26.1",
+  "version": "3.27.0",
   "description": "",
   "engines": {
     "node": ">=8.6.0"

package/src/addVariationStories.js

@@ -0,0 +1,104 @@
+'use strict';
+
+function addVariationStories({stories, config}) {
+  const defaultStories = [];
+  const variationStories = {};
+  for (const story of stories) {
+    const variations = getStoryVariations(story, config);
+    if (variations) {
+      for (const variation of variations) {
+        const variationKey = stringifyVariation(variation);
+        const variationStoriesArray =
+          variationStories[variationKey] || (variationStories[variationKey] = []);
+        const variationStory = {...story};
+        if (variation.queryParams || variation.properties) {
+          variationStory.parameters = addVariation(story.parameters, variation);
+        }
+        variationStoriesArray.push(variationStory);
+      }
+    } else {
+      defaultStories.push(story);
+    }
+  }
+
+  return Object.values(variationStories).reduce((allStories, variationStories) => {
+    return allStories.concat(variationStories);
+  }, defaultStories);
+}
+
+function getStoryVariations(story, config) {
+  if (story.parameters && story.parameters.eyes && story.parameters.eyes.variations) {
+    if (!Array.isArray(story.parameters.eyes.variations)) {
+      throw new Error('variations should be an array');
+    }
+    return normalizeVariations(story.parameters.eyes.variations);
+  }
+
+  if (config.variations) {
+    if (Array.isArray(config.variations)) {
+      return normalizeVariations(config.variations);
+    } else if (typeof config.variations === 'function') {
+      const variations = config.variations(story);
+      if (variations) {
+        if (!Array.isArray(variations)) {
+          throw new Error('global variations should be a function that returns array');
+        }
+        return normalizeVariations(variations);
+      }
+    } else {
+      throw new Error('global variations should be an array or a function that returns array');
+    }
+  }
+}
+
+function normalizeVariations(variations) {
+  let shouldHasDefault = false; // default variation is one without query params
+  const normalizedVariations = variations.map(variation => {
+    if (typeof variation === 'string') {
+      shouldHasDefault = true;
+      return {
+        queryParams: {'eyes-variation': variation},
+        properties: [{name: 'eyes-variation', value: variation}],
+      };
+    }
+    if (variation.queryParams && (!variation.properties || variation.properties.length === 0)) {
+      return {
+        ...variation,
+        properties: Object.entries(variation.queryParams).map(([name, value]) => ({name, value})),
+      };
+    }
+    return variation;
+  });
+
+  // if it should has default variation and it is not already there
+  if (shouldHasDefault && !normalizedVariations.some(variation => !variation.queryParams)) {
+    normalizedVariations.unshift({});
+  }
+
+  return normalizedVariations;
+}
+
+function stringifyVariation(variation) {
+  if (!variation.queryParams) return '';
+  return Object.keys(variation.queryParams)
+    .sort()
+    .map(name => `${name}=${variation.queryParams[name]}`)
+    .join('&');
+}
+
+function addVariation(parameters, variation) {
+  parameters = {...parameters};
+  parameters.eyes = {...parameters.eyes};
+  if (variation.queryParams) {
+    parameters.eyes.queryParams = variation.queryParams;
+  }
+  if (variation.properties) {
+    parameters.eyes.properties = [
+      ...(parameters.eyes.properties || []),
+      ...(variation.properties || []),
+    ];
+  }
+  return parameters;
+}
+
+module.exports = addVariationStories;

package/src/eyesStorybook.js

@@ -10,7 +10,7 @@ const makeRenderStories = require('./renderStories');
 const makeGetStoryData = require('./getStoryData');
 const ora = require('ora');
 const filterStories = require('./filterStories');
-const addParametrizedStories = require('./addParametrizedStories');
+const addVariationStories = require('./addVariationStories');
 const browserLog = require('./browserLog');
 const memoryLog = require('./memoryLog');
 const getIframeUrl = require('./getIframeUrl');
@@ -116,12 +116,12 @@ async function eyesStorybook({
     );
 
     const filteredStories = filterStories({stories, config});
-    const storiesIncludingParametrizedVariations = addParametrizedStories({
+    const storiesIncludingVariations = addVariationStories({
       stories: filteredStories,
       config,
     });
 
-    logger.log(`starting to run ${storiesIncludingParametrizedVariations.length} stories`);
+    logger.log(`starting to run ${storiesIncludingVariations.length} stories`);
 
     const getStoryData = makeGetStoryData({
       logger,
@@ -158,7 +158,7 @@ async function eyesStorybook({
         setRenderIE,
         setTransitioningIntoIE,
         configs,
-        stories: storiesIncludingParametrizedVariations,
+        stories: storiesIncludingVariations,
         pagePool,
         logger,
         timeItAsync,

package/src/getStoryBaselineName.js

@@ -3,11 +3,17 @@ const getStoryTitle = require('./getStoryTitle');
 
 function getStoryBaselineName({name, kind, parameters}) {
   const storyTitle = getStoryTitle({name, kind, parameters});
-  const queryParam = parameters && parameters.eyes && parameters.eyes.queryParam;
+  const queryParams = parameters && parameters.eyes && parameters.eyes.queryParams;
+  if (!queryParams) return storyTitle;
+  const customQueryParams = {...queryParams};
+  delete customQueryParams['eyes-variation'];
+  if (Object.keys(customQueryParams).length === 0) return storyTitle;
 
-  if (!queryParam || queryParam.name === 'eyes-variation') return storyTitle;
+  const queryParamsString = Object.entries(customQueryParams)
+    .map(([name, value]) => `${name}=${value}`)
+    .join('&');
 
-  return `${storyTitle} [${queryParam.name}=${queryParam.value}]`;
+  return `${storyTitle} [${queryParamsString}]`;
 }
 
 module.exports = getStoryBaselineName;

package/src/getStoryData.js

@@ -15,19 +15,9 @@ function makeGetStoryData({logger, takeDomSnapshots, waitBeforeCapture, reloadPa
 
     const eyesParameters = story.parameters && story.parameters.eyes;
     if (story.isApi && !reloadPagePerStory) {
-      const expectedQueryParam = eyesParameters ? eyesParameters.queryParam : undefined;
-      const actualQueryParam = await getQueryParam(
-        eyesParameters && eyesParameters.queryParams
-          ? eyesParameters.queryParams.map(queryParam => queryParam.name)
-          : undefined,
-      );
-      if (
-        (!actualQueryParam && !expectedQueryParam) ||
-        (actualQueryParam &&
-          expectedQueryParam &&
-          actualQueryParam.value === expectedQueryParam.name &&
-          actualQueryParam.value === expectedQueryParam.value)
-      ) {
+      const currentUrl = page.url();
+      const expectedQueryParams = eyesParameters ? eyesParameters.queryParams : undefined;
+      if (urlQueryParamsEquals(currentUrl, expectedQueryParams)) {
         const err = await page.evaluate(renderStoryWithClientAPI, story.index);
         err && handleRenderStoryError(err);
       } else {
@@ -84,19 +74,28 @@ function makeGetStoryData({logger, takeDomSnapshots, waitBeforeCapture, reloadPa
       }
     }
 
-    async function getQueryParam(queryParamNames = []) {
+    function urlQueryParamsEquals(url, expectedQueryParams) {
       try {
-        const url = new URL(await page.url());
-        queryParamNames = [...queryParamNames, 'eyes-variation'];
-        const queryParamName = queryParamNames.find(queryParamName =>
-          url.searchParams.has(queryParamName),
-        );
-        if (queryParamName) {
-          return {name: queryParamName, value: url.searchParams.get(queryParamName)};
+        url = new URL(url);
+      } catch (err) {
+        logger.error('Error during parsing page url', err);
+        return false;
+      }
+
+      expectedQueryParams = expectedQueryParams || {};
+      const expectedQueryParamNames = Object.keys(expectedQueryParams);
+      const actualQueryParamNames = [];
+      for (const [name, value] of url.searchParams) {
+        if (['eyes-storybook', 'selectedKind', 'selectedStory'].includes(name)) continue;
+        if (!expectedQueryParams.hasOwnProperty(name) || !expectedQueryParams[name] === value) {
+          return false;
         }
-      } catch (ex) {
-        logger.log('failed to get url from page (in need of eyes-variation param)');
+        actualQueryParamNames.push(name);
       }
+
+      if (actualQueryParamNames.length !== expectedQueryParamNames.length) return false;
+
+      return true;
     }
 
     // TODO (amit): handle this error in the caller (probably renderStories)

package/src/getStoryTitle.js

@@ -1,11 +1,10 @@
 'use strict';
 
 function getStoryTitle({name, kind, parameters}) {
-  const queryParam = parameters && parameters.eyes && parameters.eyes.queryParam;
-  const variation =
-    queryParam && queryParam.name === 'eyes-variation' ? queryParam.value : undefined;
+  const queryParams = (parameters && parameters.eyes && parameters.eyes.queryParams) || {};
+  const eyesVariation = queryParams['eyes-variation'];
 
-  return `${kind}: ${name}${variation ? ` [${variation}]` : ''}`;
+  return `${kind}: ${name}${eyesVariation ? ` [${eyesVariation}]` : ''}`;
 }
 
 module.exports = getStoryTitle;

package/src/getStoryUrl.js

@@ -2,12 +2,15 @@
 const getIframeUrl = require('./getIframeUrl');
 
 function getStoryUrl({name, kind, parameters}, baseUrl) {
-  const queryParam = parameters && parameters.eyes && parameters.eyes.queryParam;
-  const queryParamString = queryParam ? `&${queryParam.name}=${queryParam.value}` : '';
+  const queryParams = (parameters && parameters.eyes && parameters.eyes.queryParams) || {};
+  const queryString = Object.entries(queryParams).reduce(
+    (queryString, [name, value]) => queryString + `&${name}=${value}`,
+    '',
+  );
 
   return `${getIframeUrl(baseUrl)}&selectedKind=${encodeURIComponent(
     kind,
-  )}&selectedStory=${encodeURIComponent(name)}${queryParamString}`;
+  )}&selectedStory=${encodeURIComponent(name)}${queryString}`;
 }
 
 module.exports = getStoryUrl;

package/src/renderStory.js

@@ -8,7 +8,12 @@ function makeRenderStory({logger, testWindow, performance, timeItAsync}) {
     const {name, kind, parameters} = story;
     const baselineName = getStoryBaselineName({name, kind, parameters});
     const title = getStoryTitle({name, kind, parameters});
-    const eyesOptions = Object.assign({}, config, (parameters && parameters.eyes) || {});
+    const eyesParameters = (parameters && parameters.eyes) || {};
+    const eyesOptions = {
+      ...config,
+      ...eyesParameters,
+      properties: [...(config.properties || []), ...(eyesParameters.properties || [])],
+    };
     const {
       ignoreDisplacements,
       ignoreRegions,
@@ -31,7 +36,6 @@ function makeRenderStory({logger, testWindow, performance, timeItAsync}) {
       visualGridOptions,
       useDom,
       enablePatterns,
-      queryParam,
     } = eyesOptions;
 
     if (sizeMode) {
@@ -52,10 +56,6 @@ function makeRenderStory({logger, testWindow, performance, timeItAsync}) {
       ...(properties || []),
     ];
 
-    if (queryParam) {
-      storyProperties.push(queryParam);
-    }
-
     const openParams = {
       testName: baselineName,
       displayName: title,

package/src/addParametrizedStories.js

@@ -1,81 +0,0 @@
-'use strict';
-
-function addParametrizedStories({stories, config}) {
-  const parametrizedStories = {};
-  for (const story of stories) {
-    const queryParams = getStoryQueryParams(story, config);
-    if (!queryParams) continue;
-    for (const queryParam of queryParams) {
-      const queryParamString = `${queryParam.name}=${queryParam.value}`;
-      const parametrizeStoriesArray =
-        parametrizedStories[queryParamString] || (parametrizedStories[queryParamString] = []);
-      parametrizeStoriesArray.push({
-        ...story,
-        parameters: addQueryParam(story.parameters, queryParam),
-      });
-    }
-  }
-
-  return Object.values(parametrizedStories).reduce((allStories, parametrizedStories) => {
-    return allStories.concat(parametrizedStories);
-  }, stories);
-}
-
-function getStoryQueryParams(story, config) {
-  let queryParams;
-  if (story.parameters && story.parameters.eyes && story.parameters.eyes.queryParams) {
-    if (!Array.isArray(story.parameters.eyes.queryParams)) {
-      throw new Error('queryParams should be an array');
-    }
-    queryParams = [...story.parameters.eyes.queryParams];
-  }
-  if (story.parameters && story.parameters.eyes && story.parameters.eyes.variations) {
-    if (!Array.isArray(story.parameters.eyes.variations)) {
-      throw new Error('variations should be an array');
-    }
-    queryParams = [
-      ...(queryParams || []),
-      ...variationsToQueryParams(story.parameters.eyes.variations),
-    ];
-  }
-
-  if (queryParams) return queryParams;
-
-  if (config.queryParams) {
-    if (!Array.isArray(config.queryParams)) {
-      throw new Error('global queryParams should be an array');
-    }
-    queryParams = [...config.queryParams];
-  }
-
-  if (config.variations) {
-    if (Array.isArray(config.variations)) {
-      queryParams = [...(queryParams || []), ...variationsToQueryParams(config.variations)];
-    } else if (typeof config.variations === 'function') {
-      const variations = config.variations(story);
-      if (variations) {
-        if (!Array.isArray(variations)) {
-          throw new Error('global variations should be a function that returns array');
-        }
-        queryParams = [...(queryParams || []), ...variationsToQueryParams(variations)];
-      }
-    } else {
-      throw new Error('global variations should be an array or a function that returns array');
-    }
-  }
-
-  if (queryParams) return queryParams;
-}
-
-function variationsToQueryParams(variations) {
-  return variations.map(variation => ({name: 'eyes-variation', value: variation}));
-}
-
-function addQueryParam(parameters, queryParam) {
-  parameters = {...parameters};
-  parameters.eyes = {...parameters.eyes};
-  parameters.eyes.queryParam = queryParam;
-  return parameters;
-}
-
-module.exports = addParametrizedStories;