Read Me Page
Validate WCAG, Section 508, HTML, CSS, Links, and Spelling

Introduction

Total Validator Embedded only runs from the command line to allow embedding within an automated system shared by many people, for example as used in continuous integration. Note: The licence still prevents embedding within any service or software you may provide to third parties.

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

top

Command line options

The following options may be used when running from the command line. If no options are provided then it will attempt to use a default properties file. 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 translate what you select in Total Validator Pro into the command line properties to select from the list below.

Detailed descriptions of each option are provided in the Total Validator Pro documentation for the corresponding option.

  • -help : displays the list of command line options and exits.
  • -properties Path_To_File : Where Path_To_File is properties file containing the command line options. If this option is used then it must be the only one used on the command line.

Main tab equivalent options:

  • -url URL : Where URL is the starting web page e.g. http://mywebpage.com/index.html
  • -file Path_To_File : Where Path_To_File is the starting web page located on local disk e.g. c:\mysite\index.html. If both this and -url are not supplied but -interact is used, then you will be prompted to choose a starting page on disk.
  • -pages Pages : Where Pages is the number of pages to check. By default it will only check one page. Set this to zero to check all pages.
  • -dtd DTD : Where DTD represents the HTML validation you wish to apply. See below for valid values.
  • -useariacontent : Use ARIA content model rules.
  • -accessibility 508|A2|AA2|AAA2|508-OLD|A|AA|AAA : Supply one of the values 508|A2|AA2|AAA2|508-OLD|A|AA|AAA to represent the WAI or Section 508 validation you wish to apply.
  • -css 1|2.1|3 : Supply one of the CSS levels for the standard you wish to test against.
  • -ignorevendor : Ignore CSS vendor extensions.
  • -brokenlinks : Check for and report any broken links.
  • -spellcheck : Perform a spell check.
  • -ignoreinfo : Ignore extra information messages.
  • -ignorewarn : Ignore warnings.
  • -ignoreprob : Ignore probable errors.
  • -listenport Port : Where Port is the port Total Validator Pro listens on for spell check additions to a dictionary. This must be an integer in the range (1-65535). It defaults to 9890.

Include tab equivalent options:

  • -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.
  • -followbelow : Will just follow links below the starting page.
  • -followlinks : Will follow all links on the starting page.
  • -ignorecase : Ignore case when deciding whether to follow links.
  • -userobots : Exclude/include paths specified in robots.txt
  • -validateerrors : Validate error pages when HTTP error code is returned.
  • -ignoreidentical : Ignore duplicate pages and style sheets.
  • -issuesbyitem Item_Definition : Ignore issues by id/class/element. Where Item_Definition is in the format: #id|.class|element=<comma separated list of issue codes>. Use an empty list to ignore all issues. You can use this option more than once.
  • -ignoreissues Issues_List : Ignore these issues. Where Issues_List is a comma separated list of issue codes to ignore.
  • -includeissues Issues_List : Only validate these issues. Where Issues_List is a comma separated list of issue codes to include.
  • -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 errors plus warnings to report before stopping.
  • -depth Depth : Where Depth is the the directory depth below the starting page.

Links tab equivalent options:

  • -reportredirects :If checking broken links, then all 301/302/303 redirection warnings will be reported.
  • -linkmethod DEFAULT|GET|HEAD : The HTTP Method to use when testing links. Defaults to DEFAULT.
  • -timeout Seconds : If checking 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 checking broken links or more than one page, then Maximum is the maximum number of links to check simultaneously. This must be a positive integer. Set to 0 to check 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 checking each link. This must be an integer, greater than 0.
  • -noquery : Will strip off query parameters from links before testing or following them.
  • -nosession : Will strip off session ids from links before testing or following them. e.g. http://yourdomain/page.html;session_id

Spell check tab equivalent options:

  • -uppercase : Spell check words that are all in upper case. Must appear after -spellcheck
  • -mixedcase : Spell check words that are in mixed case. Must appear after -spellcheck
  • -wordswithdigits : Spell check words with digits in. Must appear after -spellcheck
  • -punctuated : Spell check words surrounded by characters other than quote marks. Must appear after -spellcheck
  • -includecode : Spell check words within <samp>, <code>, and <kbd> tags. Must appear after -spellcheck
  • -checkattrs : Spell check text in these attributes: alt, title, summary, label, prompt, standby. Must appear after -spellcheck
  • -savebadwords : When spell checking save all the misspelt words to the corrections folder. Does not do anything if -suppressresults has been selected.
  • -saveforeign : When spell checking save all words from unrecognised languages to the corrections folder. Does not do anything if -suppressresults has been selected.
  • -usebritish : Use British instead of American as the default English.
  • -ignoresuggestions : When spell checking don't supply any alternative words when a word cannot be found in the dictionary. Must appear after -spellcheck
  • -showlangcodes : Display the language codes next to each misspelt word.
  • -owndics Paths_To_Files : Where Paths_To_Files is a comma-separated list of paths to one or more supplementary/alternative 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.
  • -correctionsfolder Path_To_Folder : Where Path_To_Folder is the folder used for correction dictionaries.

