@dotcms/experiments 0.0.1-alpha.37 → 0.0.1-alpha.39

package/src/lib/hooks/useExperimentVariant.spec.tsx

@@ -0,0 +1,111 @@
+import { renderHook } from '@testing-library/react-hooks';
+import React from 'react';
+
+import * as dotcmsClient from '@dotcms/client';
+
+import { useExperimentVariant } from './useExperimentVariant';
+
+import MockDotExperimentsContext from '../contexts/DotExperimentsContext';
+import { EXPERIMENT_DEFAULT_VARIANT_NAME } from '../shared/constants';
+import { LocationMock } from '../shared/mocks/mock';
+
+interface WrapperProps {
+    children: React.ReactNode;
+}
+
+const createMockDotExperimentsContext = (variantResponse: unknown) => {
+    const mockGetVariantFromHref = jest.fn().mockImplementation(() => variantResponse);
+
+    return React.createContext({
+        getVariantFromHref: mockGetVariantFromHref
+    });
+};
+
+jest.mock('../contexts/DotExperimentsContext', () => ({
+    __esModule: true,
+    default: createMockDotExperimentsContext({ name: 'variant-1' })
+}));
+
+const wrapper = ({ children }: WrapperProps) => (
+    // eslint-disable-next-line react-hooks/rules-of-hooks
+    <MockDotExperimentsContext.Provider value={React.useContext(MockDotExperimentsContext)}>
+        {children}
+    </MockDotExperimentsContext.Provider>
+);
+
+describe('useExperimentVariant', () => {
+    describe('shouldWaitForVariant `false`', () => {
+        it('if is insideEditor is `false`', () => {
+            const mockData = {
+                runningExperimentId: '1',
+                viewAs: { variantId: '1' }
+            };
+
+            jest.spyOn(dotcmsClient, 'isInsideEditor').mockReturnValue(true);
+
+            const { result } = renderHook(() => useExperimentVariant(mockData));
+
+            const { shouldWaitForVariant } = result.current;
+
+            expect(shouldWaitForVariant).toBe(false);
+        });
+
+        it(' if `runningExperimentId` is undefined', () => {
+            const mockData = {
+                viewAs: { variantId: EXPERIMENT_DEFAULT_VARIANT_NAME }
+            };
+
+            jest.spyOn(dotcmsClient, 'isInsideEditor').mockReturnValue(false);
+
+            const { result } = renderHook(() => useExperimentVariant(mockData));
+
+            const { shouldWaitForVariant } = result.current;
+
+            expect(shouldWaitForVariant).toBe(false);
+        });
+
+        it(' if VariantId get from `PageApi` is same of VariantAssigned', () => {
+            const locationSpy = jest.spyOn(window, 'location', 'get');
+
+            const locationMock = { ...LocationMock, pathname: '/blog' };
+
+            locationSpy.mockReturnValue(locationMock);
+
+            jest.spyOn(dotcmsClient, 'isInsideEditor').mockReturnValue(false);
+
+            const { result } = renderHook(
+                () =>
+                    useExperimentVariant({
+                        runningExperimentId: 'exp-id',
+                        viewAs: { variantId: 'variant-1' }
+                    }),
+                { wrapper }
+            );
+
+            expect(result.current.shouldWaitForVariant).toBe(false);
+        });
+
+        describe('shouldWaitForVariant `true`', () => {
+            it(' if VariantId get from `PageApi` is different of VariantAssigned', () => {
+                const locationSpy = jest.spyOn(window, 'location', 'get');
+
+                const locationMock = { ...LocationMock, pathname: '/blog' };
+
+                locationSpy.mockReturnValue(locationMock);
+
+                jest.spyOn(dotcmsClient, 'isInsideEditor').mockReturnValue(false);
+
+                const { result } = renderHook(
+                    () =>
+                        useExperimentVariant({
+                            runningExperimentId: 'exp-id',
+                            viewAs: { variantId: EXPERIMENT_DEFAULT_VARIANT_NAME }
+                        }),
+                    { wrapper }
+                );
+
+                expect(result.current.shouldWaitForVariant).toBe(true);
+            });
+        });
+    });
+});

package/src/lib/hooks/useExperimentVariant.ts

