Create a rule

@@@TODO refactor this doc

Prerequisites

Start by creating your test referential context by using the referential-creator maven plugin.

Once created, let’s implement some rules !

Detection rule

To create a detection rule, implement a class that extends the AbstractDetectionPageRuleImplementation abstract class.

For example, the detection of the h1 tag should be implemented as follows :

public class DetectH1 extends AbstractDetectionPageRuleImplementation {

    public DetectH1 () {
        super(
                // the selector implementation that performs the selection
                new SimpleElementSelector("h1"),
                // solution when at least one element is found
                TestSolution.PASSED,
                // solution when no element is found
                TestSolution.FAILED,
                // no message created when element is found
                // because passed doesn't produce message
                null,
                // General message indicating the element is
                // not present on the page
                "H1TagMissing"
            );
    }

}

This test will return PASSED when at least one h1 element is present on the page, FAILED instead, producing the internationalisable message “H1TagMissing” (see How to internationalize the messages thrown by a test to properly render it in the Asqatasun web-app interface)

Let’s consider the opposite: checking whether an unwished element, like iframe, is absent on the page should be implemented as follows:

public class DetectIframe extends AbstractDetectionPageRuleImplementation {

    /**
     * Default constructor
     */
    public DetectIframe () {
        super(
                new SimpleElementSelector("iframe"),// the selector implementation that performs the selection
                TestSolution.FAILED, // solution when at least one element is found
                TestSolution.PASSED, // solution when no element is found
                "IframeDetected", // message associated with each detected element
                null // no message created when attribute is found because passed doesn't produce message
            );
    }
}

This test will return PASSED when no iframe has been found on the page, FAILED instead, producing the internationalisable message “IframeDetected” for each occurence found on the page. Thus, each occurence will be rendered in the Asqatasun web-app interface with its line number, and snippet of HTML source representing the element.

Selection and check rule

Detection is great, but you often need to perform checks on selected elements. To do so, implement a class that extends the AbstractPageRuleWithSelectorAndCheckerImplementation abstract class. Let’s say that you want to check that all the links (a tags) of a page have not a title attribute. Here is what your class would look like :

public class CheckWhetherEachLinkHaventTitleAttribute extends
                         AbstractPageRuleWithSelectorAndCheckerImplementation {

    public CheckWhetherEachLinkHaventTitleAttribute() {

        super(new SimpleElementSelector("a"), // The ElementSelector implementation
              new AttributePresenceChecker( // The ElementChecker implementation
                  // the attribute to search
                  "title",
                  // solution when attribute is found
                  TestSolution.FAILED,
                  // solution when attribute is not found
                  TestSolution.PASSED,
                  // message associated with element
                  // when attribute is not found
                  "LinkWithTitleDetected",
                  // no message created when attribute is not
                  // found because passed doesn't produce message
                  null)
        );
    }

}

Site level rule

Asqatasun enables to create rules at site level, in other words, make cross-pages checks.

The most obvious example is the verification of the unicity of the title tag for each page. Asqatasun provides the AbstractUniqueElementSiteRuleImplementation abstract class that can be used as follows in this case :

public class CheckTitleContentUnicityAtSiteLevel
                   extends AbstractUniqueElementSiteRuleImplementation {

    /**
     * Constructor
     */
    public CheckTitleContentUnicityAtSiteLevel() {
        super(
                // The ElementSelector implementation
                new SimpleElementSelector("head title"),
                // The TextElementBuilder implementation
                new SimpleTextElementBuilder(),
                // Message associated with element its title
                // is present on another page
                "TitleIdenticalToAnotherPage",
                // Message created to render a cross-page
                // version of the result
                "TitleNotUnique",
                false);
    }
}

This example introduces a new useful interface called TextElementBuilder, that produces a String representation for a given Element. The SimpleTextElementBuilder used in the example simply returns the content of the title element. You may need to use other text element builder implementations or implement your own ones.

Nomenclature based Check rule

Asqatasun uses the concept of nomenclature to create dynamic lists that then can be used as white lists or black lists.

Let’s consider the check of the doctype validity. To avoid to hard-code in the rule implementation the exhaustive list of allowed doctype declarations, a nomenclature (seen as a whitelist here) can be used to handle them. The addition of a new one (HTML6 ?) consists in inserting a new entry in database, without modifying a line of the code. You can have a look at the DoctypeValidityChecker implementation for more details.

The concept of nomenclature can also lead to the check of relevancy. Dealing with this problematic is very difficult and is often taken up with complex algorithms. The usage of a nomenclature as a blacklist enables to detect, in an easy and collaborative way, common irrelevant cases.

From this approach, the relevancy of the title of a page can be compared with a list of definitive irrelevant titles such as ‘Document’, ‘Home’, ‘Welcome’. That list can be then populated from feedbacks by just inserting entries in database. The rule that implements this case could be written as follows:

public class CheckTitleTagRelevancy extends
                 AbstractPageRuleWithSelectorAndCheckerImplementation {
    /**
     * Constructor
     */
    public CheckTitleTagRelevancy() {
        super(new SimpleElementSelector("title"), // The ElementSelector implementation
              new TextBelongsToBlackListChecker( // The ElementChecker implementation
                  // the TextElementBuilder implementation
                  new SimpleTextElementBuilder(),
                  // the name of the irrelevant titles nomenclature
                  "IrrelevantTitleNomenclature",
                  // message created when the title belongs
                  // to the blacklist
                  "IrrelevantTitle",
                  // the text of the title is extracted
                  // and displayed in case of irrelevant
                  "text"
              )
        );
    }

}

To make this test work, an entry named “IrrelevantTitleNomenclature” has to exist in the NOMENCLATURE table of the database. Please refer to the Create a nomenclature and populate it section for more details.

More About Selection

You need to perform more complex selection? The SimpleElementSelector is based on Jsoup and its powerfull CSS (or jquery) like selector syntax to find matching elements. Have a look to the Jsoup selector-syntax description page to know more about what you can do.

You can use also use one of our selection implementations or even implement your own ones.

More About Check

Based on the implementation of accessiblity rules, many checkers have been implemented and can be reused. Regarding your need, you can use one of our check implementations or even implement your own ones.

More About More

Asqatasun can also make controls on CSS, combine selectors, checkers, use data extracted from a javascript script executing while fetching the page and more, characterise elements by using a marker approach (use the “decorative-image” class to identify all the decoration images of the page). You can browse the Accessiweb 2.2 rules implementations or the RGAA v3.0 rules implementation to get more examples of how to implement a rule.

Want really more? see Create a rule : the framework

Any questions

Let’s discuss Asqatasun