grunt-check-pages

Grunt task that checks various aspects of a web page for correctness.

Getting Started

This plugin requires Grunt ~0.4.4 or later.

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-check-pages --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-check-pages');

For similar functionality without a Grunt dependency, please see the check-pages package.

For direct use, the check-pages-cli package wraps check-pages with a command-line interface.

The "checkPages" task

Overview

An important aspect of creating a web site is validating the structure, content, and configuration of the site's pages. The checkPages task provides an easy way to integrate this testing into your normal Grunt workflow.

By providing a list of pages to scan, the task can:

Validate each page is accessible
Validate all links point to accessible content (similar to the W3C Link Checker)
Validate links with query string file hashes have the expected content
Validate all links use the secure HTTPS protocol where possible
Validate page structure for XHTML compliance (akin to the W3C Markup Validation Service)
Validate a page's response time is below some threshold
Validate a page takes advantage of caching for better performance
Validate a page takes advantage of compression for better performance

Usage

In your project's Gruntfile, add a section named checkPages to the data object passed into grunt.initConfig(). The following example includes all supported options:

grunt.initConfig({
  checkPages: {
    development: {
      options: {
        pageUrls: [
          'http://localhost:8080/',
          'http://localhost:8080/blog',
          'http://localhost:8080/about.html'
        ],
        checkLinks: true,
        linksToIgnore: [
          'http://localhost:8080/broken.html'
        ],
        noEmptyFragments: true,
        noLocalLinks: true,
        noRedirects: true,
        onlySameDomain: true,
        preferSecure: true,
        queryHashes: true,
        checkCaching: true,
        checkCompression: true,
        checkXhtml: true,
        summary: true,
        terse: true,
        maxResponseTime: 200,
        userAgent: 'custom-user-agent/1.2.3'
      }
    },
    production: {
      options: {
        pageUrls: [
          'http://example.com/',
          'http://example.com/blog',
          'http://example.com/about.html'
        ],
        checkLinks: true,
        maxResponseTime: 500
      }
    }
  }
});

Options

pageUrls

Type: Array of String
Default value: undefined
Required

pageUrls specifies a list of URLs for web pages the task will check. The list can be empty, but must be present. Wildcards are not supported.

URLs can point to local or remote content via the http, https, and file protocols. http and https URLs must be absolute; file URLs can be relative. Some features (for example, HTTP header checks) are not available with the file protocol.

To store the list outside Gruntfile.js, read the array from a JSON file instead: pageUrls: grunt.file.readJSON('pageUrls.json').

checkLinks

Type: Boolean
Default value: false

Enabling checkLinks causes each link in a page to be checked for validity (i.e., an HTTP HEAD or GET request returns success).

For efficiency, a HEAD request is made first and a successful result validates the link. Because some web servers misbehave, a failed HEAD request is followed by a GET request to definitively validate the link.

The following element/attribute pairs are used to identify links:

a/href
area/href
audio/src
embed/src
iframe/src
img/src
img/srcset
input/src
link/href
object/data
script/src
source/src
source/srcset
track/src
video/src
video/poster

linksToIgnore

Type: Array of String
Default value: undefined
Used by: checkLinks

linksToIgnore specifies a list of URLs that should be ignored by the link checker.

This is useful for links that are not accessible during development or known to be unreliable.