pagean 7.0.0 → 8.0.0

package/README.md

@@ -282,8 +282,10 @@ pagean:
   stage: test
   before_script:
     # Start static server in test cases directory, discarding any console output,
-    # and wait until the server is running
-    - http-server ./tests/test-cases > /dev/null 2>&1 & wait-on http://localhost:8080
+    # and wait until the server is running. Have wait-on check by IP based on DNS
+    # change in Node 17 and issues with it resolving `localhost`. Pagean is able
+    # to resolve localhost with no issue, see example in static-server.pageanrc.json.
+    - http-server ./tests/test-cases > /dev/null 2>&1 & wait-on http://127.0.0.1:8080
   script:
     - pagean -c static-server.pageanrc.json
   artifacts:

package/index.js

@@ -15,8 +15,8 @@ const { createLinkChecker } = require('./lib/link-utils');
 /**
  * Executes Pagean tests as specified in config and reports results.
  *
- * @static
  * @param {object} config The Pagean test configuration.
+ * @static
  */
 // eslint-disable-next-line max-lines-per-function
 const executeAllTests = async (config) => {

package/lib/config.js

@@ -51,8 +51,8 @@ const consolidateTestSettings = (
     globalSettings,
     urlSettings
 ) => {
-    const sanitizedGlobalSettings = globalSettings ? globalSettings : {};
-    const sanitizedUrlSettings = urlSettings ? urlSettings : {};
+    const sanitizedGlobalSettings = globalSettings || {};
+    const sanitizedUrlSettings = urlSettings || {};
     const processedSettings = {};
     for (const key of Object.keys(defaultSettings)) {
         processedSettings[key] = {
@@ -114,9 +114,10 @@ const getConfigFromFile = (configFileName) => {
  * Loads config from file and returns consolidated config with
  * defaults where values are not specified.
  *
+ * @param   {string}    configFileName Pagean configuration file name.
+ * @returns {object}                   Consolidated Pagean configuration.
+ * @throws  {TypeError}                Throws if config file has an invalid schema.
  * @static
- * @param   {string} configFileName Pagean configuration file name.
- * @returns {object}                Consolidated Pagean configuration.
  */
 const processConfig = (configFileName) => {
     const config = getConfigFromFile(configFileName);
@@ -133,16 +134,16 @@ const processConfig = (configFileName) => {
         htmlHintConfig: getHtmlHintConfig(
             config.htmlhintrc || defaultHtmlHintConfigFilename
         ),
-        reporters: config.reporters ? config.reporters : defaultConfig.reporters
+        reporters: config.reporters || defaultConfig.reporters
     };
 };
 
 /**
  * Lints the configuration file schema.
  *
- * @static
  * @param   {string}  configFileName Pagean configuration file name.
  * @returns {boolean}                True if file has valid Pagean config schema.
+ * @static
  */
 const lintConfigFile = (configFileName) => {
     const config = getConfigFromFile(configFileName);

package/lib/external-file-utils.js

@@ -15,10 +15,10 @@ 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.
+ * @static
  */
 const shouldSaveFile = (script, page) => {
     const scriptUrl = new URL(script);
@@ -30,10 +30,10 @@ const shouldSaveFile = (script, page) => {
  * 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.
+ * @static
  */
 const saveExternalScript = async (script) => {
     const result = { url: script };

package/lib/link-utils.js

@@ -16,9 +16,9 @@ const timeoutSeconds = 120;
 /**
  * Enum for HTTP responses.
  *
- * @public
  * @readonly
  * @enum {number}
+ * @public
  */
 const httpResponse = Object.freeze({
     continue: 100,
@@ -31,19 +31,18 @@ const httpResponse = Object.freeze({
 
 const noRetryResponses = new Set([httpResponse.tooManyRequests]);
 
-/* eslint-disable jsdoc/require-description-complete-sentence */
 /**
  * Normalizes a URL (with https://www.npmjs.com/package/normalize-url).
  * Uses defaults plus the following overrides.
- *  1. Set default protocol to https if protocol-relative
- *  2. Do not remove any querystring parameters
- *  3. Strip hash from URL
- *  4. Do not strip "www." from the URL
+ * 1. Set default protocol to https if protocol-relative.
+ * 2. Do not remove any querystring parameters.
+ * 3. Strip hash from URL.
+ * 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.
+ * @public
  */
 const normalizeLink = (url) =>
     normalizeUrl(url, {
@@ -57,12 +56,12 @@ const normalizeLink = (url) =>
 /**
  * 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.
+ * @private
  */
 const ignoreLink = (settings, link) =>
     settings.ignoredLinks && settings.ignoredLinks.includes(link);
@@ -71,10 +70,10 @@ const ignoreLink = (settings, link) =>
  * Checks a response to an HTTP request, either a response code or explicit error,
  * to identify any failed responses.
  *
- * @public
- * @static
  * @param   {(string|number)} response The response to an HTTP request to check for failure.
  * @returns {boolean}                  True if failed, otherwise false.
+ * @static
+ * @public
  */
 const isFailedResponse = (response) =>
     Number.isNaN(Number(response.status)) ||
@@ -83,11 +82,11 @@ const isFailedResponse = (response) =>
 /**
  * Checks a Puppeteer page for the element specified in the hash of the provided link.
  *
- * @private
- * @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).
+ * @static
+ * @private
  */
 const checkSamePageLink = async (page, link) => {
     const selector = link.slice(page.url().length);
@@ -102,11 +101,11 @@ const checkSamePageLink = async (page, link) => {
 /**
  * Checks the provided link for validity by loading in a Puppeteer page.
  *
- * @private
- * @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).
+ * @static
+ * @private
  */
 const checkExternalPageLinkBrowser = async (page, link) => {
     let status;
@@ -127,12 +126,12 @@ const checkExternalPageLinkBrowser = async (page, link) => {
  * Checks the provided link for validity by requesting with axios. If useGet if false,
  * a HEAD request is made for efficiency. If useGet is true, a full GET request is made.
  *
- * @private
- * @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).
+ * @static
+ * @private
  */
 // eslint-disable-next-line sonarjs/cognitive-complexity -- Allow less than 10
 const checkExternalPageLink = async (page, link, useGet = false) => {
@@ -175,9 +174,9 @@ const checkExternalPageLink = async (page, link, useGet = false) => {
  * Factory function returning a linkChecker object with a {@link checkLink}
  * function that caches checked link results.
  *
- * @public
- * @static
  * @returns {object} Link checker object.
+ * @static
+ * @public
  */
 const createLinkChecker = () => {
     const checkedLinks = new Map();
@@ -187,11 +186,11 @@ const createLinkChecker = () => {
          * Checks the provided link for validity using context object for a
          * reference to the Puppeteer page and applicable settings.
          *
-         * @public
          * @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).
+         * @public
          */
         // eslint-disable-next-line sonarjs/cognitive-complexity
         checkLink: async (context, link) => {

package/lib/logger.js

@@ -21,9 +21,9 @@ 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.
+ * @static
  */
 // eslint-disable-next-line max-lines-per-function
 module.exports = (config) => {

package/lib/report-template.handlebars

@@ -13,9 +13,9 @@
 			color: #333333;
 			font-family: Arial, Helvetica, sans-serif;
 			font-size: 0.85rem;
-			padding: 1rem;
 			margin: auto;
 			max-width: 1000px;
+			padding: 1rem;
 		}
 
 		ul {
@@ -31,9 +31,9 @@
 		}
 
 		h1 {
+			margin: 1rem 0 0.75rem;
 			margin-block: 0;
 			margin-inline: 0;
-			margin: 1rem 0 0.75rem;
 		}
 
 		h2 {

package/lib/reporter.js

@@ -41,9 +41,9 @@ const reporterTypes = Object.freeze({
 /**
  * Outputs the given results with specified reporters.
  *
- * @static
  * @param {object}   results   Consolidated Pagean results for a all tests.
  * @param {string[]} reporters The configured reporters.
+ * @static
  */
 const saveReports = (results, reporters) => {
     if (reporters.includes(reporterTypes.json)) {

package/lib/schema-errors.js

@@ -48,9 +48,9 @@ const processErrorParameters = (error) => {
  * 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.
+ * @static
  */
 const formatErrors = (errors) => {
     const margin = 2;

package/lib/test-utils.js

@@ -26,12 +26,12 @@ const getTestSettings = (testSettingProperty, urlSettings) => {
  * 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.
+ * @static
  */
 const pageanTest = async (
     name,

package/lib/tests.js

@@ -16,8 +16,8 @@ const msPerSec = 1000;
 /**
  * Tests the current page for the existence of a horizontal scroll bar.
  *
- * @static
  * @param {object} context Test execution context.
+ * @static
  */
 const horizontalScrollbarTest = async (context) => {
     await pageanTest(
@@ -44,8 +44,8 @@ const horizontalScrollbarTest = async (context) => {
 /**
  * Tests the current page for any console output.
  *
- * @static
  * @param {object} context Test execution context.
+ * @static
  */
 const consoleOutputTest = (context) => {
     pageanTest(
@@ -71,8 +71,8 @@ const consoleOutputTest = (context) => {
 /**
  * Tests the current page for any console errors.
  *
- * @static
  * @param {object} context Test execution context.
+ * @static
  */
 const consoleErrorTest = (context) => {
     pageanTest(
@@ -101,8 +101,8 @@ const consoleErrorTest = (context) => {
 /**
  * Tests the current page for any HTML lint issues.
  *
- * @static
  * @param {object} context Test execution context.
+ * @static
  */
 const renderedHtmlTest = async (context) => {
     await pageanTest(
@@ -133,8 +133,8 @@ const renderedHtmlTest = async (context) => {
 /**
  * Tests the current page for load time.
  *
- * @static
  * @param {object} context Test execution context.
+ * @static
  */
 // eslint-disable-next-line max-lines-per-function
 const pageLoadTimeTest = async (context) => {
@@ -176,8 +176,8 @@ const pageLoadTimeTest = async (context) => {
  * Tests the current page for any external JavaScript files and
  * downloads the files for further analysis.
  *
- * @static
  * @param {object} context Test execution context.
+ * @static
  */
 // eslint-disable-next-line max-lines-per-function
 const externalScriptTest = async (context) => {
@@ -220,8 +220,8 @@ const externalScriptTest = async (context) => {
 /**
  * Tests the current page for any broken links (external or within the page).
  *
- * @static
  * @param {object} context Test execution context.
+ * @static
  */
 // eslint-disable-next-line max-lines-per-function
 const brokenLinkTest = async (context) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagean",
-  "version": "7.0.0",
+  "version": "8.0.0",
   "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",
@@ -51,28 +51,28 @@
   },
   "homepage": "https://gitlab.com/gitlab-ci-utils/pagean",
   "devDependencies": {
-    "@aarongoldenthal/eslint-config-standard": "^15.0.0",
-    "@aarongoldenthal/stylelint-config-standard": "^9.0.0",
-    "bin-tester": "^2.0.1",
-    "eslint": "^8.17.0",
-    "jest": "^28.1.1",
-    "jest-junit": "^13.2.0",
-    "markdownlint-cli": "^0.31.1",
-    "prettier": "^2.7.0",
+    "@aarongoldenthal/eslint-config-standard": "^17.0.1",
+    "@aarongoldenthal/stylelint-config-standard": "^11.2.1",
+    "bin-tester": "^3.0.0",
+    "eslint": "^8.26.0",
+    "jest": "^29.2.2",
+    "jest-junit": "^14.0.1",
+    "markdownlint-cli": "^0.32.2",
+    "prettier": "^2.7.1",
     "strip-ansi": "^6.0.1",
-    "stylelint": "^14.9.1"
+    "stylelint": "^14.14.0"
   },
   "dependencies": {
     "ajv": "^8.11.0",
     "ajv-errors": "^3.0.0",
-    "axios": "^0.27.2",
-    "ci-logger": "^5.0.0",
-    "commander": "^9.3.0",
+    "axios": "^1.1.3",
+    "ci-logger": "^5.1.0",
+    "commander": "^9.4.1",
     "handlebars": "^4.7.7",
     "htmlhint": "^1.1.4",
-    "kleur": "^4.1.4",
+    "kleur": "^4.1.5",
     "normalize-url": "^6.1.0",
     "protocolify": "^3.0.0",
-    "puppeteer": "^14.4.0"
+    "puppeteer": "^19.2.0"
   }
 }