@cuppet/core 1.0.0

package/src/helperFunctions.js

@@ -0,0 +1,183 @@
+/**
+ * @module helperFunctions
+ * @typedef {import('puppeteer').Page} Page
+ * @typedef {import('puppeteer').Browser} Browser
+ */
+const config = require('config');
+const strings = require('../features/app/multilingualStrings/multilingualStrings');
+module.exports = {
+    /**
+     * Waits for a keypress event to continue the test execution.
+     * Please use only for local execution as it doesn't resolve automatically.
+     *
+     * @returns {Promise<void>} - A promise that resolves when a keypress event occurs.
+     */
+    waitForKeypress: async function () {
+        process.stdin.setRawMode(true);
+        return new Promise((resolve) =>
+            process.stdin.once('data', () => {
+                process.stdin.setRawMode(false);
+                resolve();
+            })
+        );
+    },
+
+    /**
+     * Generate random string with custom length
+     * @param length
+     * @returns {string}
+     */
+    generateRandomString: function (length) {
+        return Math.random()
+            .toString(36)
+            .substring(2, length + 2);
+    },
+
+    /**
+     * Wait until AJAX request is completed
+     * @param {Page} page
+     * @returns {Promise<void>}
+     */
+    waitForAjax: async function (page) {
+        const jsCode = "typeof jQuery === 'undefined' || (jQuery.active === 0 && jQuery(':animated').length === 0)";
+        await page.waitForFunction(jsCode);
+    },
+
+    /**
+     * Returns the translated variant of the inputted text or the text itself if there isn't a translation.
+     * @param text
+     * @returns {Promise<string>}
+     */
+    getMultilingualString: async function (text) {
+        const lang = config.has('language') ? config.get('language') : null;
+        let result;
+        if (lang) {
+            let string = strings.multilingualStrings(lang, text);
+            result = string ?? text;
+        } else {
+            result = text;
+        }
+        return result;
+    },
+
+    /**
+     * Retrieves the class name of an element based on a property in the config json.
+     * You can set directly the full class, partial or ID, but mind that it always resolves to
+     * the full className of that element.
+     *
+     * @param {Object} page - The page object representing the web page.
+     * @param {string} region - The region of the page to search for the element.
+     * @returns {Promise<string>} - A promise that resolves to the class name of the element.
+     */
+    getRegion: async function (page, region) {
+        const regionMap = config.get('regionMap');
+        const el = await page.waitForSelector(regionMap[region]);
+        return await (await el.getProperty('className')).jsonValue();
+    },
+
+    /**
+     * Assert that array is in alphabetical order
+     *
+     * @param  {Array} arr
+     * @param  {string|number} propKey - json property when element items are objects or array key for simple arrays
+     * @returns {boolean}
+     */
+    isArraySorted: function (arr, propKey) {
+        let sortedArr = arr;
+        sortedArr.sort((a, b) => a[propKey].localeCompare(b[propKey]));
+
+        return JSON.stringify(arr) === JSON.stringify(sortedArr);
+    },
+
+    /**
+     * Method which checks whether it's an AJAX request or normal page(doc) request.
+     * If it's an AJAX it adds hardcoded 2s wait to allow for element rendering, otherwise
+     * the next step waitForSelector is triggered before the AJAX completes, and it will never find the element
+     * because it uses the old page state.
+     * If it's a non-interactive(dropdown, checkbox, autocomplete option etc.) element please use the corresponding step.
+     * @param {Page} page
+     * @returns {Promise<void>}
+     */
+    afterClick: async function (page) {
+        // Listen for page or ajax requests
+        async function handleRequest(request) {
+            try {
+                if (['xhr', 'fetch'].includes(request.resourceType())) {
+                    await page.waitForResponse(() => true, { timeout: 10000 });
+                    return 'AJAX';
+                } else if (request.resourceType() === 'document') {
+                    await page.waitForNavigation({ timeout: 10000 });
+                    return 'Document';
+                } else {
+                    // Simple wait for cases where the click was over element which changes via CSS/JS not request.
+                    await new Promise((resolve) => setTimeout(resolve, 200));
+                    return true;
+                }
+            } catch {
+                return 'Timeout';
+            }
+        }
+        page.once('request', async (request) => {
+            const isAjax = await handleRequest(request);
+            if (isAjax === 'AJAX') {
+                // Add wait after AJAX so that there is enough time to render the response from it
+                await new Promise((resolve) => setTimeout(resolve, 200));
+            }
+        });
+    },
+
+    /**
+     * Go back to original page (first tab)
+     * To be used when you have more than one tabs open, and you want to go back to the first.
+     * @param {Browser} browser
+     * @returns {Promise<Object>}
+     */
+    openOriginalTab: async function (browser) {
+        const pages = await browser.pages();
+        // Switch to the original/initial tab - [0]
+        // For complex handling of more than 2 tabs use switchToTab() method.
+        await pages[0].bringToFront(); // Switch to the original tab
+        return pages[0];
+    },
+
+    /**
+     * Switching between open tabs
+     * @param {Browser} browser
+     * @param {number} tabIndex - the number of the tab (first tab is 1, not 0 for better UX)
+     * @returns {Promise<Object>}
+     */
+    switchToTab: async function (browser, tabIndex) {
+        let pages = await browser.pages();
+        let tabNumber = Number(tabIndex);
+        if (tabNumber < 1) {
+            throw new Error('Please provide a valid tab number - 1,2,3 etc.');
+        }
+
+        let attempts = 0;
+        // Pages is an array, thus tab 1 is 0, tab 2 is 1 etc.
+        // We need this subtraction by 1 for both the loop and the return of the new page object.
+        const num = tabNumber - 1;
+        while (pages.length <= num && attempts < 40) {
+            await new Promise((resolve) => setTimeout(resolve, 100)); // wait for 100ms before checking again
+            pages = await browser.pages();
+            attempts++;
+        }
+
+        if (tabNumber > pages.length) {
+            throw new Error(`The opened tabs are ${pages.length}, you entered ${tabNumber}`);
+        }
+
+        await pages[num].bringToFront();
+        return pages[num];
+    },
+    /**
+     * Replace the incompatible chars from a URL with _ so that the string can be used in a filename.
+     * @param path
+     * @returns {Promise<string>}
+     */
+    prepareFileNameFromUrl: async function (path) {
+        const newUrl = new URL(path);
+        let pathName = newUrl.pathname;
+        return pathName.replace(/[^a-z0-9]/gi, '_').toLowerCase();
+    },
+};