Network tab equivalent options:

  • -ignoreproxy : Ignore any operating system proxy settings e.g. those set in '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 starting web 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 to traverse an authenticating proxy server.
  • -ppassword Password : Where Password is required to traverse an authenticating proxy server.
  • -noproxyfor Hosts : Where Hosts is a comma-separated list of hosts which bypass the proxy server.
  • -cookiepolicy ACCEPT_ALL|ACCEPT_SERVER|ACCEPT_SESSION|ACCEPT_NONE : Use this option to specify how you wish to deal with cookies received whilst validating. 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 starting page and subject to the policies defined above.
  • -ppause MilliSeconds : Where MilliSeconds is the time to pause in milliseconds before retrieving each page. This must be an integer, greater than 0.
  • -identity identity : Where identity is the name of a user agent in the identities.props file.

Authentication tab equivalent options:

  • -user UserName : Where UserName is required for HTTP protected web pages.
  • -password Password : Where Password is required for HTTP protected web pages.
  • -clientcert Path_To_Cert : Where Path_To_Cert is the path to a standard #pkcs12 certificate.
  • -clientcertpwd Password : Where Password is the password for the #pkcs12 certificate
  • -truststore Path_To_Store : Where Path_To_Store is the path to a Java Key Store.
  • -truststorepwd Password : Where Password is the password for the Java Key Store.

Forms tab equivalent options: (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 tab equivalent options:

  • -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 using a unique report name.
  • -detailsdefault HOVER|SHOW_ALL|HIDE_ALL : The default value for the 'Display issues details' option on the Results. Defaults to HOVER.
  • -sortbydefault LINKS|PATH|MOST|LEAST : The default value for the 'Sort by' option on the Results. Defaults to LINKS.
  • -showsuccess : Use this option to list pages that had no reported issues.
  • -shortreport : Select the 'Short report' checkbox on the results.
  • -hidecontent : Select the 'Hide content' checkbox on the results.
  • -shortestreport : Display a short form of the report.

Additional results options:

  • -showresultspath : Output to stdout the path to the results file.
  • -stdout : Output the results file to stdout. Only works if a single page is being validated.
  • -suppressresults : Do not save the validation results to disk. If you have -stdout set then the results may still be captured. Useful with -extendedstatus to check how successful the validation was.
  • -extendedstatus : Output an exit status which is the sum of the values: 4 if any validation errors, 2 if any warnings, 1 if any program errors, and 0 if all okay.

top

DTD values

Valid values for use with the -dtd option above are listed below. Note that these are case-sensitive and you must include the double quotes where shown:

  • Auto-detect
  • Best-fit
  • HTML5
  • XHTML5
  • HTML5R
  • XHTML5R
  • "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"

Forms 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

top

Properties file

In place of a long command line with lots of options as described above, you can place all these options into a properties file instead, and then just use the single -properties option to refer to this 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 properties and their values. Blank lines are ignored.

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

If no command line options are provided it will look for a file called commandline.props in the <data> folder:

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

The location of this folder is also displayed in the 'About' menu of Total Validator Pro.

top

Identities file

Use the option at the bottom of the Total Validator Pro Include tab to manage the list of available User Agent identities. This allows you to edit the list of entries stored in a file called identities.props. If Total Validator Pro and Total Validator Embedded are on the same computer, there is nothing further to do and the -identity option can now be used.

If the Total Validator Embedded is running on a different computer then you need to copy the identities.props file from a computer running Total Validator Pro. This file may be found in the <data> folder of Total Validator Pro and should be copied to the equivalent <data> folder of the Total Validator Embedded. The location of the <data> folder on each operating system is given in the previous section.

top

Examples

The examples below show how to modify 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 of the resource files needed, otherwise an error will occur.

The following command will check all the pages on a website for compliance against XHTML 1.1, with W3C WCAG2 AAA accessibility, spell checking, and broken links checking:

$tv -url http://www.your_web_site.com/index.html -pages 0 -dtd "XHTML 1.1" -accessibility AAA2 -spellcheck -brokenlinks

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

$tv -uniquereport -dtd HTML5 -accessibility 508

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:

$tv -suppressresults -extendedstatus -pages 0 -file c:\mysite\index.html -brokenlinks -reportredirects -ignoreissues W302,W303

To supply the command line options in the default commandline.props properties file, simply use:

$tv

To supply the command line options in your own properties file, use:

$tv -properties myprops.props

top