pagean 6.0.3 → 6.0.7

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2019 - 2021 Aaron Goldenthal
+Copyright (c) 2019 - 2022 Aaron Goldenthal
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/index.js

@@ -1,5 +1,10 @@
 'use strict';
 
+/**
+ * Pagean test framework.
+ *
+ * @module pagean
+ */
 const puppeteer = require('puppeteer');
 
 const testLogger = require('./lib/logger');
@@ -7,7 +12,12 @@ const testReporter = require('./lib/reporter');
 const { ...testFunctions } = require('./lib/tests');
 const { createLinkChecker } = require('./lib/linkUtils');
 
-// eslint-disable-next-line max-lines-per-function
+/**
+ * Executes Pagean tests as specified in config and reports results.
+ *
+ * @static
+ * @param {object} config The Pagean test configuration.
+ */
 const executeAllTests = async (config) => {
     const logger = testLogger(config);
     const linkChecker = createLinkChecker();
@@ -23,8 +33,10 @@ const executeAllTests = async (config) => {
         page.on('console', msg => consoleLog.push({ _type: msg._type, _text: msg._text, _stackTraceLocations: msg._stackTraceLocations }));
         await page.goto(testUrl.url, { waitUntil: 'load' });
 
-        const testContext = { page, consoleLog,
-            urlSettings: { ...testUrl.settings, htmlHintConfig: config.htmlHintConfig }, logger, linkChecker };
+        const testContext = {
+            page, consoleLog,
+            urlSettings: { ...testUrl.settings, htmlHintConfig: config.htmlHintConfig }, logger, linkChecker
+        };
         for (const test of Object.keys(testFunctions)) {
             await testFunctions[test](testContext);
         }

package/lib/config.js

@@ -1,5 +1,11 @@
 'use strict';
 
+/**
+ * Functions for managing Pagean config files.
+ *
+ * @module config
+ */
+
 const fs = require('fs');
 const path = require('path');
 const Ajv = require('ajv').default;
@@ -86,6 +92,14 @@ const getConfigFromFile = (configFileName) => {
     return JSON.parse(fs.readFileSync(configFileName, 'utf-8'));
 };
 
+/**
+ * Loads config from file and returns consolidated config with
+ * defaults where values are not specified.
+ *
+ * @static
+ * @param   {string} configFileName Pagean configuration file name.
+ * @returns {object}                Consolidated Pagean configuration.
+ */
 const processConfig = (configFileName) => {
     const config = getConfigFromFile(configFileName);
     const { isValid } = validateConfigSchema(config);
@@ -101,6 +115,13 @@ const processConfig = (configFileName) => {
     };
 };
 
+/**
+ * Lints the configuration file schema.
+ *
+ * @static
+ * @param   {string}  configFileName Pagean configuration file name.
+ * @returns {boolean}                True if file has valid Pagean config schema.
+ */
 const lintConfigFile = (configFileName) => {
     const config = getConfigFromFile(configFileName);
     return validateConfigSchema(config);

package/lib/externalFileUtils.js

@@ -1,5 +1,10 @@
 'use strict';
 
+/**
+ * Utilities for checking external JavaScript files.
+ *
+ * @module external-file-utils
+ */
 const fs = require('fs');
 const path = require('path');
 
@@ -7,12 +12,29 @@ const axios = require('axios');
 
 const externalFilePath = 'pagean-external-scripts';
 
+/**
+ * Checks if the JavaScript is external to the page and should be saved.
+ *
+ * @static
+ * @param   {string}  script The URL of the JavaScript file.
+ * @param   {string}  page   The URL of the current page.
+ * @returns {boolean}        True if the script is external to the page.
+ */
 const shouldSaveFile = (script, page) => {
     const scriptUrl = new URL(script);
     const pageUrl = new URL(page);
     return scriptUrl.host !== pageUrl.host;
 };
 
+/**
+ * Loads the JavaScript file from the specified URL and
+ * saves it to disc.
+ *
+ * @static
+ * @param   {string} script The URL of the JavaScript file.
+ * @returns {object}        An object with original script
+ *                          URL and local file name.
+ */
 const saveExternalScript = async (script) => {
     const result = { url: script };
     try {

package/lib/linkUtils.js

@@ -1,6 +1,8 @@
 'use strict';
 
 /**
+ * Utilities for checking page links.
+ *
  * @module linkUtils
  */
 
@@ -12,7 +14,7 @@ const msPerSec = 1000;
 const timeoutSeconds = 120;
 
 /**
- * Enum for HTTP responses
+ * Enum for HTTP responses.
  *
  * @public
  * @readonly
@@ -29,6 +31,7 @@ const httpResponse = Object.freeze({
 
 const noRetryResponses = [httpResponse.tooManyRequests];
 
+// eslint-disable-next-line jsdoc/require-description-complete-sentence
 /**
  * Normalizes a URL with https://www.npmjs.com/package/normalize-url
  * using defaults plus the following overrides:
@@ -38,8 +41,9 @@ const noRetryResponses = [httpResponse.tooManyRequests];
  *  4. Do not strip "www." from the URL
  *
  * @public
- * @param {string} url  The URL to normalize
- * @returns {string}    The normalized URL
+ * @static
+ * @param {string} url  The URL to normalize.
+ * @returns {string}    The normalized URL.
  */
 const normalizeLink = url => normalizeUrl(url,
     {
@@ -51,13 +55,14 @@ const normalizeLink = url => normalizeUrl(url,
 
 
 /**
- * Checks settings to determine if the provided link should be ignored
+ * Checks settings to determine if the provided link should be ignored.
  *
  * @private
- * @param {Object} settings     Test settings object, which may contain an
- *                              ignoredLinks array
- * @param {string} link         The link to check against the ignore list
- * @returns {boolean}           True if the link should be ignored, otherwise false
+ * @static
+ * @param   {object} settings Test settings object, which may contain an
+ *                            ignoredLinks array.
+ * @param   {string} link     The link to check against the ignore list.
+ * @returns {boolean}         True if the link should be ignored, otherwise false.
  */
 const ignoreLink = (settings, link) => settings.ignoredLinks && settings.ignoredLinks.includes(link);
 
@@ -67,8 +72,9 @@ const ignoreLink = (settings, link) => settings.ignoredLinks && settings.ignored
  * to identify any failed responses.
  *
  * @public
- * @param {(string|number)} response    The response to an HTTP request to check for failure.
- * @returns {boolean}                   True if failed, otherwise false
+ * @static
+ * @param   {(string|number)} response The response to an HTTP request to check for failure.
+ * @returns {boolean}                  True if failed, otherwise false.
  */
 const isFailedResponse = response => isNaN(response.status) || response.status >= httpResponse.badRequest;
 
@@ -77,9 +83,10 @@ const isFailedResponse = response => isNaN(response.status) || response.status >
  * Checks a Puppeteer page for the element specified in the hash of the provided link.
  *
  * @private
- * @param {Object} page         A Puppeteer page object
- * @param {string} link         The link to check
- * @returns {(string|number)}   The link status (HTTP response code or error)
+ * @static
+ * @param   {object}          page A Puppeteer page object.
+ * @param   {string}          link The link to check.
+ * @returns {(string|number)}      The link status (HTTP response code or error).
  */
 const checkSamePageLink = async (page, link) => {
     const selector = link.slice(page.url().length);
@@ -96,9 +103,10 @@ const checkSamePageLink = async (page, link) => {
  * Checks the provided link for validity by loading in a Puppeteer page.
  *
  * @private
- * @param {Object} page         A Puppeteer page object
- * @param {string} link         The link to check
- * @returns {(string|number)}   The link status (HTTP response code or error)
+ * @static
+ * @param   {object}          page A Puppeteer page object.
+ * @param   {string}          link The link to check.
+ * @returns {(string|number)}      The link status (HTTP response code or error).
  */
 const checkExternalPageLinkBrowser = async (page, link) => {
     let status;
@@ -122,10 +130,11 @@ const checkExternalPageLinkBrowser = async (page, link) => {
  * a HEAD request is made for efficiency. If useGet is true, a full GET request is made.
  *
  * @private
- * @param {Object} page             A Puppeteer page object
- * @param {string} link             The link to check
- * @param {boolean} [useGet=false]  Used to identify the request method to use (HEAD or GET)
- * @returns {(string|number)}       The link status (HTTP response code or error)
+ * @static
+ * @param   {object}          page     A Puppeteer page object.
+ * @param   {string}          link     The link to check.
+ * @param   {boolean}         [useGet] Used to identify the request method to use (HEAD or GET).
+ * @returns {(string|number)}          The link status (HTTP response code or error).
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity -- Allow less than 10
 const checkExternalPageLink = async (page, link, useGet = false) => {
@@ -164,7 +173,8 @@ const checkExternalPageLink = async (page, link, useGet = false) => {
  * function that caches checked link results.
  *
  * @public
- * @returns {Object}
+ * @static
+ * @returns {object} Link checker object.
  */
 // eslint-disable-next-line max-lines-per-function
 const createLinkChecker = () => {
@@ -176,11 +186,12 @@ const createLinkChecker = () => {
          * reference to the Puppeteer page and applicable settings.
          *
          * @public
-         * @param {Object} context      A Pagean test context object
-         * @param {string} link         The link to check
-         * @returns {(string|number)}   The link status (HTTP response code or error)
+         * @instance
+         * @param   {object}          context A Pagean test context object.
+         * @param   {string}          link    The link to check.
+         * @returns {(string|number)}         The link status (HTTP response code or error).
          */
-        // eslint-disable-next-line sonarjs/cognitive-complexity, max-lines-per-function
+        // eslint-disable-next-line sonarjs/cognitive-complexity
         checkLink: async (context, link) => {
             let status = httpResponse.unknownError;
             try {

package/lib/logger.js

@@ -1,5 +1,11 @@
 'use strict';
 
+/**
+ * Creates an instance of a logger object to manage logging functions.
+ *
+ * @module logger
+ */
+
 const consoleLogger = require('ci-logger');
 const { reporterTypes } = require('../lib/reporter');
 
@@ -11,6 +17,14 @@ const testResultSymbols = Object.freeze({
 
 const nullFunction = () => { };
 
+/**
+ * Factory function that creates an instance of a
+ * logger object to manage logging functions.
+ *
+ * @static
+ * @param   {object} config Pagean configuration.
+ * @returns {object}        A logger object.
+ */
 // eslint-disable-next-line max-lines-per-function
 module.exports = (config) => {
     const cliReporter = {
@@ -34,6 +48,13 @@ module.exports = (config) => {
     };
 
     let currentUrlTests;
+    /**
+     * Indicates the start of testing the specified URL. Subsequent
+     * calls to logTestResults will be logged with this URL.
+     *
+     * @instance
+     * @param {string} url The URL being tested.
+     */
     const startUrlTests = (url) => {
         const urlTestResults = {
             url,
@@ -44,6 +65,13 @@ module.exports = (config) => {
         cliReporter.log({ message: `\nTesting URL: ${url}` });
     };
 
+    /**
+     * Logs test results for the current URL (indicated
+     * by the last call to StartUrlTests).
+     *
+     * @instance
+     * @param {object} testResult The test results.
+     */
     const logTestResults = (testResult) => {
         if (testResult) {
             currentUrlTests.tests.push(testResult);
@@ -62,6 +90,13 @@ module.exports = (config) => {
         cliReporter.logAlways({ message: `\n Tests: ${testResults.summary.tests}\n Passed: ${testResults.summary.passed}\n Warning: ${testResults.summary.warning}\n Failed: ${testResults.summary.failed}\n` });
     };
 
+    /**
+     * Outputs the test results summary to stdout and returns
+     * the consolidated results for all tests.
+     *
+     * @instance
+     * @returns {object} The consolidated results for all tests.
+     */
     const getTestResults = () => {
         outputTestSummary();
         return testResults;

package/lib/reporter.js

@@ -1,5 +1,10 @@
 'use strict';
 
+/**
+ * Manages Pagean reporting.
+ *
+ * @module reporter
+ */
 const fs = require('fs');
 const path = require('path');
 const handlebars = require('handlebars');
@@ -31,6 +36,13 @@ const reporterTypes = Object.freeze({
     json: 'json'
 });
 
+/**
+ * Outputs the given results with specified reporters.
+ *
+ * @static
+ * @param {object}   results   Consolidated Pagean results for a all tests.
+ * @param {string[]} reporters The configured reporters.
+ */
 const saveReports = (results, reporters) => {
     if (reporters.includes(reporterTypes.json)) {
         saveJsonReport(results);

package/lib/schemaErrors.js

@@ -1,5 +1,10 @@
 'use strict';
 
+/**
+ * Generates formatted Pagean config schema errors for output to stdout.
+ *
+ * @module schema-errors
+ */
 const { red } = require('kleur');
 
 const getDataKey = (instancePath) => {
@@ -28,6 +33,14 @@ const processErrorParams = (error) => {
     return formattedMessage;
 };
 
+/**
+ * Generates formatted schema strings for output to stdout for all
+ * schema errors.
+ *
+ * @static
+ * @param   {object[]} errors Array of Pagean config schema errors.
+ * @returns {string[]}        Array of formatted schema error strings.
+ */
 const formatErrors = (errors) => {
     const margin = 2;
     let maxLength = 0;

package/lib/testUtils.js

@@ -1,5 +1,11 @@
 'use strict';
 
+/**
+ * Miscellaneous test utilities.
+ *
+ * @module test-utils
+ */
+
 const testResultStates = Object.freeze({
     passed: 'passed',
     warning: 'warning',
@@ -13,8 +19,19 @@ const getTestSettings = (testSettingProperty, urlSettings) => {
     return urlSettings[testSettingProperty];
 };
 
-// Allow cognitive complexity les than 10
-// eslint-disable-next-line sonarjs/cognitive-complexity
+/**
+ * Wrapper function for executing all Pagean tests that manages getting
+ * test-specific settings from configuration, passing the test context,
+ * and logging results.
+ *
+ * @static
+ * @param {string}   name                The name of the test.
+ * @param {Function} testFunction        The test function to be executed.
+ * @param {object}   testContext         The test execution context.
+ * @param {string}   testSettingProperty The name of the config property
+ *                                       with settings for the current test.
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Allow < 10
 const pageanTest = async (name, testFunction, testContext, testSettingProperty) => {
     const testSettings = getTestSettings(testSettingProperty, testContext.urlSettings);
     testContext.testSettings = testSettings;

package/lib/tests.js

@@ -1,5 +1,10 @@
 'use strict';
 
+/**
+ * Pagean tests.
+ *
+ * @module tests
+ */
 const { HTMLHint } = require('htmlhint');
 
 const { testResultStates, pageanTest } = require('./testUtils');
@@ -8,6 +13,12 @@ const { isFailedResponse } = require('./linkUtils');
 
 const msPerSec = 1000;
 
+/**
+ * Tests the current page for the existence of a horizontal scroll bar.
+ *
+ * @static
+ * @param {object} context Test execution context.
+ */
 const horizontalScrollbarTest = async (context) => {
     // eslint-disable-next-line no-shadow -- less intuitive
     await pageanTest('should not have a horizontal scrollbar', async (context) => {
@@ -20,6 +31,12 @@ const horizontalScrollbarTest = async (context) => {
     }, context, 'horizontalScrollbarTest');
 };
 
+/**
+ * Tests the current page for any console output.
+ *
+ * @static
+ * @param {object} context Test execution context.
+ */
 const consoleOutputTest = (context) => {
     // eslint-disable-next-line no-shadow -- less intuitive
     pageanTest('should not have console output', (context) => {
@@ -31,6 +48,12 @@ const consoleOutputTest = (context) => {
     }, context, 'consoleOutputTest');
 };
 
+/**
+ * Tests the current page for any console errors.
+ *
+ * @static
+ * @param {object} context Test execution context.
+ */
 const consoleErrorTest = (context) => {
     // eslint-disable-next-line no-shadow -- less intuitive
     pageanTest('should not have console errors', (context) => {
@@ -45,6 +68,12 @@ const consoleErrorTest = (context) => {
     }, context, 'consoleErrorTest');
 };
 
+/**
+ * Tests the current page for any HTML lint issues.
+ *
+ * @static
+ * @param {object} context Test execution context.
+ */
 const renderedHtmlTest = async (context) => {
     // eslint-disable-next-line no-shadow -- less intuitive
     await pageanTest('should have valid rendered HTML', async (context) => {
@@ -58,6 +87,12 @@ const renderedHtmlTest = async (context) => {
     }, context, 'renderedHtmlTest');
 };
 
+/**
+ * Tests the current page for load time.
+ *
+ * @static
+ * @param {object} context Test execution context.
+ */
 const pageLoadTimeTest = async (context) => {
     const testSettingName = 'pageLoadTimeTest';
     // eslint-disable-next-line no-shadow -- less intuitive
@@ -77,6 +112,13 @@ const pageLoadTimeTest = async (context) => {
     }, context, testSettingName);
 };
 
+/**
+ * Tests the current page for any external JavaScript files and
+ * downloads the files for further analysis.
+ *
+ * @static
+ * @param {object} context Test execution context.
+ */
 const externalScriptTest = async (context) => {
     // eslint-disable-next-line no-shadow -- less intuitive
     await pageanTest('should not have external scripts', async (context) => {
@@ -96,6 +138,12 @@ const externalScriptTest = async (context) => {
     }, context, 'externalScriptTest');
 };
 
+/**
+ * Tests the current page for any broken links (external or within the page).
+ *
+ * @static
+ * @param {object} context Test execution context.
+ */
 const brokenLinkTest = async (context) => {
     // eslint-disable-next-line no-shadow -- less intuitive
     await pageanTest('should not have broken links', async (context) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagean",
-  "version": "6.0.3",
+  "version": "6.0.7",
   "description": "Pagean is a web page analysis tool designed to automate tests requiring web pages to be loaded in a browser window (e.g. horizontal scrollbar, console errors)",
   "bin": {
     "pagean": "./bin/pagean.js",
@@ -48,27 +48,27 @@
   },
   "homepage": "https://gitlab.com/gitlab-ci-utils/pagean#readme",
   "devDependencies": {
-    "@aarongoldenthal/eslint-config-standard": "^10.0.1",
-    "@aarongoldenthal/stylelint-config-standard": "^5.0.0",
+    "@aarongoldenthal/eslint-config-standard": "^11.0.0",
+    "@aarongoldenthal/stylelint-config-standard": "^7.0.0",
     "bin-tester": "^2.0.1",
-    "eslint": "^8.2.0",
-    "jest": "^27.3.1",
+    "eslint": "^8.8.0",
+    "jest": "^27.5.1",
     "jest-junit": "^13.0.0",
-    "markdownlint-cli": "^0.29.0",
+    "markdownlint-cli": "^0.31.1",
     "strip-ansi": "^6.0.1",
-    "stylelint": "^14.1.0"
+    "stylelint": "^14.5.0"
   },
   "dependencies": {
-    "ajv": "^8.8.1",
+    "ajv": "^8.10.0",
     "ajv-errors": "^3.0.0",
-    "axios": "^0.24.0",
+    "axios": "^0.25.0",
     "ci-logger": "^4.0.1",
-    "commander": "^8.3.0",
+    "commander": "^9.0.0",
     "handlebars": "^4.7.7",
-    "htmlhint": "^0.16.1",
+    "htmlhint": "^1.1.2",
     "kleur": "^4.1.4",
     "normalize-url": "^6.1.0",
     "protocolify": "^3.0.0",
-    "puppeteer": "^11.0.0"
+    "puppeteer": "^13.3.1"
   }
 }