package/src/lighthouse.js

@@ -0,0 +1,23 @@
+/**
+ * @module lighthouse
+ * @typedef {import('puppeteer').Page} Page
+ */
+const dataStorage = require('./dataStorage');
+const helper = require('./helperFunctions');
+
+module.exports = {
+    /**
+     *
+     * @param {Page} page
+     * @param path
+     * @param scenarioName
+     * @returns {Promise<void>}
+     */
+    validatePageSpeed: async function (page, path, scenarioName) {
+        const { default: lighthouse, generateReport: report } = await import('lighthouse');
+        const { lhr } = await lighthouse(path, undefined, undefined, page);
+        const reportHtml = report(lhr, 'html');
+        const fileName = await helper.prepareFileNameFromUrl(path);
+        await dataStorage.createHtmlReport('LightHouse-' + scenarioName.slice(0, -1) + fileName, reportHtml);
+    },
+};

package/src/mainFunctions.js

@@ -0,0 +1,288 @@
+/**
+ * @module mainFunctions
+ * @typedef {import('puppeteer').Page} Page
+ * @typedef {import('puppeteer').Browser} Browser
+ */
+const config = require('config');
+
+module.exports = {
+    /**
+     * Prepare the URL using the config to get the domain and then
+     * based on the path variable to either generate a full path or replace it
+     * when path is absolute URL.
+     * @param path
+     * @returns {Promise<string>}
+     */
+    prepareUrl: async function (path) {
+        if (path.startsWith('http')) {
+            return path;
+        }
+        let baseUrl = config.get('credentials.baseUrl').toString();
+        if (baseUrl.endsWith('/')) {
+            baseUrl = baseUrl.slice(0, -1);
+        }
+        if (path === '/' || path === 'homepage' || path === 'home') {
+            return baseUrl;
+        }
+        return baseUrl + path;
+    },
+
+    /**
+     * Return current page URL - absolute or relative
+     * @param {Page} page
+     * @param {boolean} absolute - set to true if you want to extract the full path (with domain)
+     * @returns {string}
+     */
+    extractPath: function (page, absolute = false) {
+        const url = new URL(page.url());
+        const href = url.href;
+        const origin = url.origin;
+        if (absolute) {
+            return href;
+        }
+        return href.replace(origin, '');
+    },
+
+    /**
+     * Visit a certain URL. Can be relative or absolute.
+     * The step also supports auto select of a cookie consent if configured.
+     * @param {Page} page
+     * @param path
+     * @returns {Promise<void>}
+     */
+    visitPath: async function (page, path) {
+        const url = await this.prepareUrl(path);
+        try {
+            await page.goto(url, { waitUntil: 'domcontentloaded' });
+        } catch (error) {
+            throw new Error(`The requested page cannot be opened!: ${error}`);
+        }
+        if (config.has('blockingCookie')) {
+            const selector = config.get('blockingCookie');
+            await new Promise(function (resolve) {
+                setTimeout(resolve, 1000);
+            });
+            const cookie = await page.$(selector);
+            if (cookie) {
+                await cookie.click();
+            }
+        }
+    },
+
+    /**
+     * Visit current page concatenated with another path.
+     * Example localhost.com/listing -> localhost.com/listing/page-1
+     * @param {Page} page
+     * @param plus
+     * @returns {Promise<void>}
+     */
+    visitCurrentPathPlus: async function (page, plus) {
+        if (!plus.startsWith('/')) {
+            throw new Error('The path alias must start with a slash!');
+        }
+        let path = page.url();
+        if (path.endsWith('/')) {
+            path = path.slice(0, -1);
+        }
+        await page.goto(path + plus, { waitUntil: 'domcontentloaded' });
+    },
+
+    /**
+     * Reload the current page
+     * @param {Page} page
+     * @returns {Promise<void>}
+     */
+    reloadPage: async function (page) {
+        await page.reload({ waitUntil: 'domcontentloaded' });
+    },
+
+    /**
+     * Reload the current page and add get params
+     * @param {Page} page
+     * @param params
+     * @returns {Promise<void>}
+     */
+    reloadPageWithParams: async function (page, params) {
+        const currentUrl = this.extractPath(page);
+        if (!params.startsWith('?')) {
+            throw new Error("Invalid get param provided. Use '?' as first character.");
+        }
+        const newPath = currentUrl + params;
+        await this.visitPath(page, newPath);
+    },
+
+    /**
+     * Validate whether the current page is the one you should be on
+     * @param {Page} page
+     * @param path
+     * @returns {void}
+     */
+    validatePath: function (page, path) {
+        const pathAlias = this.extractPath(page);
+        if (pathAlias !== path) {
+            throw new Error(`The current path ${pathAlias} does not match the expected: ${path}!`);
+        }
+    },
+
+    /**
+     * Validate the last path in an alias
+     * @param {Page} page
+     * @param path
+     * @returns {void}
+     */
+    validatePathEnding: function (page, path) {
+        let pathAlias = this.extractPath(page);
+        if (pathAlias.endsWith('/')) {
+            pathAlias = pathAlias.slice(0, -1);
+        }
+        const splitAlias = pathAlias.split('/');
+        let lastElement;
+        if (Array.isArray(splitAlias)) {
+            lastElement = splitAlias[splitAlias.length - 1];
+        }
+        if (lastElement !== path) {
+            throw new Error(`The last path alias of ${pathAlias} does not match the expected: ${path}!`);
+        }
+    },
+
+    /**
+     * Validate http response code
+     * @param {Page} page
+     * @param code
+     * @param path
+     * @returns {Promise<void>}
+     */
+    validateStatusCode: async function (page, code, path) {
+        let baseUrl = config.get('credentials.baseUrl');
+        if (baseUrl.endsWith('/')) {
+            baseUrl = baseUrl.slice(0, -1);
+        }
+        const response = await page.goto(baseUrl + path);
+        const statusCode = response.status();
+        if (statusCode !== Number(code)) {
+            throw new Error(`The status code of the response: ${statusCode} does not match the expected!`);
+        }
+    },
+
+    /**
+     * Open new tab and switch to it (manually open tab and load a page)
+     * @param {Browser} browser
+     * @param url
+     * @returns {Promise<Object>}
+     */
+    openNewTab: async function (browser, url) {
+        const page = await browser.newPage();
+        await this.visitPath(page, url);
+        // Get all pages
+        const pages = await browser.pages();
+        // Switch to the new tab
+        return pages[pages.length - 1];
+    },
+
+    /**
+     * Validate current page response headers.
+     * @param {Page} page
+     * @param header
+     * @param value
+     * @returns {Promise<void>}
+     */
+    validatePageResponseHeaders: async function (page, header, value) {
+        const refreshPage = await page.reload({ waitUntil: 'domcontentloaded' });
+        const responseHeaders = refreshPage.headers();
+        if (responseHeaders[header.toLowerCase()] !== value) {
+            throw new Error('Response headers do not match the requirement!');
+        }
+    },
+
+    /**
+     * Verify cookie existence by name
+     * @param {object} page
+     * @param {string} cookieName
+     * @param {boolean} presence
+     * @returns {Promise<void>}
+     */
+    verifyCookiePresence: async function (page, cookieName, presence) {
+        let result;
+        const jsCode = `(function (name) {
+                var dc = document.cookie;
+                var prefix = name + '=';
+                var begin = dc.indexOf('; ' + prefix);
+                if (begin == -1) {
+                    begin = dc.indexOf(prefix);
+                    if (begin != 0) return null;
+                }
+                else
+                    {
+                        begin += 2;
+                        var end = document.cookie.indexOf(';', begin);
+                        if (end == -1) {
+                            end = dc.length;
+                        }
+                }
+                return decodeURI(dc.substring(begin + prefix.length, end));
+            })('${cookieName}');`;
+        try {
+            result = await page.evaluate(jsCode);
+        } catch (error) {
+            throw new Error(`There was an error when evaluating the code. ${error}`);
+        }
+
+        if (result) {
+            if (!presence) {
+                throw new Error(`The cookie ${cookieName} is present, but it shouldn't!`);
+            }
+        } else if (!result) {
+            if (presence) {
+                throw new Error(`The cookie ${cookieName} is not present, but it should!`);
+            }
+        }
+    },
+    /**
+     * Sets the viewport of the given page to match the specified device's dimensions.
+     *
+     * @param {Object} page - The page object where the viewport should be set.
+     * @param {string} device - The name of the device whose viewport dimensions should be applied.
+     * @throws {Error} Throws an error if the specified device is not defined in the configuration.
+     */
+    setViewport: async function (page, device) {
+        const viewport = config.get('viewport');
+
+        if (!viewport[device]) {
+            throw new Error(
+                `Viewport for device "${device}" is not defined in config.\nAvailable devices are: ${Object.keys(viewport).join(', ')}`
+            );
+        }
+        await page.setViewport({
+            width: viewport[device]['width'],
+            height: viewport[device]['height'],
+        });
+    },
+    /**
+     * Handle browser alert dialog and validate its text
+     * @param {Page} page
+     * @param {boolean} accept - true to accept/confirm, false to dismiss/cancel
+     * @param {string} expectedText - the expected text in the dialog
+     * @returns {Promise<void>}
+     */
+    handleAlert: async function (page, accept, expectedText = null) {
+        try {
+            page.on('dialog', async (dialog) => {
+                if (expectedText !== null) {
+                    const actualText = dialog.message();
+                    if (actualText !== expectedText) {
+                        throw new Error(
+                            `Alert dialog text mismatch. Expected: "${expectedText}", Got: "${actualText}"`
+                        );
+                    }
+                }
+                if (accept) {
+                    await dialog.accept();
+                } else {
+                    await dialog.dismiss();
+                }
+            });
+        } catch (error) {
+            throw new Error(`Could not handle alert dialog: ${error}`);
+        }
+    },
+};

