Home Page Check Accessibility, HTML, CSS, Broken Links & Spelling

CI version

Total Validator CI runs from the command line for use within an automated testing system, such as continuous integration. Note: The licence prevents using it within any product or service you may provide to third parties.

A Windows batch file for running from the command line is provided called TotalValidatorCI.bat. This may be found in the application folder, for example; C:\Program Files\TotalValidatorCI. An equivalent script called TotalValidatorCI.sh is provided for Linux and macOS. You must run these batch/script files from the folder where they reside so that Total Validator can find all the resources needed, otherwise an error will occur.

If you wish to integrate with the CI version, you can call the batch/script files directly from your application and use the results options to return or save the test results. Alternatively, run the batch/script files with the -startlistener option so that Total Validator CI runs continuously, and then make calls to the Web API.

When you purchase Total Validator CI, you will be given a User ID and an activation.key file (the actual file name may contain a prefix to help manage multiple keys). For Total Validator to start, the activation.key file must be saved in the app sub-folder of the application, and the -id option must be used with your User ID.

Options

The following options may be used when running from the command line. Note that whenever you use Total Validator Pro it automatically creates a properties file in the results folder. This is done to help you to convert what you select in Total Validator Pro into the command line properties below.

Detailed descriptions of each option are provided in the Total Validator Pro documentation for the corresponding option. If any value contains a space character then the whole value must be surrounded by double quotes.

  • -help : display the list of command line options and exit.
  • -properties Path_To_File : Where Path_To_File is a properties file containing the command line options.
  • -id USERID : Where USERID is the Total Validator User ID. This option MUST be supplied for Total Validator to run.
  • -showkey : display the activation key number.

Main options equivalents:

  • -url URL : Where URL is the start page, e.g. https://mywebpage.com/index.html
  • -file Path_To_File : Where Path_To_File is the local start web page, e.g. c:\mysite\index.html.
  • -dtd DTD : Where DTD represents the HTML specification.
  • -accessibility LEVEL : Where LEVEL represents the Accessibility specification.
  • -ignorecsspages : Ignore CSS pages with WCAG 2.
  • -css 1|2.1|3 : Supply one of the CSS levels you wish to test against.
  • -ignorevendor : Ignore CSS vendor extensions.
  • -brokenlinks : Test for and report any broken links.
  • -spellcheck : Perform a spell check.

Additional main options for use with our API or browser extensions:

  • -startlistener : Ignores any -url or -file option and runs forever, waiting for requests to the API or from our browser extensions to start a test.
  • -listenonce : The same as -startlistener, but finishes after the first test is complete.
  • -dom : Simulates the Validate DOM option of the Pro version, by opening a tab in the default system browser, displaying the -url start page, testing the DOM of it, then exiting.
  • -listenport Port : Where Port is the port Total Validator listens on for requests to the API or from our browser extensions. This must be an integer in the range 1-65535. Defaults to 9889.

Include options equivalents:

  • -pages Pages : Where Pages is the number of pages to test. By default it will only test one page. Set this to zero to test all pages.
  • -stopafterpg Pages : Where Pages is the maximum number of pages with issues to report before stopping.
  • -stopafter Issues : Where Issues is the maximum number of issues to report before stopping.
  • -depth Depth : Where Depth is the directory depth below the start page.
  • -excludepath Path_To_Exclude : Where Path_To_Exclude is a path within the starting URL to exclude when testing more than one page (must start with a '/'). Regular expressions may be used, and you can use this option more than once.
  • -includepath Path_To_Include : Where Path_To_Include is a path within the starting URL to include when testing more than one page (must start with a '/'). Regular expressions may be used, and you can use this option more than once.
  • -userobots : Exclude/include paths specified in robots.txt
  • -ignoreidentical : Ignore duplicate pages and style sheets.
  • -followlinks : Follow all links on the start page.
  • -followbelow : Follow links below the start page only.
  • -validateerrors : Test error pages when HTTP error codes are returned.
  • -ignorecase : Ignore case when deciding whether to follow links.
  • -noquery : Strip off query parameters from links before testing or following them.
  • -nosession : Strip off session ids from links before testing or following them, e.g. http://yourdomain/page.html;session_id