@@ -0,0 +1,55 @@
+import { useContext, useEffect, useState } from 'react';
+
+import { isInsideEditor } from '@dotcms/client';
+
+import DotExperimentsContext from '../contexts/DotExperimentsContext';
+
+/**
+ * A React Hook that determines whether to wait for the correct variant in an A/B testing scenario.
+ * This is used to avoid flickering - showing the original content before redirecting to the assigned variant.
+ *
+ * The hook uses the running experiment id and viewAs (containing variantId) from the provided data.
+ * It then works with the DotExperimentsContext to synchronize between the assigned variant and the one requested.
+ * If the hook is executed inside an editor or if no running experiment id is provided, it immediately signals not to wait for the variant.
+ * Similarly, if the assigned variant matches the requested one, it signals not to wait for the variant.
+ * By default, the hook signals to wait for the variant.
+ *
+ * @param {Object} data - An object containing the runningExperimentId and viewAs (containing variantId).
+ * @returns {Object} An object with a function `shouldWaitForVariant` that, when called, returns `true` if it should wait for the correct variant, `false` otherwise.
+ */
+export const useExperimentVariant = (data: {
+    runningExperimentId?: string;
+    viewAs: { variantId: string };
+}): { shouldWaitForVariant: boolean } => {
+    const dotExperimentInstance = useContext(DotExperimentsContext);
+
+    const { runningExperimentId, viewAs } = data;
+
+    const { variantId } = viewAs;
+
+    // By default, wait for the variant
+    const [shouldWaitForVariant, setShouldWaitForVariant] = useState<boolean>(true);
+
+    useEffect(() => {
+        if (isInsideEditor() || !runningExperimentId) {
+            setShouldWaitForVariant(false);
+
+            return;
+        }
+
+        const location = typeof window !== 'undefined' ? window.location : undefined;
+
+        if (location && dotExperimentInstance) {
+            const variantAssigned = dotExperimentInstance.getVariantFromHref(location.pathname);
+
+            if (variantAssigned && variantId === variantAssigned.name) {
+                // the data requested and the variant assigned is the correct no need to wait
+                setShouldWaitForVariant(false);
+
+                return;
+            }
+        }
+    }, [dotExperimentInstance, data]);
+
+    return { shouldWaitForVariant };
+};

package/src/lib/hooks/useExperiments.ts

@@ -0,0 +1,90 @@
+import { useEffect } from 'react';
+
+import { isInsideEditor } from '@dotcms/client';
+
+import { DotExperiments } from '../dot-experiments';
+import { EXPERIMENT_DEFAULT_VARIANT_NAME, EXPERIMENT_QUERY_PARAM_KEY } from '../shared/constants';
+
+/**
+ * Custom hook `useExperiments`.
+ *
+ * This hook is designed to handle changes in the location of the current DotExperiments
+ * instance and set a global click handler that redirects the application when an element with an
+ * assigned variant is clicked.
+ *
+ * It also manages adding or removing the experimentation query parameter from the URL as
+ * appropriate when a click occurs.
+ *
+ * @returns {void}
+ */
+export const useExperiments = (instance: DotExperiments | null): void => {
+    /**
+     * This `useEffect` hook is responsible for tracking location changes when not inside an editor environment, and invoking the
+     * `locationChanged` method from `experimentContext` with current location and custom redirection function.
+     *
+     */
+    useEffect(() => {
+        if (!instance || typeof document === 'undefined') {
+            return;
+        }
+
+        const insideEditor = isInsideEditor();
+
+        if (!insideEditor) {
+            const location = typeof window !== 'undefined' ? window.location : undefined;
+
+            if (instance && location) {
+                instance.locationChanged(location, instance.customRedirectFn);
+            }
+        }
+    }, [instance]);
+
+    /**
+     * This effect sets a click handler on the document.
+     * It captures click events and redirects to a new URL if the clicked anchor has a variant assigned,
+     * additional removing the experiment query param from the URL.
+     */
+    useEffect(() => {
+        if (!instance) {
+            return;
+        }
+
+        const customClickHandler = (event: MouseEvent) => {
+            const target = (event.target as HTMLElement).closest('a');
+
+            if (!target) {
+                return;
+            }
+
+            const clickedHref = target.getAttribute('href');
+
+            if (clickedHref) {
+                const modifiedUrl = new URL(clickedHref, instance.location.href);
+
+                // Remove the experiment query param from the URL
+                modifiedUrl.searchParams.delete(EXPERIMENT_QUERY_PARAM_KEY);
+
+                event.preventDefault();
+
+                // Get the variant from the href of the clicked anchor
+                const variant = instance.getVariantFromHref(clickedHref);
+
+                if (variant && variant.name !== EXPERIMENT_DEFAULT_VARIANT_NAME) {
+                    // Set the experiment query param in the URL if the variant is not the default one
+                    modifiedUrl.searchParams.set(EXPERIMENT_QUERY_PARAM_KEY, variant.name);
+                }
+
+                // Redirect to the new URL using the custom redirect function
+                instance.customRedirectFn(modifiedUrl.toString());
+            }
+        };
+
+        // Register the click handler to all elements in the document
+        document.addEventListener('click', customClickHandler);
+
+        return () => {
+            // Remove the click handler when the component is unmounted
+            document.removeEventListener('click', customClickHandler);
+        };
+    }, [instance]);
+};