package/src/visualRegression.js

@@ -0,0 +1,67 @@
+const config = require('config');
+const backStop = require('backstopjs');
+const backStopConfig = require('../backStopData/backStopConfig.json');
+
+module.exports = {
+    /**
+     *
+     * @returns {Object} - the backstop configuration object
+     */
+    backstopConfigPrepare: function () {
+        let newConfig = backStopConfig;
+        newConfig.id = process.env.NODE_CONFIG_ENV;
+        newConfig.viewports[0].width = Number(config.get('viewport.width'));
+        newConfig.viewports[0].height = Number(config.get('viewport.height'));
+        newConfig.engineOptions.args = config.get('args');
+        return newConfig;
+    },
+
+    /**
+     *
+     * @param command
+     * @param configObject
+     * @returns {Promise<void>}
+     */
+    runBackStop: async function (command, configObject) {
+        await backStop(command, { config: configObject })
+            .then(() => {
+                console.log(`${command} backstop run executed successfully!`);
+                // test successful
+            })
+            .catch((error) => {
+                throw new Error(error);
+            });
+    },
+
+    /**
+     *
+     * @param scenarioName
+     * @param path
+     * @param testCommand
+     * @returns {Promise<void>}
+     */
+    runBackStopSingleScenario: async function (scenarioName, path, testCommand) {
+        const newConfig = this.backstopConfigPrepare();
+        newConfig.scenarios[0].label = scenarioName;
+        newConfig.scenarios[0].url = path;
+        await this.runBackStop(testCommand, newConfig);
+    },
+    /**
+     *
+     * @param pages
+     * @param testCommand
+     * @returns {Promise<void>}
+     */
+    runBackstopMultiplePages: async function (pages, testCommand) {
+        const newConfig = this.backstopConfigPrepare();
+        newConfig.scenarios = [];
+        pages.forEach((page) => {
+            newConfig.scenarios.push({
+                label: page.label,
+                url: page.url,
+                // Add other scenario properties as needed...
+            });
+        });
+        await this.runBackStop(testCommand, newConfig);
+    },
+};

package/stepDefinitions.js

@@ -0,0 +1,17 @@
+// Cuppet Core Step Definitions
+// This file exports all step definitions for use in consuming projects
+
+module.exports = {
+    accessibilitySteps: require('./features/app/stepDefinitions/accessibilitySteps'),
+    apiSteps: require('./features/app/stepDefinitions/apiSteps'),
+    appiumSteps: require('./features/app/stepDefinitions/appiumSteps'),
+    generalSteps: require('./features/app/stepDefinitions/generalSteps'),
+    helperSteps: require('./features/app/stepDefinitions/helperSteps'),
+    iframeSteps: require('./features/app/stepDefinitions/iframeSteps'),
+    ifVisibleSteps: require('./features/app/stepDefinitions/ifVisibleSteps'),
+    lighthouseSteps: require('./features/app/stepDefinitions/lighthouseSteps'),
+    pageElements: require('./features/app/stepDefinitions/pageElements'),
+    pageElementsConfig: require('./features/app/stepDefinitions/pageElementsConfig'),
+    pageElementsJson: require('./features/app/stepDefinitions/pageElementsJson'),
+    visualRegressionSteps: require('./features/app/stepDefinitions/visualRegressionSteps')
+};