pagean 4.4.2 → 6.0.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Aaron Goldenthal
+Copyright (c) 2019 - 2021 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/README.md

@@ -2,8 +2,6 @@
 
 Pagean is a web page analysis tool designed to automate tests requiring web pages to be loaded in a browser window (e.g. 404 error loading an external resource, page renders with horizontal scrollbars).  The specific tests are outlined below, but are all general tests that do not include any page-specific logic.
 
-**Note: As of v4.0.0, this module is being being released as `pagean` and `page-load-tests` has been deprecated. This drove breaking configuration changes that will require updating your project's configuration file. See the [version upgrade guide](https://gitlab.com/gitlab-ci-utils/pagean/-/blob/master/docs/upgrade-guide.md) for complete details.**
-
 ## Installation
 
 Install Pagean globally (as shown below), or locally, via [npm](https://www.npmjs.com/).
@@ -121,7 +119,11 @@ Each external script is saved only once, but will be reported on any page where
 The broken link test checks for broken links on the page. It checks any `<a>` tag on the page with `href` pointing to another location on the current page or another page (i.e. only `http(s)` or `file` protocols).
 
 - For links within the page, this test checks for existence of the element on the page, passing if the element exists and failing otherwise (and passing for cases that are always valid, e.g. `#` or `#top` for the current page).  It does not check the visibility of the element. Failing tests return a response of "#element Not Found" (where `#element` identifies the specific element).
-- For links to other pages, the test makes a `HEAD` request for that URL and checks the response.  If an erroneous response is returned (>= 400 with no execution error) and not code 429 (Too Many Requests), the request is retried with a `GET` request.  The test test passes for HTTP responses < 400 and fails otherwise (if HTTP response is >= 400 or another error occurs). If the link point to an element on that page, there is no check that the element exists.  Some examples have been seen where links that are valid in a browser show an error in this test.
+- For links to other pages, the test tries to most efficiently confirm whether the target link is valid. It first makes a `HEAD` request for that URL and checks the response.  If an erroneous response is returned (>= 400 with no execution error) and not code 429 (Too Many Requests), the request is retried with a `GET` request.  The test passes for HTTP responses < 400 and fails otherwise (if HTTP response is >= 400 or another error occurs).
+  - This can result in false failure indications, specifically for `file://` links (`404` or `ECONNREFUSED`) or where the browser passes a domain identity with the request (page loads when tested, but `401` response for links to that page). For these cases, or other false failures, the test configuration allows a boolean `checkWithBrowser` option that will instead check links by loading the target in the browser (via `puppeteer`). Note this can increase test execution time, in some cases substantially, due to the time to open a new browser tab and plus load the page and all assets.
+  - If the link to another page includes a hash it is removed prior to checking. The test in this case is confirming a valid link, not that the element exists, which is only done for the current page.
+  - The test configuration allows an `ignoredLinks` array listing link URLs to ignore for this test. Note this only applies to links to other pages, not links within the page, which are always checked.
+- To optimize performance, link test results are cached and those links are not re-tested for the entire test run (across all tested URLs). The test configuration allows a boolean `ignoreDuplicates` option that can be set to `false` to bypass this behavior and re-test all links. The results for any failed links are included in the reports in any case.
 
 For any failing test, the `data` array in the test report includes the original URL and the response code or error as shown below.
 
@@ -142,10 +144,6 @@ For any failing test, the `data` array in the test report includes the original
 ]
 ```
 
-The test configuration allows an `ignoredLinks` array listing link URLs to ignore.
-
-**Note: This test currently fails with warning by default so that it is not a breaking change, but this will be updated in the next major release.**
-
 ## Reports
 
 Based on the `reporters` configuration, Pagean results may be displayed in the console and saved in two reports in the project root directory (any or all of the three):
@@ -175,7 +173,7 @@ Below is an example `.pageanrc.json` file, which is broken into six major proper
   - The shorthand notation allows easy enabling/disabling of tests. In this format the test name is given with a boolean value to enable or disable the test.  In this case any other test-specific settings use the default values.
   - The longhand version includes an object for each test. Every test includes two possible properties (some tests include additional settings):
     - `enabled`: A boolean value to enable/disable the test, and some tests include additional settings (default `true` for all tests).
-    - `failWarn`: A boolean value causing a failed test to report a warning instead of failure.  A warning result will not cause the test process to fail (exit with an error code).  The default value for all tests is `false` except the `externalScriptTest` and `brokenLinkTest`, as shown below.
+    - `failWarn`: A boolean value causing a failed test to report a warning instead of failure.  A warning result will not cause the test process to fail (exit with an error code).  The default value for all tests is `false` except the `externalScriptTest`, as shown below.
 
 The shorthand:
 
@@ -238,7 +236,9 @@ All available settings with the default values are shown below.
         },
         "brokenLinkTest": {
             "enabled": true,
-            "failWarn": true,
+            "failWarn": false,
+            "checkWithBrowser": false,
+            "ignoreDuplicates": true,
             "ignoredLinks": []
         }
     },

package/docs/upgrade-guide.md

@@ -1,5 +1,21 @@
 # Version Upgrade Guide
 
+## Upgrading from v4.x to v5.0
+
+1. Update to a Node.js current or LTS release (`^12.20.0 || ^14.15.0 || >=16.0.0`). Pagean may still work in other releases, but is not specifically tested or supported.
+
+2. The Broken Link Test default setting was originally to fail with warning, but this was updated to fail (without warning) to be consistent with the other tests. To return to the previous behavior, update your configuration settings with:
+
+```json
+{
+  "settings": {
+    "brokenLinkTest": {
+      "failWarn": true
+    }
+  }
+}
+```
+
 ## Upgrading from v3.x (`page-load-tests`) to v4.0 (`pagean`)
 
 1. Change the configurations file name from `.pltconfig.json` to `.pageanrc.json`

package/index.js

@@ -5,10 +5,12 @@ const puppeteer = require('puppeteer');
 const testLogger = require('./lib/logger');
 const testReporter = require('./lib/reporter');
 const { ...testFunctions } = require('./lib/tests');
+const { createLinkChecker } = require('./lib/linkUtils');
 
 // eslint-disable-next-line max-lines-per-function
-const executeAllTests = async(config) => {
+const executeAllTests = async (config) => {
     const logger = testLogger(config);
+    const linkChecker = createLinkChecker();
     const browser = await puppeteer.launch(config.puppeteerLaunchOptions);
 
     for (const testUrl of config.urls) {
@@ -21,7 +23,8 @@ 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 };
+        const testContext = { page, consoleLog,
+            urlSettings: { ...testUrl.settings, htmlHintConfig: config.htmlHintConfig }, logger, linkChecker };
         for (const test of Object.keys(testFunctions)) {
             await testFunctions[test](testContext);
         }
@@ -34,8 +37,8 @@ const executeAllTests = async(config) => {
 
     if (testResults.summary.failed > 0) {
         // For test harness want process to exit with error code
-        // eslint-disable-next-line no-process-exit
-        process.exit(1);
+        // eslint-disable-next-line no-process-exit, no-magic-numbers
+        process.exit(2);
     }
 };
 

package/lib/config.js

@@ -46,7 +46,7 @@ const consolidateTestSettings = (defaultSettings, globalSettings, urlSettings) =
     const sanitizedUrlSettings = urlSettings ? urlSettings : {};
     const processedSettings = {};
     for (const key of Object.keys(defaultSettings)) {
-        processedSettings[key] = Object.assign({}, defaultSettings[key], sanitizedGlobalSettings[key], sanitizedUrlSettings[key]);
+        processedSettings[key] = { ...defaultSettings[key], ...sanitizedGlobalSettings[key], ...sanitizedUrlSettings[key] };
     }
     if (processedSettings.brokenLinkTest.ignoredLinks) {
         processedSettings.brokenLinkTest.ignoredLinks = processedSettings.brokenLinkTest.ignoredLinks.map(link => normalizeLink(link));
@@ -73,7 +73,7 @@ const getHtmlHintConfig = (htmlHintConfigFilename) => {
     return JSON.parse(fs.readFileSync(htmlHintConfigFilename, 'utf-8'));
 };
 
-const validateConfigSchema = (config) =>{
+const validateConfigSchema = (config) => {
     const schema = JSON.parse(fs.readFileSync(path.join(__dirname, '../', 'schemas', 'pageanrc.schema.json')));
     const ajv = new Ajv({ allErrors: true });
     ajvErrors(ajv);

package/lib/default-config.json

@@ -1,41 +1,43 @@
 {
-    "settings": {
-        "horizontalScrollbarTest": {
-            "enabled": true,
-            "failWarn": false
-        },
-        "consoleOutputTest": {
-            "enabled": true,
-            "failWarn": false
-        },
-        "consoleErrorTest": {
-            "enabled": true,
-            "failWarn": false
-        },
-        "renderedHtmlTest": {
-            "enabled": true,
-            "failWarn": false
-        },
-        "pageLoadTimeTest": {
-            "enabled": true,
-            "failWarn": false,
-            "pageLoadTimeThreshold": 2
-        },
-        "externalScriptTest": {
-            "enabled": true,
-            "failWarn": true
-        },
-        "brokenLinkTest": {
-            "enabled": true,
-            "failWarn": true
-        }
+  "settings": {
+    "horizontalScrollbarTest": {
+      "enabled": true,
+      "failWarn": false
     },
-    "reporters": [
-        "cli",
-        "html",
-        "json"
-    ],
-    "urls": [
-        "ignored, required to validate schema"
-    ]
-}
+    "consoleOutputTest": {
+      "enabled": true,
+      "failWarn": false
+    },
+    "consoleErrorTest": {
+      "enabled": true,
+      "failWarn": false
+    },
+    "renderedHtmlTest": {
+      "enabled": true,
+      "failWarn": false
+    },
+    "pageLoadTimeTest": {
+      "enabled": true,
+      "failWarn": false,
+      "pageLoadTimeThreshold": 2
+    },
+    "externalScriptTest": {
+      "enabled": true,
+      "failWarn": true
+    },
+    "brokenLinkTest": {
+      "enabled": true,
+      "failWarn": false,
+      "checkWithBrowser": false,
+      "ignoreDuplicates": true
+    }
+  },
+  "reporters": [
+    "cli",
+    "html",
+    "json"
+  ],
+  "urls": [
+    "ignored, required to validate schema"
+  ]
+}

package/lib/externalFileUtils.js

@@ -13,7 +13,7 @@ const shouldSaveFile = (script, page) => {
     return scriptUrl.host !== pageUrl.host;
 };
 
-const saveExternalScript = async(script) => {
+const saveExternalScript = async (script) => {
     const result = { url: script };
     try {
         const scriptUrl = new URL(script);

package/lib/linkUtils.js

@@ -1,10 +1,23 @@
 'use strict';
 
+/**
+ * @module linkUtils
+ */
+
+const https = require('https');
 const axios = require('axios');
 const normalizeUrl = require('normalize-url');
 
 const msPerSec = 1000;
 const timeoutSeconds = 120;
+
+/**
+ * Enum for HTTP responses
+ *
+ * @public
+ * @readonly
+ * @enum {number}
+ */
 const httpResponse = Object.freeze({
     continue: 100,
     ok: 200,
@@ -16,14 +29,59 @@ const httpResponse = Object.freeze({
 
 const noRetryResponses = [httpResponse.tooManyRequests];
 
-const normalizeLink = url => normalizeUrl(url, { defaultProtocol: 'https:', stripWWW: false, removeQueryParameters: [] });
+/**
+ * Normalizes a URL with https://www.npmjs.com/package/normalize-url
+ * using 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
+ *
+ * @public
+ * @param {string} url  The URL to normalize
+ * @returns {string}    The normalized URL
+ */
+const normalizeLink = url => normalizeUrl(url,
+    {
+        defaultProtocol: 'https:',
+        removeQueryParameters: [],
+        stripHash: true,
+        stripWWW: false
+    });
+
+
+/**
+ * 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
+ */
+const ignoreLink = (settings, link) => settings.ignoredLinks && settings.ignoredLinks.includes(link);
 
-// The ignoredLinks values are normalized when settings are processed and does not need to be repeated here.
-const ignoreLink = (settings, link) => settings.ignoredLinks && settings.ignoredLinks.includes(normalizeLink(link));
 
+/**
+ * Checks a response to an HTTP request, either a response code or explicit error,
+ * 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
+ */
 const isFailedResponse = response => isNaN(response.status) || response.status >= httpResponse.badRequest;
 
-const checkSamePageLink = async(page, link) => {
+
+/**
+ * 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)
+ */
+const checkSamePageLink = async (page, link) => {
     const selector = link.slice(page.url().length);
     if (selector === '#' || selector === '#top') {
         return httpResponse.ok;
@@ -33,14 +91,55 @@ const checkSamePageLink = async(page, link) => {
     return element ? httpResponse.ok : `${selector} Not Found`;
 };
 
-// Allow cognitive complexity less than 10
-// eslint-disable-next-line sonarjs/cognitive-complexity
-const checkExternalPageLink = async(page, link, useGet = false) => {
+
+/**
+ * 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)
+ */
+const checkExternalPageLinkBrowser = async (page, link) => {
+    let status;
+    try {
+        const testPage = await page.browser().newPage();
+        const response = await testPage.goto(link);
+        status = response.status();
+        await testPage.close();
+    }
+    catch (err) {
+        // Errors are returned in the format: "ENOTFOUND at https://this.url.does.not.exist/",
+        // so extract error only and remove URL
+        status = err.message.replace(/^(.*) at .*$/, '$1');
+    }
+    return status;
+};
+
+
+/**
+ * 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
+ * @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)
+ */
+// eslint-disable-next-line sonarjs/cognitive-complexity -- Allow less than 10
+const checkExternalPageLink = async (page, link, useGet = false) => {
     // Get user-agent from page so axios uses the same value for requesting links
     const userAgent = await page.evaluate('navigator.userAgent');
 
     try {
         const options = { headers: { 'User-Agent': userAgent }, timeout: timeoutSeconds * msPerSec };
+        // Using internal browser property since not exposed
+        // eslint-disable-next-line no-underscore-dangle
+        if (page.browser()._ignoreHTTPSErrors) {
+            const agent = new https.Agent({ rejectUnauthorized: false });
+            options.httpsAgent = agent;
+        }
         const httpMethod = useGet ? axios.get : axios.head;
         const response = await httpMethod(link, options);
         return response.status;
@@ -59,27 +158,65 @@ const checkExternalPageLink = async(page, link, useGet = false) => {
     }
 };
 
-const checkLink = async(context, link) => {
-    let status = httpResponse.unknownError;
-    try {
-        if (ignoreLink(context.testSettings, link)) {
-            // Set to a unique status so obvious that it's ignored
-            status = httpResponse.continue;
-        }
-        else if (link.startsWith(`${context.page.url()}#`)) {
-            status = await checkSamePageLink(context.page, link);
-        }
-        else {
-            status = await checkExternalPageLink(context.page, link);
+
+/**
+ * Factory function returning a linkChecker object with a {@link checkLink}
+ * function that caches checked link results.
+ *
+ * @public
+ * @returns {Object}
+ */
+// eslint-disable-next-line max-lines-per-function
+const createLinkChecker = () => {
+    const checkedLinks = new Map();
+
+    return {
+        /**
+         * Checks the provided link for validity using context object for a
+         * 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)
+         */
+        // eslint-disable-next-line sonarjs/cognitive-complexity, max-lines-per-function
+        checkLink: async (context, link) => {
+            let status = httpResponse.unknownError;
+            try {
+                // Check all page links first since normalize removes the hash
+                if (link.startsWith(`${context.page.url()}#`)) {
+                    return await checkSamePageLink(context.page, link);
+                }
+
+                const normalizedLink = normalizeLink(link);
+                if (ignoreLink(context.testSettings, normalizedLink)) {
+                    // Set to a unique status so obvious that it's ignored
+                    return httpResponse.continue;
+                }
+
+                if (context.testSettings.ignoreDuplicates && checkedLinks.has(link)) {
+                    return checkedLinks.get(link);
+                }
+
+                if (context.testSettings.checkWithBrowser) {
+                    status = await checkExternalPageLinkBrowser(context.page, normalizedLink);
+                }
+                else {
+                    status = await checkExternalPageLink(context.page, normalizedLink);
+                }
+            }
+            catch {
+                status = httpResponse.unknownError;
+            }
+
+            checkedLinks.set(link, status);
+            return status;
         }
-    }
-    catch {
-        status = httpResponse.unknownError;
-    }
-    return status;
+    };
 };
 
-module.exports.checkLink = checkLink;
+module.exports.createLinkChecker = createLinkChecker;
 module.exports.httpResponse = httpResponse;
 module.exports.isFailedResponse = isFailedResponse;
 module.exports.normalizeLink = normalizeLink;

package/lib/logger.js

@@ -9,7 +9,7 @@ const testResultSymbols = Object.freeze({
     warning: ' ‼'
 });
 
-const nullFunction = () => {};
+const nullFunction = () => { };
 
 // eslint-disable-next-line max-lines-per-function
 module.exports = (config) => {