Issues options equivalents:

  • -ignoreerrs : Ignore errors.
  • -ignoreprob : Ignore probable errors.
  • -ignorewarn : Ignore warnings.
  • -ignoreinfo : Ignore extra information messages.
  • -exceptissues Issues_List : Exceptions to the above. Where Issues_List is a comma-separated list of issue codes to include.
  • -ignoreissues Issues_List : Ignore these issues. Where Issues_List is a comma-separated list of issue codes to ignore.
  • -issuesbyitem Item_Definition : Ignore issues by id/class/element. Where Item_Definition is in the format: #id|.class|element|element&class=<comma-separated list of issue codes>. Use an empty list to ignore all issues. You can use this option more than once.
  • -cssIssuesbyitem Item_Definition : Ignore CSS issues by property/at-keyword/selector. Where Item_Definition is in the format: @keyword|%selector|property|property&@keyword|property&selector=<comma-separated list of issue codes>. Use an empty list to ignore all issues. You can use this option more than once.
  • -ignoretvmarkup : Ignore any -tv- classes, at-rules or properties on each page.
  • -timeout Seconds : If testing for broken links or more than one page, then Seconds is the time to wait before declaring a link broken. This must be a value between 10 and 120. It defaults to 20.
  • -concurrency Maximum : If testing for broken links or more than one page, then Maximum is the maximum number of links to test simultaneously. This must be a positive integer. Set to 0 to test all links simultaneously. It defaults to 100.
  • -lpause MilliSeconds : If concurrency is set to 1, then MilliSeconds is the time to pause in milliseconds before testing each link. This must be an integer, greater than 0.
  • -reportredirects : If testing for broken links, report all 301/302/303 redirection warnings.
  • -ignoreotherdomains : Will ignore links to domains different to the start page.
  • -ignoreotherhosts : Will ignore links to hosts different to the start page.

Spell Check options equivalents:

  • -uppercase : Spell check words that are all in upper case.
  • -mixedcase : Spell check words that are in mixed case.
  • -wordswithdigits : Spell check words with digits in.
  • -includecode : Spell check words within <samp>, <code>, and <kbd> tags.
  • -checkattrs : Spell check text in these attributes: alt, title, summary, label, prompt, standby.
  • -punctuated : Spell check words surrounded by characters other than quote marks.
  • -ignoresuggestions : Don't display alternative words when a word cannot be found in the dictionary.
  • -checkforrepeats : Display repeated words e.g. 'the the'.
  • -showlangcodes : Display the language code next to each unrecognised word.
  • -savebadwords : Save all the unrecognised words to the personal dictionaries folder.
  • -saveforeign : Save all words with unknown language codes to the personal dictionaries folder.
  • -usebritish : Use British instead of American as the default English language code.
  • -correctionsfolder Path_To_Folder : Where Path_To_Folder is the folder used for personal dictionaries.
  • -owndics Paths_To_Files : Where Paths_To_Files is a comma-separated list of paths to one or more external dictionaries.
  • -ignorelangs Language_Codes : Where Language_Codes is a comma-separated list of language codes to ignore.
  • -defaultlangcode Language_Code : Where Language_Code is the default to use when a page doesn't specify one.

Network options equivalents:

  • -cookiepolicy ACCEPT_ALL|ACCEPT_SERVER|ACCEPT_SESSION|ACCEPT_NONE : Use this option to specify how you wish to deal with cookies. Defaults to ACCEPT_SERVER.
  • -cookie Cookie : Where Cookie is a standard set-cookie HTTP header. This cookie will be treated like a normal cookie received from the server for the start page and subject to the policies defined above.
  • -identity identity : Where identity is the name of a user agent as displayed on the Network tab of Total Validator Pro.
  • -ppause MilliSeconds : Where MilliSeconds is the time to pause in milliseconds before retrieving each page. This must be an integer, greater than 0.
  • -user UserName : Where UserName is required for HTTP authentication.
  • -password Password : Where Password is required for HTTP authentication.

Proxy Server options equivalents:

  • -ignoreproxy : Ignore any operating system proxy settings, e.g. those set in the Internet Options control panel applet in Windows.
  • -proxyhost Host : Where Host is the name of the proxy server you need to go through to access the start page.
  • -proxyport Port : Where Port is the port the proxy server listens on. This must be an integer in the range 1-65535.
  • -proxysocks : Use the SOCKS protocol to talk to the proxy server.
  • -puser UserName : Where UserName is required by an authenticating proxy server.
  • -ppassword Password : Where Password is required by an authenticating proxy server.
  • -noproxyfor Hosts : Where Hosts is a comma-separated list of hosts which bypass the proxy server.

