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

Integrating Total Validator CI with Selenium

The recommended way of integrating Total Validator CI with Selenium is to use the Web API, which works with any programming language and any browser.

This document covers the old, now deprecated, system we used before the Web API was created and is limited to the Java (8+) version of Selenium with just the Chrome browser.

Overview

Start by launching Total Validator CI using the -startlistener option, so that it runs in the background waiting for requests to test something.

Modify your Selenium code to add our browser extension to the Chrome Driver.

In your Selenium code, after displaying a page, use our TotalValidatorAdapter to start a Total Validator test on that page. The TotalValidatorAdapter calls our browser extension which sends all the necessary information to Total Validator CI to perform the test, and return a status code.

Running Total Validator CI

Please see the CI documentation for how to configure and run the CI version. As a minimum you need to use the -startlistener and -id options. Typically you will want to configure other options (such as -accessibility and -suppressresults) which are common to all the pages you wish to test. If there are a lot of options you should consider putting them into a CI properties file for convenience.

You can either run the CI batch/script file from the command line (or PowerShell for Windows), or even start it directly from your Selenium program. But please note that you must run this from the folder where it resides. so that Total Validator can find all the resources needed.

If you are running the CI batch/script file from the command line, then when you've finished testing, you will have to type Ctrl+C or Command+C to stop it, or just close the window it is running in.

Installing/Configuring Selenium

Normally you would install the browser extension from our downloads page. But with Selenium you must have a copy on your filesystem for the Chrome WebDriver to load into Chrome. You will also need a copy of the jar file containing the TotalValidatorAdapter code. You can download these from here:

Total Validator Chrome Extension (totalvalidator.zip)

TotalValidatorAdapter (totalvalidatoradapter.jar)

Note that although the extension file has a .zip suffix, that is just to stop your Chrome browser from trying to install it. You should not unzip this file as it will no longer work. Just save it somewhere convenient.

Add the jar to your CLASSPATH. This contains the TotalValidatorAdapter code which coordinates everything.

Modify your Selenium code to add the extension to Chrome and create an instance of TotalValidatorAdapter:

  ChromeOptions options = new ChromeOptions();
  options.addExtensions(Paths.get("/path/to/totalvalidator.zip").toFile());
  ChromeDriver driver = new ChromeDriver(options);
  try {
    TotalValidatorAdapter tvAdapter = new TotalValidatorAdapter(driver);
  } catch (IOException e) {
    //Exception thrown if CI application is not already running
  }

You can also provide a port parameter, if you have started the CI application with the -listenport option:

  TotalValidatorAdapter tvAdapter = new TotalValidatorAdapter(driver, port);

Running a Total Validator test in your code

In your Selenium code, after you've loaded and tested each web page, you can then call the runTest() method to test the current page:

  import com.totalvalidator.selenium.TotalValidatorAdapter.TVAction;
  
  //Load web page and perform usual tests on it
  . . .

  //Send a message to Total Validator CI via the browser to test the current page
  int statusCode = -1;
  try {
    statusCode = tvAdapter.runTest(TVAction.SEND_URL);
  } catch (IOException e) {
    //Exception thrown if CI application is not already running
    //Exception thrown if browser extension could not be found
  }

  //Deal with the 'statusCode' then move onto the next page
  . . .

There are three types of test you can perform corresponding to the three Toolbar actions available with our browser extensions. For each type pass the appropriate parameter in the runTest method: TVAction.SEND_URL, TVAction.SEND_DOM, TVAction.SEND_SOURCE.

The statusCode contains the same value as the -extendedstatus exit code (see the CI documentation for details). So a successful test with no issues would return 0, and if the test fails to complete -1 is returned.

Dynamically configuring CI options

If you need to use different CI options for each page you test, you can pass these in a List<String>, in the same format used for a CI properties file: 

  import com.totalvalidator.selenium.TotalValidatorAdapter.TVAction;
  
  //Load and perform usual tests on page
  . . .

  List<String> ciOptions = new ArrayList<>();
  ciOptions.add("-reportredirects");
  ciOptions.add("-ignoreissues=P883,E879");

  //Send a message to Total Validator CI via the browser to start the test
  int statusCode = -1;
  try {
    statusCode = tvAdapter.runTest(TVAction.SEND_URL, ciOptions);
  } catch (IOException e) {
    //Exception thrown if CI application is not already running
    //Exception thrown if browser extension could not be found
  }

  //Deal with the 'statusCode' then move onto the next page
  . . .

Note that the options you send here are added to the options you started the CI application with. In some cases these will overwrite the original options, but in others (such as with -ignoreissues) it will add to them. If in doubt about any option do not start the CI application with it, and instead add it to the List for each page.

Extending the wait time

By default TotalValidatorAdapter will only wait a maximum of 1 minute for the CI application to complete a test, before returning a -1 status code. In some circumstances (for example: many broken links on a page) the test may take much longer than this. Meanwhile the CI application will continue to run the test blocking any further runTest() calls until it is completed.

You can change the default maximum wait time, by passing a different value in the TotalValidatorAdapter constructor:

TotalValidatorAdapter tvAdapter = new TotalValidatorAdapter(driver, defaultMaxWaitTime);
    OR
TotalValidatorAdapter tvAdapter = new TotalValidatorAdapter(driver, port, defaultMaxWaitTime);

Where defaultMaxWaitTime is the java.time.Duration to wait. This must be between 1 second and 24 hours, or it will be ignored.

You can also override this on a test by test basis, by passing a Duration to the runTest() method:

tvAdapter.runTest(TVAction.SEND_URL, maxWaitTime);
    OR
tvAdapter.runTest(TVAction.SEND_URL, ciOptions, maxWaitTime);

Where maxWaitTime is the maximum time to wait for the CI application to complete the test.