package/src/lib/shared/{constants.d.ts → constants.ts}

@@ -3,34 +3,39 @@
  *
  * @constant {string}
  */
-export declare const EXPERIMENT_WINDOWS_KEY = "dotExperiment";
+export const EXPERIMENT_WINDOWS_KEY = 'dotExperiment';
+
 /**
  * The default variant name for an experiment.
  *
  * @type {string}
  * @constant
  */
-export declare const EXPERIMENT_DEFAULT_VARIANT_NAME = "DEFAULT";
+export const EXPERIMENT_DEFAULT_VARIANT_NAME = 'DEFAULT';
+
 /**
  * The key used to store or retrieve the information in the SessionStore
  *
  * @constant {string}
  */
-export declare const EXPERIMENT_QUERY_PARAM_KEY = "variantName";
+export const EXPERIMENT_QUERY_PARAM_KEY = 'variantName';
+
 /**
  * The key used to store or retrieve the information in the SessionStore
  * indicating whether an experiment has already been checked.
  *
  * @constant {string}
  */
-export declare const EXPERIMENT_ALREADY_CHECKED_KEY = "experimentAlreadyCheck";
+export const EXPERIMENT_ALREADY_CHECKED_KEY = 'experimentAlreadyCheck';
+
 /**
  * EXPERIMENT_FETCH_EXPIRE_TIME is a constant that represents the name of the variable used to store
  * the expire time for experiment fetching. It is a string value 'experimentFetchExpireTime'.
  *
  * @constant {string}
  */
-export declare const EXPERIMENT_FETCH_EXPIRE_TIME_KEY = "experimentFetchExpireTime";
+export const EXPERIMENT_FETCH_EXPIRE_TIME_KEY = 'experimentFetchExpireTime';
+
 /**
  * The duration in milliseconds for which data should be stored in the local storage.
  *
@@ -39,26 +44,34 @@ export declare const EXPERIMENT_FETCH_EXPIRE_TIME_KEY = "experimentFetchExpireTi
  * @default 86400000 (A day)
  *
  */
-export declare const LOCAL_STORAGE_TIME_DURATION_MILLISECONDS: number;
+export const LOCAL_STORAGE_TIME_DURATION_MILLISECONDS = 86400 * 1000;
+
 /**
  * The name of the experiment script file.
  *
  * @constant {string}
  */
-export declare const EXPERIMENT_SCRIPT_FILE_NAME = "dot-experiments.min.iife.js";
+export const EXPERIMENT_SCRIPT_FILE_NAME = 'dot-experiments.min.iife.js';
+
 /**
  * The prefix used for the experiment script data attributes.
  *
  * @constant {string}
  */
-export declare const EXPERIMENT_SCRIPT_DATA_PREFIX = "data-experiment-";
+export const EXPERIMENT_SCRIPT_DATA_PREFIX = 'data-experiment-';
+
 /**
  * Array containing the allowed data attributes for an experiment.
  *
  * @type {Array.<string>}
  * @constant
  */
-export declare const EXPERIMENT_ALLOWED_DATA_ATTRIBUTES: string[];
+export const EXPERIMENT_ALLOWED_DATA_ATTRIBUTES = [
+    EXPERIMENT_SCRIPT_DATA_PREFIX + 'api-key',
+    EXPERIMENT_SCRIPT_DATA_PREFIX + 'server',
+    EXPERIMENT_SCRIPT_DATA_PREFIX + 'debug'
+];
+
 /**
  * API_EXPERIMENTS_URL
  *
@@ -67,29 +80,33 @@ export declare const EXPERIMENT_ALLOWED_DATA_ATTRIBUTES: string[];
  * @type {string}
  * @constant
  */
