Nanoc»Testing Nanoc sites

The check command is used to verify that a compiled site meets the requirements.

A check can be run using nanoc check check-name. For instance, the following will run the internal links check (internal_links or ilinks):

% nanoc check ilinks
Loading site data… done
  Running internal_links check…   ok
%

Available checks

Nanoc comes with the following checks:

css
verifies that the CSS is valid
html
verifies that the HTML is valid
external_links
elinks
verifies that external links are correct
internal_links
ilinks
verifies that internal links are correct
stale
verifies whether no non-Nanoc items are in the output directory
mixed_content
verifies that no content is included or linked to from a potentially insecure source

Deployment-time checks

A file named Checks at the root of a Nanoc site defines which checks should be run before a nanoc deploy.

Here is an example Checks file that ensures that a Nanoc site does not get deployed if there are broken internal links or stale files in the output directory:

deploy_check :internal_links
deploy_check :stale

Here’s what a nanoc deploy looks like when all checks pass:

% nanoc deploy
Loading site data… done
Running issue checks…
  Running internal_links check…   ok
  Running stale check…            ok
No issues found. Deploying!
%

Here’s what a nanoc deploy looks like when some checks fail:

% nanoc deploy
Loading site data… done
Running issue checks…
  Running check internal_links…   error
  Running check stale…            ok
Issues found!
  output/doc/guides/unit-testing-nanoc-sites/index.html:
    [ ERROR ] internal_links - broken reference to ../../api/Nanoc/Site.html
Issues found, deploy aborted.
%

To run the checks marked for deployment without deploying, use nanoc check --deploy.

Custom checks

The Checks file is also used to define custom checks. Here is an example check that verifies that no compiled files contain <% and therefore likely include unprocessed ERB instructions:

check :no_unprocessed_erb do
  @output_filenames.each do |fn|
    if fn =~ /html$/ && File.read(fn).match(/<%/)
      add_issue("erb detected", :subject => fn)
    end
  end
end

In a custom check, you can use #add_issue. The first argument is the description of the problem, and the :subject option defines the location of the problem (usually a filename).

In a custom check, the variables @config, @items, and @layouts are available, in addition to @output_filenames, which is the collection of filenames in the output directory that correspond to an item in the site. For details, see the Variables page.