Forms options equivalents: (Also see Notes below)

  • -actionX Action : Where Action is the value of the action attribute value to match for form submission. X is a number greater than zero to allow more than one form to be specified.
  • -actionregexX : Treat the -action option as a regular expression. X is used to match with the correct -action.
  • -submitX Name : Where Name is the name of the submit button to use if there is more than one. X is used to match with the correct -action.
  • -paramX Name=Value : Where Name is the name of a parameter to submit when sending a form, and Value is its value, e.g. -param userid=julie, or -param userid= to send a blank value. X is used to match with the correct -action.
  • -sso : Use SAML authentication.

Results options equivalents:

  • -resultsfolder Path_To_Folder : Where Path_To_Folder is the folder you wish to store the results in. This defaults to the documents folder.
  • -uniquereport : Output the results into a unique folder.
  • -oldreport : Save results using the pre-17.0 report format.
  • -displaybrowser Browser : The browser you wish to display the results when using -showresults, or to test with when using -dom. This defaults to the default system browser. It should be the full path to the browser executable for Linux and Windows, but just the browser's name for macOS.
  • -sortbydefault LINKS|PATH|MOST|LEAST : The default value for the Sort by option on the summary report. Defaults to LINKS.
  • -showsuccess : Use this option to list pages that had no reported issues.
  • -apicompatible : Ensure the results are compatible with the API.

Additional results options:

  • -showresults : Display the results in a browser. Requires a desktop environment. Ignored if -stdout or -suppressresults are used.
  • -showsource : Display the source. To view what was tested, when debugging.
  • -showresultspath : Output the path to the results file to stdout or the Web API.
  • -stdout : Output the results file to stdout. Only works if a single page is being tested.
  • -suppressresults : Do not save the results to disk. If you have -stdout set then the results may still be captured. Useful with -extendedstatus or -savestatus to check for a successful test.
  • -extendedstatus : Output an exit status which is the sum of the values: 4 if any test errors, 2 if any test warnings, 1 if any program errors, and 0 if all okay.
  • -savestatus Path_To_File : Where Path_To_File is a file to save the extended status (see above).

Multiple options

You can specify more than one of each of the above options and each option is processed in the order it appears. Duplicate boolean options (options that do not have a value) such as -brokenlinks are ignored, and non-conflicting options such as -excludepath are added together. But with conflicting options such as -css, the last value is used. So if you use -css 1 and then -css 3, only -css 3 will be used.

HTML values

Values for use with the -dtd option above are listed below. Note that these are case-sensitive and you must include the double quotes for those which include spaces:

Value to use
Auto-detect
Best-fit
HTML5
XHTML5
"XHTML 1.1"
"XHTML Basic 1.1"
"XHTML+ARIA 1.0"
"XHTML+RDFa 1.1"
"XHTML+RDFa 1.0"
"XHTML 1.0 Strict"
"XHTML 1.0 Transitional"
"XHTML 1.0 Frameset"
"XHTML-Print 1.0"
"XHTML Basic 1.0"
"XHTML Mobile 1.2"
"HTML4+ARIA 1.0"
"HTML4+RDFa 1.1"
"HTML4+RDFa Lite 1.1"
"HTML4+RDFa 1.0"
"HTML 4.01 Strict"
"HTML 4.01 Transitional"
"HTML 4.01 Frameset"
"HTML 4.0 Strict"
"HTML 4.0 Transitional"
"HTML 4.0 Frameset"
"ISO/IEC 15445:2000"
"HTML 3.2"
"HTML 2.0"

Accessibility values

Values for use with the -accessibility option above are listed below. Note that these are case-sensitive:

Specification
Value to use
US-508
508
WCAG 2.2 Level A
A22 (or A2 - deprecated)
WCAG 2.2 Level AA
AA22 (or AA2 - deprecated)
WCAG 2.2 Level AAA
AAA22 (or AAA2 - deprecated)
WCAG 2.1 Level A
A21
WCAG 2.1 Level AA
AA21
WCAG 2.1 Level AAA
AAA21
WCAG 2.0 Level A
A20
WCAG 2.0 Level AA
AA20
WCAG 2.0 Level AAA
AAA20
US-508 (pre 2017)
508-OLD
WCAG 1.0 Level A
A
WCAG 1.0 Level AA
AA
WCAG 1.0 Level AAA
AAA

Form options

With the -action, -actionregex, -submit, -param form options you may wish to supply information for more than one form. If so then add a unique number greater than zero to the option name to distinguish between each form.

For example, with just one form you can pass the options like this:

-action authenticate/login -param userid=julie -param password=test

With two forms you need to identify which parameters to use with which form action:

-action1 authenticate/login -param1 userid=julie -param1 password=test
-action2 purchase -submit2 buy -param2 item=SDCard -param2 type=32GB

Properties file

In place of a long command line with lots of options as described above, you can place these options into a properties file instead, and then use the -properties option to refer to this file. You can also specify other command line options to supplement or to override those in the properties file.

Here's an example properties file to help. Note that comments are prefixed with a #, each option must be on its own line, and you must add '=' between options and their values. Blank lines are ignored.

To help you to create this file, whenever you use Total Validator Pro it automatically creates a file called commandline.props in the results folder. This contains all the command line equivalents of the Total Validator Pro settings you have just used.

Multiple options

As with the command line you can specify more than one of each of the options and each option is processed in the order it appears in the file. So where there's a conflict the last entry takes precedence.

You can also specify other command line options along with -properties to supplement or to override those in the properties file. The options in the properties file are processed first followed by those on the command line. So where there's a conflict the last command line option always wins.

In order to override boolean options (options that do not have a value) such as -brokenlinks, you can append :remove to the option name and it will then be ignored. So if you specify -brokenlinks in the properties file and then -brokenlinks:remove on the command line, no broken link check will be performed.

Changes to User Agent identities or HTML5 Meta Names

Total Validator Pro may be used to change the default lists of User Agent identities and HTML5 Meta Names. If Total Validator Pro and Total Validator CI are on the same computer, and being run by the same user, these will be automatically picked up by Total Validator CI as they share the same data folder:

  • On Windows the data folder is <user_home>\AppData\Roaming\TotalValidatorTool
  • On Linux the data folder is ~/.totalvalidatortool
  • On macOS the data folder is <user_home>/Library/Application Support/TotalValidatorTool

However, if you have made changes to either of these lists and Total Validator CI is running on a different computer, or as a different user, you will need to copy the appropriate files from the data folder of Total Validator Pro to the equivalent data folder of Total Validator CI (you will need to manually create this folder for the CI version).

The User Agent identities are stored in a file called identities.props and the Meta Names stored in a file called metanames within the data folder.

Examples

The examples below show how to call the batch/scripts provided to do different things. You must run these batch/script files from the folder where they reside so that Total Validator can find all the resource files needed, otherwise an error will occur.

The following Linux command will test all the pages on a website for compliance against XHTML 1.1, with W3C WCAG 2.2 AAA accessibility, spell checking, and broken link checking:

TotalValidatorCI.sh -url http://www.your_web_site.com/index.html -pages 0 -dtd "XHTML 1.1" -accessibility AAA22 -spellcheck -brokenlinks -id USERID

The following Windows example prompts for a single local web page, then tests it for compliance against the latest HTML5, with Section 508 accessibility, and saves the results in a unique folder:

TotalValidatorCI.bat -uniquereport -dtd HTML5 -accessibility 508 -id USERID

The next example tests a local web site for broken links, reports all redirects but suppresses the reporting of 302 and 303 warnings. It does not save the results, so the exit status will be used to see if it was successful or not:

TotalValidatorCI.sh -suppressresults -extendedstatus -pages 0 -file c:\mysite\index.html -brokenlinks -reportredirects -ignoreissues W302,W303 -id USERID

This example runs continuously waiting for API requests. You can add other options here to use with all your API calls. The -extendedstatus option is automatically configured, so you don't need to add it:

TotalValidatorCI.sh -startlistener -id USERID

To supply the command line options in a properties file (including -id), use:

TotalValidatorCI.bat -properties myprops.props