-export declare const API_EXPERIMENTS_URL = "api/v1/experiments/isUserIncluded";
+export const API_EXPERIMENTS_URL = 'api/v1/experiments/isUserIncluded';
+
 /**
  * The name of the experiment database store in indexDB.
  *
  * @type {string}
  * @constant
  */
-export declare const EXPERIMENT_DB_STORE_NAME = "dotExperimentStore";
+export const EXPERIMENT_DB_STORE_NAME = 'dotExperimentStore';
+
 /**
  * The path to the key in the database IndexDB representing the running experiment data.
  * @type {string}
  */
-export declare const EXPERIMENT_DB_KEY_PATH = "running_experiment";
+export const EXPERIMENT_DB_KEY_PATH = 'running_experiment';
+
 /**
  * Enumeration of debug levels.
  *
  * @enum {string}
  * @readonly
  */
-export declare enum DEBUG_LEVELS {
-    NONE = "NONE",
-    DEBUG = "DEBUG",
-    WARN = "WARN",
-    ERROR = "ERROR"
+export enum DEBUG_LEVELS {
+    NONE = 'NONE',
+    DEBUG = 'DEBUG',
+    WARN = 'WARN',
+    ERROR = 'ERROR'
 }
-export declare const PAGE_VIEW_EVENT_NAME = "pageview";
+
+export const PAGE_VIEW_EVENT_NAME = 'pageview';

package/src/lib/shared/mocks/mock.ts

@@ -0,0 +1,209 @@
+import { Experiment, ExperimentEvent, IsUserIncludedApiResponse } from '../models';
+
+/**
+ * Represents the response object for the IsUserIncluded API.
+ * @typedef {Object} IsUserIncludedResponse
+ * @property {IsUserIncludedApiResponse} entity - The response entity.
+ * @property {string[]} errors - Array of error messages, if any.
+ * @property {Object} i18nMessagesMap - Map of internationalization messages.
+ * @property {string[]} messages - Array of additional messages, if any.
+ */
+export const IsUserIncludedResponse: IsUserIncludedApiResponse = {
+    entity: {
+        excludedExperimentIds: [],
+        excludedExperimentIdsEnded: [],
+        experiments: [
+            {
+                id: '11111-11111-11111-11111-11111',
+                lookBackWindow: {
+                    expireMillis: 1209600000,
+                    value: 'AAAAAAAAAA'
+                },
+                name: 'Exp1',
+                pageUrl: '/blog/index',
+                regexs: {
+                    isExperimentPage:
+                        '^(http|https):\\/\\/(localhost|127.0.0.1|\\b(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,})(:\\d{1,5})?\\/blog(\\/index|\\/)?(\\/?\\?.*)?$',
+                    isTargetPage: '.*destinations.*'
+                },
+                runningId: '1111111-22222222',
+                variant: {
+                    name: 'variant-1',
+                    url: '/blog/index?variantName=variant-1'
+                }
+            }
+        ],
+        includedExperimentIds: ['11111-11111-11111-11111-11111']
+    },
+    errors: [],
+    i18nMessagesMap: {},
+    messages: []
+};
+
+export const NewIsUserIncludedResponse: IsUserIncludedApiResponse = {
+    entity: {
+        excludedExperimentIds: ['11111-11111-11111-11111-11111'],
+        excludedExperimentIdsEnded: ['11111-11111-11111-11111-11111'],
+        experiments: [
+            {
+                id: '222222-222222-222222-222222-222222',
+                lookBackWindow: {
+                    expireMillis: 1209600000,
+                    value: 'BBBBBBBBBBBBBB'
+                },
+                name: 'Exp2',
+                pageUrl: '/destinations/index',
+                regexs: {
+                    isExperimentPage:
+                        '^(http|https):\\/\\/(localhost|127.0.0.1|\\b(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,})(:\\d{1,5})?\\/destinations(\\/index|\\/)?(\\/?\\?.*)?$',
+                    isTargetPage: null
+                },
+                runningId: '33333333-3333333333',
+                variant: {
+                    name: 'variant-1',
+                    url: '/blog/index?variantName=variant-1'
+                }
+            }
+        ],
+        includedExperimentIds: ['222222-222222-222222-222222-222222']
+    },
+    errors: [],
+    i18nMessagesMap: {},
+    messages: []
+};
+
+export const After15DaysIsUserIncludedResponse: IsUserIncludedApiResponse = {
+    entity: {
+        excludedExperimentIds: ['222222-222222-222222-222222-222222'],
+        excludedExperimentIdsEnded: [],
+        experiments: [],
+        includedExperimentIds: []
+    },
+    errors: [],
+    i18nMessagesMap: {},
+    messages: []
+};
+
+export const NoExperimentsIsUserIncludedResponse: IsUserIncludedApiResponse = {
+    entity: {
+        excludedExperimentIds: [],
+        excludedExperimentIdsEnded: [],
+        experiments: [],
+        includedExperimentIds: []
+    },
+    errors: [],
+    i18nMessagesMap: {},
+    messages: []
+};
+
+export const MOCK_CURRENT_TIMESTAMP = 1704096000000;
+
+export const TIME_15_DAYS_MILLISECONDS = 1296000 * 1000;
+
+export const TIME_5_DAYS_MILLISECONDS = 432000 * 1000;
+
+export const MockDataStoredIndexDB: Experiment[] = [
+    {
+        ...IsUserIncludedResponse.entity.experiments[0],
+        lookBackWindow: {
+            ...IsUserIncludedResponse.entity.experiments[0].lookBackWindow,
+            // Added expireTime to the lookBackWindow
+            expireTime:
+                MOCK_CURRENT_TIMESTAMP +
+                IsUserIncludedResponse.entity.experiments[0].lookBackWindow.expireMillis
+        }
+    }
+];
+
+export const MockDataStoredIndexDBNew: Experiment[] = [
+    {
+        ...NewIsUserIncludedResponse.entity.experiments[0],
+        lookBackWindow: {
+            ...NewIsUserIncludedResponse.entity.experiments[0].lookBackWindow,
+            // Added expireTime to the lookBackWindow
+            expireTime:
+                // 2nd request, 5 days later, so expireTime is 5 days from MOCK_CURRENT_TIMESTAMP
+                MOCK_CURRENT_TIMESTAMP +
+                TIME_5_DAYS_MILLISECONDS +
+                NewIsUserIncludedResponse.entity.experiments[0].lookBackWindow.expireMillis
+        }
+    }
+];
+
+// Final data to be stored in IndexedDB only the last, the first will be removed by was ended from `excludedExperimentIdsEnded`
+export const MockDataStoredIndexDBWithNew: Experiment[] = [...MockDataStoredIndexDBNew];
+
+// Mock Store after 15 days
+export const MockDataStoredIndexDBWithNew15DaysLater: Experiment[] = [...MockDataStoredIndexDBNew];
+
+/**
+ * Represents an event that indicates the expected experiments parsed from a response to send to Analytics.
+ *
+ * @typedef {Object} ExpectedExperimentsParsedEvent
+ * @property {ExperimentEvent[]} experiments - An array of experiment events.
+ */
+export const ExpectedExperimentsParsedEvent: ExperimentEvent[] = [
+    {
+        experiment: IsUserIncludedResponse.entity.experiments[0].id,
+        runningId: IsUserIncludedResponse.entity.experiments[0].runningId,
+        variant: IsUserIncludedResponse.entity.experiments[0].variant.name,
+        lookBackWindow: IsUserIncludedResponse.entity.experiments[0].lookBackWindow.value,
+        isExperimentPage: false,
+        isTargetPage: false
+    }
+];
+
+/**
+ * Represents a mock location object.
+ *
+ * @typedef {Object} LocationMock
+ * @property {string} href - The complete URL.
+ *
+ */
+export const LocationMock: Location = {
+    hash: '',
+    host: '',
+    hostname: '',
+    href: 'http://localhost/blog',
+    origin: '',
+    pathname: '',
+    port: '',
+    protocol: '',
+    search: '',
+    assign: () => {
+        //
+    },
+    replace: () => {
+        //
+    },
+    reload: () => {
+        //
+    },
+    toString: () => {
+        return '';
+    },
+    ancestorOrigins: {} as DOMStringList
+};
+
+const store: { [key: string]: string } = {};
+
+export const sessionStorageMock = {
+    getItem: function (key: string): string | null {
+        return store[key] || null;
+    },
+    setItem: function (key: string, value: string) {
+        store[key] = value;
+    },
+    removeItem: function (key: string) {
+        delete store[key];
+    },
+    clear: function () {
+        Object.keys(store).forEach((key) => delete store[key]);
+    },
+    key: function (index: number) {
+        return Object.keys(store)[index] || null;
+    },
+    get length() {
+        return Object.keys(store).length;
+    }
+};