pagean 8.0.3 → 9.0.0

package/README.md

@@ -133,7 +133,7 @@ For any failing test, the `data` array in the test report includes the original
     "status": 404
   },
   {
-    "href": "http://localhost:8080/brokenLinks.html#notlinked",
+    "href": "http://localhost:3000/brokenLinks.html#notlinked",
     "status": "#notlinked Not Found"
   },
   {
@@ -164,7 +164,7 @@ Complete reports for the example case in this project (the tests as specified in
 
 Pagean looks for a configuration file as specified via the CLI, or defaults to a file named `.pageanrc.json` in the project root. If the configuration file is not found, is not valid JSON, or does not contain any URLs to check the job will fail.
 
-Below is an example `.pageanrc.json` file, which is broken into six major properties:
+Below is an example `.pageanrc.json` file, which is broken into seven major properties:
 
 - `htmlhintrc`: An optional path to an htmlhintrc file to be used in the rendered HTML test
 - `project`: An optional name of the project, which is included in HTML and JSON reports.
@@ -197,6 +197,11 @@ is equivalent to the longhand:
 
 All available settings with the default values are shown below.
 
+- `sitemap`: Specify a sitemap with URLs to test. If a sitemap is specified, the URLs from the sitemap are added to the `urls` array. If a URL is in the `urls` array with `settings`, those settings are retained. Note that `<sitemapindex>` is currently not supported. The `sitemap` object can have the following properties:
+  - `url`: The URL of the sitemap (required if `sitemap` is included). This can be either an actual URL or a local file.
+  - `find`: A string to search for in sitemap URLs (e.g. `https://somehere.test`) (required if `replace` is specified).
+  - `replace`: The string to replace the `find` string with (e.g. `http://localhost:3000`) (required if `find` is specified).
+  - `exclude`: An array of strings with regular expressions to exclude URLs from the sitemap (e.g. `['\.pdf$']` to exclude any PDF files). Since these are string representations of regular expressions, the backslash must be escaped (e.g. `\\.`). Exclude is performed before find/replace, so uses the original URLs from the sitemap.
 - `urls`: An array of URLs to be tested, which must contain at least one value. Each array entry can either be a URL string, or an object that contains a `url` string and an optional `settings` object. This object can contain any of the `settings` values identified above and will override that setting for testing that URL. The `url` string can be either an actual URL or a local file, as shown in the example below.
 
 ```json
@@ -242,7 +247,7 @@ All available settings with the default values are shown below.
   "urls": [
     "https://gitlab.com/gitlab-ci-utils/pagean/",
     {
-      "url": "./tests/test-cases/consoleLog.html",
+      "url": "./tests/fixtures/site/consoleLog.html",
       "settings": {
         "consoleOutputTest": false
       }
@@ -281,7 +286,7 @@ pagean:
 
 ### Testing With Static HTTP Server
 
-The Docker image shown above includes [`http-server`](https://www.npmjs.com/package/http-server) and [`wait-on`](https://www.npmjs.com/package/wait-on) installed globally to run a local HTTP server for testing static content. The example job below illustrates how to use this for Pagean tests. The script starts the server in this project's `test-cases` directory and uses `wait-on` to hold the script until the server is running and returns a valid response. The referenced `pageanrc` file is the same as the project default `pageanrc`, but references all test URLs from the local server.
+The Docker image shown above includes [`serve`](https://www.npmjs.com/package/serve) and [`wait-on`](https://www.npmjs.com/package/wait-on) installed globally to run a local HTTP server for testing static content. The example job below illustrates how to use this for Pagean tests. The script starts the server in this project's `./tests/fixtures/site` directory and uses `wait-on` to hold the script until the server is running and returns a valid response. The referenced `pageanrc` file is the same as the project default `pageanrc`, but references all test URLs from the local server.
 
 ```yaml
 pagean:
@@ -289,10 +294,8 @@ pagean:
   stage: test
   before_script:
     # Start static server in test cases directory, discarding any console output,
-    # 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
+    # and wait until the server is running.
+    - serve ./tests/fixtures/site > /dev/null 2>&1 & wait-on http://localhost:3000
   script:
     - pagean -c static-server.pageanrc.json
   artifacts:
@@ -326,14 +329,15 @@ The `--json` option outputs the JSON results to stdout in all cases for consiste
 
 ```sh
 .\tests\test-configs\cli-tests\some-test.pageanrc.json
-  <pageanrc>.puppeteerLaunchOptions                  should NOT have fewer than 1 items
-  <pageanrc>.reporters[0]                            should be equal to one of the allowed values (cli, html, json)
-  <pageanrc>.settings.consoleOutputTest              should be either boolean or object with the appropriate properties
-  <pageanrc>.settings.pageLoadTimeTest.foo           should NOT contain additional properties: "foo"
-  <pageanrc>.settings.pageLoadTimeTest               should be either boolean or object with the appropriate properties
-  <pageanrc>.urls[2].settings.consoleOutputTest      should be either boolean or object with the appropriate properties
-  <pageanrc>.urls[3]                                 should be either URL string or object with the appropriate properties
-  <pageanrc>.urls[5]                                 should have required property url
+  <pageanrc>.puppeteerLaunchOptions                  must NOT have fewer than 1 properties
+  <pageanrc>.reporters[0]                            must be equal to one of the allowed values (cli, html, json)
+  <pageanrc>.settings.consoleOutputTest              must be either boolean or object with the appropriate properties
+  <pageanrc>.settings.pageLoadTimeTest.foo           must NOT contain additional properties: "foo"
+  <pageanrc>.settings.pageLoadTimeTest               must be either boolean or object with the appropriate properties
+  <pageanrc>.sitemap                                 must use 'find' and 'replace' together
+  <pageanrc>.urls[2].settings.consoleOutputTest      must be either boolean or object with the appropriate properties
+  <pageanrc>.urls[3]                                 must be either URL string or object with the appropriate properties
+  <pageanrc>.urls[5]                                 must have required property 'url'
 ```
 
 In some cases, a single error might result in multiple messages based on the options in the schema definition, especially for cases that can be either a single value or an object with specific properties (e.g. the errors for `<pageanrc>.settings.pageLoadTimeTest` in the example above).

package/bin/pagean.js

@@ -19,14 +19,19 @@ program
     .parse(process.argv);
 const options = program.opts();
 
-try {
-    const config = getConfig(options.config);
-    pagean.executeAllTests(config);
-} catch (error) {
-    log({
-        message: `Error executing pagean tests\n${error.message}`,
-        level: Levels.Error,
-        exitOnError: true,
-        errorCode: 1
+getConfig(options.config)
+    /* eslint-disable-next-line promise/always-return -- required instead
+       of top level await */
+    .then((config) => {
+        pagean.executeAllTests(config);
+    })
+    /* eslint-disable-next-line promise/prefer-await-to-callbacks --
+       required instead of top level await */
+    .catch((error) => {
+        log({
+            errorCode: 1,
+            exitOnError: true,
+            level: Levels.Error,
+            message: `Error executing pagean tests\n${error.message}`
+        });
     });
-}

package/bin/pageanrc-lint.js

@@ -19,13 +19,13 @@ program
 const options = program.opts();
 
 const logError = (message, exitOnError = true) => {
-    log({ message, level: Levels.Error, exitOnError, errorCode: 1 });
+    log({ errorCode: 1, exitOnError, level: Levels.Error, message });
 };
 
 const outputJsonResults = (configFileName, lintResults) => {
     // Log JSON to stdout for consistency, and eliminates extraneous stderr
     // output in PowerShell which produces invalid JSON if piped to file.
-    // eslint-disable-next-line no-magic-numbers -- index
+    // eslint-disable-next-line no-magic-numbers -- no-magic-numbers - index
     log({ message: JSON.stringify(lintResults.errors, undefined, 2) });
     if (!lintResults.isValid) {
         logError(`Errors found in file ${configFileName}`);

package/index.js

@@ -12,13 +12,15 @@ const testReporter = require('./lib/reporter');
 const { ...testFunctions } = require('./lib/tests');
 const { createLinkChecker } = require('./lib/link-utils');
 
+/* eslint-disable no-await-in-loop, max-lines-per-function --
+   no-await-in-loop - tests are deliberately performed synchronously,
+   max-lines-per-function - allowed to test executor */
 /**
  * Executes Pagean tests as specified in config and reports results.
  *
  * @param {object} config The Pagean test configuration.
  * @static
  */
-// eslint-disable-next-line max-lines-per-function
 const executeAllTests = async (config) => {
     const logger = testLogger(config);
     const linkChecker = createLinkChecker();
@@ -31,22 +33,22 @@ const executeAllTests = async (config) => {
         const page = await browser.newPage();
         page.on('console', (message) =>
             consoleLog.push({
-                type: message.type(),
+                location: message.location(),
                 text: message.text(),
-                location: message.location()
+                type: message.type()
             })
         );
         await page.goto(testUrl.url, { waitUntil: 'load' });
 
         const testContext = {
-            page,
             consoleLog,
+            linkChecker,
+            logger,
+            page,
             urlSettings: {
                 ...testUrl.settings,
                 htmlHintConfig: config.htmlHintConfig
-            },
-            logger,
-            linkChecker
+            }
         };
         for (const test of Object.keys(testFunctions)) {
             await testFunctions[test](testContext);
@@ -64,5 +66,6 @@ const executeAllTests = async (config) => {
         process.exit(2);
     }
 };
+/* eslint-enable no-await-in-loop, max-lines-per-function -- enable */
 
 module.exports.executeAllTests = executeAllTests;

package/lib/config.js

@@ -8,11 +8,13 @@
 
 const fs = require('fs');
 const path = require('path');
-const Ajv = require('ajv').default;
+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');
 
 const { normalizeLink } = require('./link-utils');
+const { getUrlsFromSitemap } = require('./sitemap');
 
 const defaultConfig = require('./default-config.json');
 const defaultHtmlHintConfigFilename = './.htmlhintrc';
@@ -43,6 +45,8 @@ const processAllTestSettings = (settings) => {
     for (const key of Object.keys(settings)) {
         processedSettings[key] = processTestSetting(settings[key]);
     }
+    /* eslint-disable-next-line consistent-return -- return undefined
+       if no settings */
     return processedSettings;
 };
 
@@ -70,18 +74,35 @@ const consolidateTestSettings = (
     return processedSettings;
 };
 
-const processUrls = (config) => {
+const addSitemapUrls = (config, sitemapUrls) => {
+    if (config.urls) {
+        for (const url of config.urls) {
+            const { rawUrl } = getUrl(url);
+            const index = sitemapUrls.indexOf(rawUrl);
+            index > -1 && sitemapUrls.splice(index, 1);
+        }
+        config.urls.push(...sitemapUrls);
+    } else {
+        config.urls = sitemapUrls;
+    }
+};
+
+const processUrls = async (config) => {
     const processedConfigSettings = processAllTestSettings(config.settings);
+    if (config.sitemap) {
+        const sitemapUrls = await getUrlsFromSitemap(config.sitemap);
+        addSitemapUrls(config, sitemapUrls);
+    }
     return config.urls.map((testUrl) => {
         const { rawUrl, urlSettings } = getUrl(testUrl);
         return {
-            url: protocolify(rawUrl),
             rawUrl,
             settings: consolidateTestSettings(
                 defaultConfig.settings,
                 processedConfigSettings,
                 processAllTestSettings(urlSettings)
-            )
+            ),
+            url: protocolify(rawUrl)
         };
     });
 };
@@ -90,6 +111,8 @@ const getHtmlHintConfig = (htmlHintConfigFilename) => {
     if (!fs.existsSync(htmlHintConfigFilename)) {
         return;
     }
+    /* eslint-disable-next-line consistent-return -- return undefined
+       if no settings */
     return JSON.parse(fs.readFileSync(htmlHintConfigFilename, 'utf8'));
 };
 
@@ -100,15 +123,15 @@ const validateConfigSchema = (config) => {
         )
     );
     const ajv = new Ajv({ allErrors: true });
+    ajv.addMetaSchema(draft7MetaSchema);
     ajvErrors(ajv);
     const validate = ajv.compile(schema);
     const isValid = validate(config);
-    return { isValid, errors: validate.errors || [] };
+    return { errors: validate.errors || [], isValid };
 };
 
-const getConfigFromFile = (configFileName) => {
-    return JSON.parse(fs.readFileSync(configFileName, 'utf8'));
-};
+const getConfigFromFile = (configFileName) =>
+    JSON.parse(fs.readFileSync(configFileName, 'utf8'));
 
 /**
  * Loads config from file and returns consolidated config with
@@ -116,10 +139,12 @@ const getConfigFromFile = (configFileName) => {
  *
  * @param   {string}    configFileName Pagean configuration file name.
  * @returns {object}                   Consolidated Pagean configuration.
+ * @async
  * @throws  {TypeError}                Throws if config file has an invalid schema.
  * @static
+ * @public
  */
-const processConfig = (configFileName) => {
+const processConfig = async (configFileName) => {
     const config = getConfigFromFile(configFileName);
     const { isValid } = validateConfigSchema(config);
     if (!isValid) {
@@ -128,13 +153,16 @@ const processConfig = (configFileName) => {
         );
     }
     return {
-        project: config.project || '',
-        puppeteerLaunchOptions: config.puppeteerLaunchOptions,
-        urls: processUrls(config),
         htmlHintConfig: getHtmlHintConfig(
             config.htmlhintrc || defaultHtmlHintConfigFilename
         ),
-        reporters: config.reporters || defaultConfig.reporters
+        project: config.project || '',
+        puppeteerLaunchOptions: {
+            ...defaultConfig.puppeteerLaunchOptions,
+            ...config.puppeteerLaunchOptions
+        },
+        reporters: config.reporters || defaultConfig.reporters,
+        urls: await processUrls(config)
     };
 };
 

package/lib/default-config.json

@@ -32,6 +32,9 @@
       "ignoreDuplicates": true
     }
   },
+  "puppeteerLaunchOptions": {
+    "headless": "new"
+  },
   "reporters": ["cli", "html", "json"],
   "urls": ["ignored, required to validate schema"]
 }

package/lib/link-utils.js

@@ -9,6 +9,7 @@
 const https = require('https');
 const axios = require('axios');
 const normalizeUrl = require('normalize-url');
+const cssesc = require('cssesc');
 
 const msPerSec = 1000;
 const timeoutSeconds = 120;
@@ -23,6 +24,7 @@ const timeoutSeconds = 120;
 const httpResponse = Object.freeze({
     continue: 100,
     ok: 200,
+    // eslint-disable-next-line sort-keys -- order by response code
     badRequest: 400,
     notFound: 404,
     tooManyRequests: 429,
@@ -51,7 +53,6 @@ const normalizeLink = (url) =>
         stripHash: true,
         stripWWW: false
     });
-/* eslint-enable jsdoc/require-description-complete-sentence */
 
 /**
  * Checks settings to determine if the provided link should be ignored.
@@ -94,7 +95,10 @@ const checkSamePageLink = async (page, link) => {
         return httpResponse.ok;
     }
 
-    const element = await page.$(selector);
+    const escapedSelector = `#${cssesc(selector.slice(1), {
+        isIdentifier: true
+    })}`;
+    const element = await page.$(escapedSelector);
     return element ? httpResponse.ok : `${selector} Not Found`;
 };
 
@@ -117,7 +121,7 @@ const checkExternalPageLinkBrowser = async (page, link) => {
     } catch (error) {
         // Errors are returned in the format: "ENOTFOUND at https://this.url.does.not.exist/",
         // so extract error only and remove URL
-        status = error.message.replace(/^(.*) at .*$/, '$1');
+        status = error.message.replace(/^(?<message>.*) at .*$/, '$1');
     }
     return status;
 };
@@ -144,15 +148,16 @@ const checkExternalPageLink = async (page, link, useGet = false) => {
 
     try {
         const options = {
+            decompress: false,
             headers: { 'User-Agent': userAgent },
-            timeout: timeoutSeconds * msPerSec,
+            timeout: timeoutSeconds * msPerSec
             // Axios can generate an error trying to decompress an empty compressed
             // HEAD response, see https://github.com/axios/axios/issues/5102.
             // The response body is also not used, so more efficient to skip.
-            decompress: false
         };
         // Using internal browser property since not exposed
-        // eslint-disable-next-line no-underscore-dangle
+        /* eslint-disable-next-line no-underscore-dangle -- require to match
+           Puppeteer API */
         if (page.browser()._ignoreHTTPSErrors) {
             const agent = new https.Agent({ rejectUnauthorized: false });
             options.httpsAgent = agent;
@@ -179,7 +184,7 @@ const checkExternalPageLink = async (page, link, useGet = false) => {
 };
 
 /**
- * Factory function returning a linkChecker object with a {@link checkLink}
+ * Factory function returning a linkChecker object with a checkLink
  * function that caches checked link results.
  *
  * @returns {object} Link checker object.
@@ -200,7 +205,7 @@ const createLinkChecker = () => {
          * @returns {(string|number)}         The link status (HTTP response code or error).
          * @public
          */
-        // eslint-disable-next-line sonarjs/cognitive-complexity
+        // eslint-disable-next-line sonarjs/cognitive-complexity -- allow < 10
         checkLink: async (context, link) => {
             let status = httpResponse.unknownError;
             try {

package/lib/logger.js

@@ -10,8 +10,8 @@ const consoleLogger = require('ci-logger');
 const { reporterTypes } = require('../lib/reporter');
 
 const testResultSymbols = Object.freeze({
-    passed: ' √',
     failed: ' ×',
+    passed: ' √',
     warning: ' ‼'
 });
 
@@ -25,7 +25,7 @@ const nullFunction = () => {};
  * @returns {object}        A logger object.
  * @static
  */
-// eslint-disable-next-line max-lines-per-function
+// eslint-disable-next-line max-lines-per-function -- factory function with state
 module.exports = (config) => {
     const cliReporter = {
         // If cli reporter is enabled, set console log function, otherwise null function
@@ -38,15 +38,15 @@ module.exports = (config) => {
     };
 
     const testResults = {
-        project: config.project,
         executionStart: new Date(),
+        project: config.project,
+        results: [],
         summary: {
-            tests: 0,
+            failed: 0,
             passed: 0,
-            warning: 0,
-            failed: 0
-        },
-        results: []
+            tests: 0,
+            warning: 0
+        }
     };
 
     let currentUrlTests;
@@ -59,8 +59,8 @@ module.exports = (config) => {
      */
     const startUrlTests = (url) => {
         const urlTestResults = {
-            url,
-            tests: []
+            tests: [],
+            url
         };
         testResults.results.push(urlTestResults);
         currentUrlTests = urlTestResults;
@@ -72,7 +72,7 @@ module.exports = (config) => {
      * by the last call to StartUrlTests).
      *
      * @instance
-     * @param {object} testResult The test results.
+     * @param {object} testResult The test results object.
      */
     const logTestResults = (testResult) => {
         if (testResult) {
@@ -81,8 +81,8 @@ module.exports = (config) => {
             testResults.summary[testResult.result]++;
 
             cliReporter.log({
-                message: `${testResult.name} (${testResult.result})`,
                 isResult: true,
+                message: `${testResult.name} (${testResult.result})`,
                 resultPrefix: testResultSymbols[testResult.result]
             });
         }
@@ -107,8 +107,8 @@ module.exports = (config) => {
     };
 
     return {
-        startUrlTests,
+        getTestResults,
         logTestResults,
-        getTestResults
+        startUrlTests
     };
 };

package/lib/report-template.handlebars

@@ -11,7 +11,7 @@
 
 		body {
 			color: #333333;
-			font-family: Arial, Helvetica, sans-serif;
+			font-family: system-ui, sans-serif;
 			font-size: 0.85rem;
 			margin: auto;
 			max-width: 1000px;
@@ -98,12 +98,17 @@
 			margin-block-start: 1rem;
 		}
 
-		details summary .name::after {
-			content: " ⏵";
+		details summary .name::after,
+		details[open] summary .name::after {
+			content: "+";
+			font-family: monospace;
+			font-weight: bold;
+			opacity: 0.8;
+    		padding-left: 0.5rem;
 		}
 
 		details[open] summary .name::after {
-			content: " ⏷";
+			content: "–";
 		}
 
 		summary {
@@ -192,7 +197,7 @@
 				<li class="test {{result}}">
 					{{#if data}}
 					<details>
-						<summary class="header">
+						<summary class="header" title="Show/hide details">
 							<div class="name">{{name}}</div>
 							<div class="result">{{result}}</div>
 						</summary>

package/lib/reporter.js

@@ -13,10 +13,10 @@ const htmlReportTemplateName = 'report-template.handlebars';
 const htmlReportFileName = './pagean-results.html';
 const jsonReportFileName = './pagean-results.json';
 
-handlebars.registerHelper('json', (context) => {
-    // eslint-disable-next-line no-magic-numbers -- count
-    return JSON.stringify(context, undefined, 2);
-});
+handlebars.registerHelper('json', (context) =>
+    // eslint-disable-next-line no-magic-numbers -- no-magic-numbers - count
+    JSON.stringify(context, undefined, 2)
+);
 
 const saveHtmlReport = (results) => {
     const templateFile = path.resolve(

package/lib/schema-errors.js

@@ -24,8 +24,8 @@ const getDataKey = (instancePath) => {
             // eslint-disable-next-line unicorn/no-array-reduce -- reduce for string concatenation
             .reduce((accumulator, currentValue) => {
                 const unencodedValue = currentValue
-                    .replace(/~0/g, '~')
-                    .replace(/~1/g, '/');
+                    .replaceAll('~0', '~')
+                    .replaceAll('~1', '/');
                 const encodedValue = Number.isNaN(Number(unencodedValue))
                     ? `.${unencodedValue}`
                     : `[${unencodedValue}]`;

package/lib/sitemap.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const axios = require('axios');
+const { parseStringPromise } = require('xml2js');
+
+const fs = require('fs');
+
+/**
+ * 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.
+ * @static
+ * @private
+ */
+const getSitemap = async (url) => {
+    try {
+        if (url.startsWith('http')) {
+            const response = await axios.get(url);
+            return response.data;
+        }
+        return fs.readFileSync(url, 'utf8');
+    } catch {
+        throw new Error(`Error retrieving sitemap "${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
+ * @static
+ * @private
+ */
+const parseSitemap = async (sitemapXml) => {
+    const sitemapData = await parseStringPromise(sitemapXml);
+    if (!sitemapData.urlset.url) {
+        return [];
+    }
+    return sitemapData.urlset.url.map((url) => url.loc[0]);
+};
+
+/**
+ * Removes excluded URLs from the list of URLs.
+ *
+ * @param   {string[]} urls    The URLs from the sitemap.
+ * @param   {string[]} exclude The URLs to exclude (regular expressions).
+ * @returns {string[]}         The non-excluded URLs from the sitemap.
+ * @static
+ * @private
+ */
+const removeExcludedUrls = (urls, exclude = []) => {
+    const excludeRegex = exclude.map((url) => new RegExp(url));
+    return urls.filter((url) => {
+        for (const excludeUrlRegex of excludeRegex) {
+            if (excludeUrlRegex.test(url)) {
+                return false;
+            }
+        }
+        return true;
+    });
+};
+
+/**
+ * Replaces the "find" string with the "replace" string in each of the URLs.
+ *
+ * @param   {string[]} urls      The URLs to process.
+ * @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
+ */
+const replaceUrlStrings = (urls, find, replace) => {
+    if (!find || !replace) {
+        return urls;
+    }
+    return urls.map((url) => url.replace(find, replace));
+};
+
+/**
+ * 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.
+ * @static
+ * @public
+ */
+const getUrlsFromSitemap = async ({ url, find, replace, exclude } = {}) => {
+    const sitemapXml = await getSitemap(url);
+    try {
+        const rawUrls = await parseSitemap(sitemapXml);
+        return replaceUrlStrings(
+            removeExcludedUrls(rawUrls, exclude),
+            find,
+            replace
+        );
+    } catch {
+        throw new Error(`Error processing sitemap "${url}"`);
+    }
+};
+
+module.exports.getUrlsFromSitemap = getUrlsFromSitemap;

package/lib/test-utils.js

@@ -7,9 +7,9 @@
  */
 
 const testResultStates = Object.freeze({
+    failed: 'failed',
     passed: 'passed',
-    warning: 'warning',
-    failed: 'failed'
+    warning: 'warning'
 });
 
 const getTestSettings = (testSettingProperty, urlSettings) => {
@@ -26,7 +26,7 @@ const getTestSettings = (testSettingProperty, urlSettings) => {
  * test-specific settings from configuration, passing the test context,
  * and logging results.
  *
- * @param {string}   name                The name of the 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
@@ -50,7 +50,7 @@ const pageanTest = async (
         try {
             results = await testFunction(testContext);
         } catch (error) {
-            results = { result: testResultStates.failed, data: { error } };
+            results = { data: { error }, result: testResultStates.failed };
         }
         if (
             results.result === testResultStates.failed &&

package/lib/tests.js

@@ -27,7 +27,10 @@ const horizontalScrollbarTest = async (context) => {
             // istanbul ignore next: injects script causing puppeteer error, see #48
             const scrollbar = await context.page.evaluate(() => {
                 document.scrollingElement.scrollLeft = 1;
-                return document.scrollingElement.scrollLeft === 1;
+                // The scrollLeft value may not end up exactly 1. But, any
+                // value greater than 0 indicates the presence of a horizontal
+                // scrollbar.
+                return document.scrollingElement.scrollLeft > 0;
             });
             return {
                 result:
@@ -136,7 +139,7 @@ const renderedHtmlTest = async (context) => {
  * @param {object} context Test execution context.
  * @static
  */
-// eslint-disable-next-line max-lines-per-function
+// eslint-disable-next-line max-lines-per-function -- exceeded due to formatting
 const pageLoadTimeTest = async (context) => {
     const testSettingName = 'pageLoadTimeTest';
     await pageanTest(
@@ -179,18 +182,16 @@ const pageLoadTimeTest = async (context) => {
  * @param {object} context Test execution context.
  * @static
  */
-// eslint-disable-next-line max-lines-per-function
+// eslint-disable-next-line max-lines-per-function -- exceeded due to formatting
 const externalScriptTest = async (context) => {
     await pageanTest(
         'should not have external scripts',
         // eslint-disable-next-line no-shadow -- less intuitive
         async (context) => {
             // istanbul ignore next: injects script causing puppeteer error, see #48
-            const scripts = await context.page.evaluate(() => {
-                return [...document.querySelectorAll('script[src]')].map(
-                    (s) => s.src
-                );
-            });
+            const scripts = await context.page.evaluate(() =>
+                [...document.querySelectorAll('script[src]')].map((s) => s.src)
+            );
 
             const pageUrl = context.page.url();
             const externalScripts = scripts.filter((script) =>
@@ -223,23 +224,21 @@ const externalScriptTest = async (context) => {
  * @param {object} context Test execution context.
  * @static
  */
-// eslint-disable-next-line max-lines-per-function
+// eslint-disable-next-line max-lines-per-function -- exceeded due to formatting
 const brokenLinkTest = async (context) => {
     await pageanTest(
         'should not have broken links',
         // eslint-disable-next-line no-shadow -- less intuitive
         async (context) => {
             // istanbul ignore next: injects script causing puppeteer error, see #48
-            const links = await context.page.evaluate(() => {
-                return [...document.querySelectorAll('a[href]')].map(
-                    (a) => a.href
-                );
-            });
+            const links = await context.page.evaluate(() =>
+                [...document.querySelectorAll('a[href]')].map((a) => a.href)
+            );
 
             // All links are returned from puppeteer as absolute links, so this filters out
             // javascript and other values and leaves only pages to request.
             const httpLinks = links.filter((link) =>
-                link.match(/(http(s?)|file):\/\//)
+                link.match(/(?<protocol>https?|file):\/\//)
             );
             // Reduce to unique page links so only checked once
             const uniqueHttpLinks = [...new Set(httpLinks)];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagean",
-  "version": "8.0.3",
+  "version": "9.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",
@@ -12,18 +12,18 @@
     "lint": "npm run lint-css && npm run lint-html && npm run lint-js && npm run lint-md",
     "lint-css": "stylelint ./lib/report-template.handlebars",
     "lint-html": "htmlhint ./lib/report-template.handlebars",
-    "lint-js": "eslint \"**/*.js\"",
-    "lint-md": "markdownlint **/*.md --ignore node_modules",
+    "lint-js": "eslint .",
+    "lint-md": "markdownlint-cli2 \"**/*.md\" \"#node_modules\" \"#Archive\"",
     "prettier-check": "prettier --check .",
     "prettier-fix": "prettier --write .",
     "start": "node ./bin/pagean.js",
     "start-lint": "node ./bin/pageanrc-lint.js",
-    "start-lint-all": "npm run start-lint && npm run start-lint -c static-server.pageanrc.json && npm run start-lint -c ./lib/default-config.json",
+    "start-lint-all": "npm run start-lint && npm run start-lint static-server.pageanrc.json && npm run start-lint ./lib/default-config.json",
     "test": "jest --ci --config jest.config.json"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/gitlab-ci-utils/pagean.git"
+    "url": "https://gitlab.com/gitlab-ci-utils/pagean.git"
   },
   "keywords": [
     "analysis",
@@ -37,7 +37,7 @@
   "author": "Aaron Goldenthal <npm@aarongoldenthal.com>",
   "license": "MIT",
   "engines": {
-    "node": "^14.15.0 || ^16.13.0 || >=18.0.0"
+    "node": "^16.13.0 || ^18.12.0 || >=20.0.0"
   },
   "files": [
     "index.js",
@@ -51,28 +51,30 @@
   },
   "homepage": "https://gitlab.com/gitlab-ci-utils/pagean",
   "devDependencies": {
-    "@aarongoldenthal/eslint-config-standard": "^20.0.0",
-    "@aarongoldenthal/stylelint-config-standard": "^12.0.1",
-    "bin-tester": "^3.0.0",
-    "eslint": "^8.33.0",
-    "jest": "^29.4.1",
-    "jest-junit": "^15.0.0",
-    "markdownlint-cli": "^0.33.0",
-    "prettier": "^2.8.3",
+    "@aarongoldenthal/eslint-config-standard": "^22.1.0",
+    "@aarongoldenthal/stylelint-config-standard": "^14.0.0",
+    "bin-tester": "^4.0.1",
+    "eslint": "^8.44.0",
+    "jest": "^29.6.0",
+    "jest-junit": "^16.0.0",
+    "markdownlint-cli2": "^0.8.1",
+    "prettier": "^2.8.8",
     "strip-ansi": "^6.0.1",
-    "stylelint": "^14.16.1"
+    "stylelint": "^15.10.0"
   },
   "dependencies": {
     "ajv": "^8.12.0",
     "ajv-errors": "^3.0.0",
-    "axios": "^1.3.1",
-    "ci-logger": "^5.1.0",
-    "commander": "^10.0.0",
+    "axios": "^1.4.0",
+    "ci-logger": "^6.0.0",
+    "commander": "^11.0.0",
+    "cssesc": "^3.0.0",
     "handlebars": "^4.7.7",
     "htmlhint": "^1.1.4",
     "kleur": "^4.1.5",
     "normalize-url": "^6.1.0",
     "protocolify": "^3.0.0",
-    "puppeteer": "^19.6.3"
+    "puppeteer": "^20.7.4",
+    "xml2js": "^0.6.0"
   }
 }

package/schemas/pageanrc.schema.json

@@ -30,6 +30,48 @@
       "description": "The global test settings to apply to all tests, unless overridden for a specific URL.",
       "$ref": "#/definitions/allTestSettings"
     },
+    "sitemap": {
+      "description": "The sitemap to test",
+      "type": "object",
+      "properties": {
+        "url": {
+          "description": "The URL of the sitemap to test",
+          "type": "string"
+        },
+        "find": {
+          "description": "The string or regex pattern to find in sitemap URLs",
+          "type": "string"
+        },
+        "replace": {
+          "description": "The replacement string in sitemap URLs",
+          "type": "string"
+        },
+        "exclude": {
+          "description": "An array of strings or regex patterns to exclude from the sitemap",
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true,
+          "minItems": 1,
+          "maxItems": 100
+        }
+      },
+      "allOf": [
+        { "required": ["url"], "errorMessage": "must provide 'url'" },
+        {
+          "dependentRequired": {
+            "find": ["replace"],
+            "replace": ["find"]
+          },
+          "errorMessage": "must use 'find' and 'replace' together"
+        }
+      ],
+      "additionalProperties": {
+        "not": true,
+        "errorMessage": "must NOT contain additional properties: ${0#}"
+      }
+    },
     "urls": {
       "description": "The collection of URLs to test, with any URL-specific test settings.",
       "type": "array",
@@ -71,7 +113,16 @@
     "not": true,
     "errorMessage": "must NOT contain additional properties: ${0#}"
   },
-  "required": ["urls"],
+  "anyOf": [
+    {
+      "required": ["sitemap"],
+      "errorMessage": "must have either property 'sitemap' or 'urls' (or both)"
+    },
+    {
+      "required": ["urls"],
+      "errorMessage": "must have either property 'sitemap' or 'urls' (or both)"
+    }
+  ],
   "definitions": {
     "detailedSetting": {
       "description": "The complete set of test-specific settings for most tests.",