pagean 10.2.0 → 11.0.0

package/lib/config.js

@@ -1,22 +1,23 @@
-'use strict';
-
 /**
  * Functions for managing Pagean config files.
  *
  * @module config
  */
 
-const fs = require('node:fs');
-const path = require('node:path');
-const Ajv = require('ajv/dist/2019');
-const draft7MetaSchema = require('ajv/dist/refs/json-schema-draft-07.json');
-const ajvErrors = require('ajv-errors');
-const protocolify = require('protocolify');
+import fs from 'node:fs';
+import path from 'node:path';
+
+import Ajv from 'ajv/dist/2019.js';
+import ajvErrors from 'ajv-errors';
+import protocolify from 'protocolify';
 
-const { normalizeLink } = require('./link-utils');
-const { getUrlsFromSitemap } = require('./sitemap');
+import { __dirname, readJson } from './utils.js';
+import { getUrlsFromSitemap } from './sitemap.js';
+import { normalizeLink } from './link-utils.js';
 
-const defaultConfig = require('./default-config.json');
+const defaultConfig = await readJson(
+    path.join(__dirname, 'default-config.json')
+);
 const defaultHtmlHintConfigFilename = './.htmlhintrc';
 
 const getUrl = (testUrl) => {
@@ -125,14 +126,13 @@ const validateConfigSchema = (config) => {
         // All values hardcoded.
         // nosemgrep: eslint.detect-non-literal-fs-filename
         fs.readFileSync(
-            path.join(__dirname, '../', 'schemas', 'pageanrc.schema.json')
+            path.join(__dirname, '..', 'schemas', 'pageanrc.schema.json')
         )
     );
     // Allow allErrors to lint the entire config file, although users could
     // ReDoS themselves.
     // nosemgrep: ajv-allerrors-true
     const ajv = new Ajv({ allErrors: true });
-    ajv.addMetaSchema(draft7MetaSchema);
     ajvErrors(ajv);
     const validate = ajv.compile(schema);
     const isValid = validate(config);
@@ -144,14 +144,24 @@ const getConfigFromFile = (configFileName) =>
     // nosemgrep: eslint.detect-non-literal-fs-filename
     JSON.parse(fs.readFileSync(configFileName, 'utf8'));
 
+/** @typedef {import('puppeteer').LaunchOptions} LaunchOptions */
+
+/**
+ * @typedef  {object}        PageanConfig
+ * @property {object}        htmlHintConfig         The htmlhint configuration.
+ * @property {string}        project                The name of the project.
+ * @property {LaunchOptions} puppeteerLaunchOptions Options for launching Puppeteer.
+ * @property {string[]}      reporters              The reporters used to output results.
+ * @property {object}        urls                   The URLs to analyze with specific settings.
+ */
+
 /**
  * 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.
- * @async
- * @throws  {TypeError}                Throws if config file has an invalid schema.
+ * @param   {string}                configFileName Pagean configuration file name.
+ * @returns {Promise<PageanConfig>}                Consolidated Pagean configuration.
+ * @throws  {TypeError}                            Throws if config file has an invalid schema.
  * @static
  * @public
  */
@@ -189,5 +199,5 @@ const lintConfigFile = (configFileName) => {
     return validateConfigSchema(config);
 };
 
-module.exports = processConfig;
-module.exports.lintConfigFile = lintConfigFile;
+export default processConfig;
+export { lintConfigFile };

package/lib/default-config.json

@@ -1,6 +1,16 @@
 {
+  "puppeteerLaunchOptions": {
+    "headless": "new"
+  },
+  "reporters": ["cli", "html", "json"],
   "settings": {
-    "horizontalScrollbarTest": {
+    "brokenLinkTest": {
+      "enabled": true,
+      "failWarn": false,
+      "checkWithBrowser": false,
+      "ignoreDuplicates": true
+    },
+    "consoleErrorTest": {
       "enabled": true,
       "failWarn": false
     },
@@ -8,11 +18,11 @@
       "enabled": true,
       "failWarn": false
     },
-    "consoleErrorTest": {
+    "externalScriptTest": {
       "enabled": true,
-      "failWarn": false
+      "failWarn": true
     },
-    "renderedHtmlTest": {
+    "horizontalScrollbarTest": {
       "enabled": true,
       "failWarn": false
     },
@@ -21,20 +31,10 @@
       "failWarn": false,
       "pageLoadTimeThreshold": 2
     },
-    "externalScriptTest": {
-      "enabled": true,
-      "failWarn": true
-    },
-    "brokenLinkTest": {
+    "renderedHtmlTest": {
       "enabled": true,
-      "failWarn": false,
-      "checkWithBrowser": false,
-      "ignoreDuplicates": true
+      "failWarn": false
     }
   },
-  "puppeteerLaunchOptions": {
-    "headless": "new"
-  },
-  "reporters": ["cli", "html", "json"],
   "urls": ["ignored, required to validate schema"]
 }

package/lib/external-file-utils.js

@@ -1,14 +1,13 @@
-'use strict';
-
 /**
  * Utilities for checking external JavaScript files.
  *
  * @module external-file-utils
  */
-const fs = require('node:fs');
-const path = require('node:path');
 
-const axios = require('axios');
+import fs from 'node:fs';
+import path from 'node:path';
+
+import axios from 'axios';
 
 const externalFilePath = 'pagean-external-scripts';
 
@@ -30,13 +29,21 @@ const shouldSaveFile = (script, page) => {
     );
 };
 
+/**
+ * @typedef  {object} ExternalScript
+ * @property {string} url            The original script url.
+ * @property {string} [localFile]    The path to the downloaded file.
+ * @property {string} [message]      The error message if the script
+ *                                   failed to download.
+ */
+
 /**
  * Loads the JavaScript file from the specified URL and
  * saves it to disc.
  *
- * @param   {string} script The URL of the JavaScript file.
- * @returns {object}        An object with original script
- *                          URL and local file name.
+ * @param   {string}                  script The URL of the JavaScript file.
+ * @returns {Promise<ExternalScript>}        An object with original script
+ *                                           URL and local file name.
  * @static
  */
 const saveExternalScript = async (script) => {
@@ -67,5 +74,4 @@ const saveExternalScript = async (script) => {
     return result;
 };
 
-module.exports.saveExternalScript = saveExternalScript;
-module.exports.shouldSaveFile = shouldSaveFile;
+export { saveExternalScript, shouldSaveFile };

package/lib/link-utils.js

@@ -1,15 +1,14 @@
-'use strict';
-
 /**
  * Utilities for checking page links.
  *
  * @module link-utils
  */
 
-const https = require('node:https');
-const axios = require('axios');
-const normalizeUrl = require('normalize-url');
-const cssesc = require('cssesc');
+import https from 'node:https';
+
+import axios from 'axios';
+import cssesc from 'cssesc';
+import normalizeUrl from 'normalize-url';
 
 const msPerSec = 1000;
 const timeoutSeconds = 120;
@@ -80,12 +79,14 @@ const isFailedResponse = (response) =>
     Number.isNaN(Number(response.status)) ||
     response.status >= httpResponse.badRequest;
 
+/** @typedef {import('puppeteer').Page} Page */
+
 /**
  * Checks a Puppeteer page for the element specified in the hash of the provided link.
  *
- * @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).
+ * @param   {Page}                     page A Puppeteer page object.
+ * @param   {string}                   link The link to check.
+ * @returns {Promise<(string|number)>}      The link status (HTTP response code or error).
  * @static
  * @private
  */
@@ -105,9 +106,9 @@ const checkSamePageLink = async (page, link) => {
 /**
  * Checks the provided link for validity by loading in a Puppeteer page.
  *
- * @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).
+ * @param   {Page}                     page A Puppeteer page object.
+ * @param   {string}                   link The link to check.
+ * @returns {Promise<(string|number)>}      The link status (HTTP response code or error).
  * @static
  * @private
  */
@@ -130,10 +131,10 @@ 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.
  *
- * @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).
+ * @param   {Page}                     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 {Promise<(string|number)>}          The link status (HTTP response code or error).
  * @static
  * @private
  */
@@ -200,9 +201,9 @@ const createLinkChecker = () => {
          * reference to the Puppeteer page and applicable settings.
          *
          * @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).
+         * @param   {object}                   context A Pagean test context object.
+         * @param   {string}                   link    The link to check.
+         * @returns {Promise<(string|number)>}         The link status (HTTP response code or error).
          * @public
          */
         // eslint-disable-next-line sonarjs/cognitive-complexity -- allow < 10
@@ -240,7 +241,4 @@ const createLinkChecker = () => {
     };
 };
 
-module.exports.createLinkChecker = createLinkChecker;
-module.exports.httpResponse = httpResponse;
-module.exports.isFailedResponse = isFailedResponse;
-module.exports.normalizeLink = normalizeLink;
+export { createLinkChecker, httpResponse, isFailedResponse, normalizeLink };

package/lib/logger.js

@@ -1,32 +1,34 @@
-'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');
+import consoleLogger from 'ci-logger';
+
+import { reporterTypes } from '../lib/reporter.js';
 
 const testResultSymbols = Object.freeze({
     failed: ' ×',
+    pageError: ' ×',
     passed: ' √',
     warning: ' ‼'
 });
 
 const nullFunction = () => {};
 
+/** @typedef {import('./lib/config.js').PageanConfig} PageanConfig */
+
 /**
  * Factory function that creates an instance of a
  * logger object to manage logging functions.
  *
- * @param   {object} config Pagean configuration.
- * @returns {object}        A logger object.
+ * @param   {PageanConfig} config Pagean configuration.
+ * @returns {object}              A logger object.
  * @static
  */
 // eslint-disable-next-line max-lines-per-function -- factory function with state
-module.exports = (config) => {
+const factory = (config) => {
     const cliReporter = {
         // If cli reporter is enabled, set console log function, otherwise null function
         log: config.reporters.includes(reporterTypes.cli)
@@ -43,6 +45,7 @@ module.exports = (config) => {
         results: [],
         summary: {
             failed: 0,
+            pageError: 0,
             passed: 0,
             tests: 0,
             warning: 0
@@ -67,6 +70,23 @@ module.exports = (config) => {
         cliReporter.log({ message: `\nTesting URL: ${url}` });
     };
 
+    /**
+     * Logs an error navigating to the URL under test.
+     *
+     * @instance
+     * @param {string} message The page error message to log.
+     */
+    const logPageError = (message) => {
+        currentUrlTests.pageError = message;
+        testResults.summary.pageError++;
+
+        cliReporter.log({
+            isResult: true,
+            message: `Failed to navigate to URL: ${message}`,
+            resultPrefix: testResultSymbols.pageError
+        });
+    };
+
     /**
      * Logs test results for the current URL (indicated
      * by the last call to StartUrlTests).
@@ -90,7 +110,7 @@ module.exports = (config) => {
 
     const outputTestSummary = () => {
         cliReporter.logAlways({
-            message: `\n Tests: ${testResults.summary.tests}\n Passed: ${testResults.summary.passed}\n Warning: ${testResults.summary.warning}\n Failed: ${testResults.summary.failed}\n`
+            message: `\n Tests: ${testResults.summary.tests}\n Passed: ${testResults.summary.passed}\n Warning: ${testResults.summary.warning}\n Failed: ${testResults.summary.failed}\n Page Errors: ${testResults.summary.pageError}\n`
         });
     };
 
@@ -108,7 +128,10 @@ module.exports = (config) => {
 
     return {
         getTestResults,
+        logPageError,
         logTestResults,
         startUrlTests
     };
 };
+
+export default factory;

package/lib/report-template.handlebars

@@ -18,6 +18,8 @@
 			--color-text-failed: #ad000c;
 			--color-background-warning: #fdec96;
 			--color-text-warning: #7e6902;
+			--color-background-page-error: #f6d5c0;
+			--color-text-page-error: #994715;
 		}
 
 		html {
@@ -69,7 +71,7 @@
 			display: flex;
 			flex-direction: row;
 			margin-block-end: 2rem;
-			max-inline-size: 50%;
+			max-inline-size: 75%;
 		}
 
 		.summary {
@@ -109,6 +111,12 @@
 			color: var(--color-text-warning);
 		}
 
+		.page-error {
+			background-color: var(--color-background-page-error);
+			border: 1px solid var(--color-text-page-error);
+			color: var(--color-text-page-error);
+		}
+
 		.test-results h2 {
 			margin-block: 1rem 0;
 		}
@@ -207,11 +215,20 @@
 			<div class="summary passed">Passed: {{summary.passed}}</div>
 			<div class="summary warning">Warning: {{summary.warning}}</div>
 			<div class="summary failed">Failed: {{summary.failed}}</div>
+			<div class="summary page-error">Page Errors: {{summary.pageError}}</div>
 		</section>
 		<section class="test-results">
 			{{#results}}
 			<h2>URL: {{url}}</h2>
 			<ul class="tests">
+				{{#if pageError}}
+				<li class="test page-error">
+					<div class="header">
+						<div class="name">{{pageError}}</div>
+						<div class="result">page error</div>
+					</div>
+				</li>
+				{{/if}}
 				{{#tests}}
 				<li class="test {{result}}">
 					{{#if data}}

package/lib/reporter.js

@@ -1,13 +1,15 @@
-'use strict';
-
 /**
  * Manages Pagean reporting.
  *
  * @module reporter
  */
-const fs = require('node:fs');
-const path = require('node:path');
-const handlebars = require('handlebars');
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import handlebars from 'handlebars';
+
+import { __dirname } from './utils.js';
 
 const htmlReportTemplateName = 'report-template.handlebars';
 const htmlReportFileName = './pagean-results.html';
@@ -56,5 +58,4 @@ const saveReports = (results, reporters) => {
     }
 };
 
-module.exports.saveReports = saveReports;
-module.exports.reporterTypes = reporterTypes;
+export { saveReports, reporterTypes };

package/lib/schema-errors.js

@@ -1,11 +1,10 @@
-'use strict';
-
 /**
  * Generates formatted Pagean config schema errors for output to stdout.
  *
  * @module schema-errors
  */
-const { red } = require('kleur');
+
+import kleur from 'kleur';
 
 const getDataKey = (instancePath) => {
     const baseKey = '<pageanrc>';
@@ -65,10 +64,10 @@ const formatErrors = (errors) => {
     }
     return errors.map(
         (error) =>
-            `  ${error.dataKey.padEnd(maxLength + margin)}${red(
+            `  ${error.dataKey.padEnd(maxLength + margin)}${kleur.red(
                 error.formattedMessage
             )}`
     );
 };
 
-module.exports.formatErrors = formatErrors;
+export { formatErrors };

package/lib/sitemap.js

@@ -1,16 +1,20 @@
-'use strict';
+/**
+ * Process sitemap files.
+ *
+ * @module sitemap
+ */
+
+import fs from 'node:fs';
 
-const fs = require('node:fs');
-const axios = require('axios');
-const { parseStringPromise } = require('xml2js');
+import axios from 'axios';
+import { parseStringPromise } from 'xml2js';
 
 /**
  * Gets a sitemap, via file path or URL, and returns the string contents.
  *
- * @param   {string} url The URL or file path to the sitemap.
- * @returns {string}     The string contents of the sitemap.
- * @async
- * @throws  {Error}      Throws if the sitemap cannot be retrieved.
+ * @param   {string}          url The URL or file path to the sitemap.
+ * @returns {Promise<string>}     The string contents of the sitemap.
+ * @throws  {Error}               Throws if the sitemap cannot be retrieved.
  * @static
  * @private
  */
@@ -31,9 +35,8 @@ const getSitemap = async (url) => {
 /**
  * Parses a sitemap string and returns an array of URLs.
  *
- * @param   {string}   sitemapXml The string contents of the sitemap.
- * @returns {string[]}            The URLs from the sitemap.
- * @async
+ * @param   {string}            sitemapXml The string contents of the sitemap.
+ * @returns {Promise<string[]>}            The URLs from the sitemap.
  * @static
  * @private
  */
@@ -75,7 +78,6 @@ const removeExcludedUrls = (urls, exclude = []) => {
  * @param   {string}   [find]    The string to find in the URLs.
  * @param   {string}   [replace] The string to replace in the URLs.
  * @returns {string[]}           The processed URLs.
- * @async
  * @static
  * @private
  */
@@ -86,20 +88,23 @@ const replaceUrlStrings = (urls, find, replace) => {
     return urls.map((url) => url.replace(find, replace));
 };
 
+/**
+ * @typedef  {object}   SitemapOptions
+ * @property {string}   url            The URL or file path to the sitemap.
+ * @property {string}   [find]         The string to find in the URLs.
+ * @property {string}   [replace]      The string to replace in the URLs.
+ * @property {string[]} [exclude]      The URLs to exclude (regular expressions).
+ */
+
 /**
  * Retrieves a list of URLs from a sitemap, via a local file path or URL.
  * Options are available to exclude URLs from the results, and to find and
  * replace strings in the URLs (primarily intended for isolated testing,
  * for example change "https://somewhere.test/" to "http://localhost:3000/").
  *
- * @param   {object}   options           The sitemap processing options.
- * @param   {string}   options.url       The URL or file path to the sitemap.
- * @param   {string}   [options.find]    The string to find in the URLs.
- * @param   {string}   [options.replace] The string to replace in the URLs.
- * @param   {string[]} [options.exclude] The URLs to exclude (regular expressions).
- * @returns {string[]}                   The processed URLs from the sitemap.
- * @async
- * @throws  {Error}                      Throws if the sitemap cannot be processed.
+ * @param   {SitemapOptions}    options The sitemap processing options.
+ * @returns {Promise<string[]>}         The processed URLs from the sitemap.
+ * @throws  {Error}                     Throws if the sitemap cannot be processed.
  * @static
  * @public
  */
@@ -117,4 +122,4 @@ const getUrlsFromSitemap = async ({ url, find, replace, exclude } = {}) => {
     }
 };
 
-module.exports.getUrlsFromSitemap = getUrlsFromSitemap;
+export { getUrlsFromSitemap };

package/lib/test-utils.js

@@ -1,5 +1,3 @@
-'use strict';
-
 /**
  * Miscellaneous test utilities.
  *
@@ -26,11 +24,12 @@ const getTestSettings = (testSettingProperty, urlSettings) => {
  * test-specific settings from configuration, passing the test context,
  * and logging results.
  *
- * @param {string}   name                The name of the test being run.
- * @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.
+ * @param   {string}        name                The name of the test being run.
+ * @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.
+ * @returns {Promise<void>}
  * @static
  */
 const pageanTest = async (
@@ -65,5 +64,4 @@ const pageanTest = async (
     }
 };
 
-module.exports.testResultStates = testResultStates;
-module.exports.pageanTest = pageanTest;
+export { testResultStates, pageanTest };