API-Referenz für Hamcrest

Referenz für die von dem hamcrest Paket bereitgestellten Typen.

Die Klassen IsAccessible und IsAuditedForAccessibility bieten die Hauptfunktionalität. Sie erhalten eine Instanz von einer der beiden über ihre statische Fabrikmethode, isAxeClean() oder isAuditedForAccessibility(), und hängen dann die AxeDevtoolsMatcher-Methoden an, um die Prüfung zu konfigurieren.

Die Beispiele auf dieser Seite nehmen an, dass webDriver Ihr Selenium WebDriver ist, driver ein AxeDriver, der es umschließt, und diese statischen Importe. Die Selektorklassen stammen aus com.deque.html.axedevtools.matchers.selectors, und AxeReportingOptions von com.deque.html.axedevtools.selenium.reporter.

import static org.hamcrest.MatcherAssert.assertThat;
import static com.deque.html.axedevtools.matchers.IsAccessible.isAxeClean;
import static com.deque.html.axedevtools.matchers.IsAuditedForAccessibility.isAuditedForAccessibility;

com.deque.html.axedevtools.matchers.AxeDevtoolsMatcher

Die Basisklasse der Axe DevTools-Matcher. Sie erweitert Hamcrests TypeSafeMatcher<AxeDriver>, sodass sie mit einem AxeDriver übereinstimmt. Sie erstellen keine direkt: Verwenden Sie IsAccessible oder IsAuditedForAccessibility, die alle unten aufgeführten Methoden erben.

Jede Konfigurationsmethode gibt denselben Matcher zurück, sodass Aufrufe verkettet werden können. Der Scan selbst wird ausgeführt, wenn assertThat den Matcher auswertet. Im Hintergrund führt jeder Matcher einen AxeSelenium-Scan durch, sodass die dort beschriebenen Regeln für die Kombination von Optionen auch hier gelten.

within(String...)

Begrenzt den Scan auf die Elemente, die von den angegebenen CSS-Selektoren und deren Nachkommen übereinstimmen. Jeder Selektor fügt dem Scan einen separaten Bereich hinzu, sodass within("#header", "#footer") beide testet, genau wie ein einzelner Aufruf von within für jeden Selektor. Dies unterscheidet sich von AxeSelenium.include(Object...), wo mehrere Argumente einen Pfad bilden.

public AxeDevtoolsMatcher within(String... cssSelectors);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().within("#header", "#footer"));

within(Selector...)

Begrenzt den Scan auf die Bereiche, die von Selector-Objekten beschrieben werden. Verwenden Sie es mit IFrameSelector, um ein Element innerhalb eines iFrames zu testen. Jeder Selektor fügt dem Scan einen separaten Bereich hinzu.

public AxeDevtoolsMatcher within(Selector... selectors);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

// Test the form inside the #payment-frame iframe
assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));

within(Object...)

Begrenzt den Scan auf Bereiche, die durch andere Selektorobjekte beschrieben werden, am nützlichsten FromFrames und FromShadowDom. Verwenden Sie es, um ein Element innerhalb eines Schatten-DOM-Baums zu testen, den Selector-Objekte nicht ausdrücken können. Jedes Argument fügt dem Scan einen separaten Bereich hinzu.

public AxeDevtoolsMatcher within(Object... selectors);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

// Test the #search form inside the shadow root attached to .app-header
assertThat(driver, isAxeClean().within(new FromShadowDom(".app-header", "form#search")));

excluding(String...)

Entfernt die von den angegebenen CSS-Selektoren und deren Nachkommen übereinstimmenden Elemente aus dem Scan. Jeder Selektor entfernt einen separaten Bereich. Ausschlüsse gelten zusätzlich zu allen within-Aufrufen, was es Ihnen ermöglicht, einen Bereich zu testen, mit Ausnahme eines Teils davon.

public AxeDevtoolsMatcher excluding(String... cssSelectors);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

// Test main, but skip the .cookie-banner and .ad-slot inside it
assertThat(driver, isAxeClean().within("main").excluding(".cookie-banner", ".ad-slot"));

excluding(Selector...)

Entfernt die von Selector-Objekten beschriebenen Bereiche aus dem Scan, wie zum Beispiel ein Element innerhalb eines iFrames. Jeder Selektor entfernt einen separaten Bereich.

public AxeDevtoolsMatcher excluding(Selector... selectors);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

// Skip the third-party ad inside the #ad-frame iframe
assertThat(driver, isAxeClean().excluding(new IFrameSelector("#ad-frame", ".ad")));

excluding(Object...)

Entfernt Bereiche, die durch andere Selektorobjekte beschrieben werden, am nützlichsten FromFrames und FromShadowDom, aus dem Scan. Jedes Argument entfernt einen separaten Bereich.

public AxeDevtoolsMatcher excluding(Object... selectors);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

// Skip the chat widget inside the shadow root attached to support-chat
assertThat(driver, isAxeClean().excluding(new FromShadowDom("support-chat", ".widget")));

accordingTo(String...)

Führt nur die Regeln aus, die mindestens eines der angegebenen Tags tragen, wie wcag2a oder best-practice.

accordingTo und checkingOnly setzen dieselbe Option, sodass nur der letzte der beiden Aufrufe wirksam wird. Ein zweiter accordingTo-Aufruf ersetzt auch die Tags des ersten, daher übergeben Sie alle Tags in einem Aufruf.

public AxeDevtoolsMatcher accordingTo(String... tags);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().accordingTo("wcag2a", "wcag2aa"));

checkingOnly(String...)

Führt nur die benannten Regeln aus und keine anderen.

checkingOnly und accordingTo setzen dieselbe Option, sodass nur der letzte der beiden Aufrufe wirksam wird. Ein zweiter checkingOnly-Aufruf ersetzt auch die Regeln des ersten, daher übergeben Sie alle Regel-IDs in einem Aufruf.

public AxeDevtoolsMatcher checkingOnly(String... rules);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().checkingOnly("label", "color-contrast"));

checking(String...)

Aktiviert die benannten Regeln zusätzlich zu den durch das Regelset oder durch accordingTo bereits ausgewählten Regeln.

checking und skipping setzen dieselbe Option, sodass nur der letzte der beiden Aufrufe wirksam wird, und ein zweiter checking-Aufruf ersetzt die Regeln des ersten. Übergeben Sie alle Regel-IDs in einem Aufruf und kombinieren Sie nicht checking mit skipping in derselben Prüfung.

public AxeDevtoolsMatcher checking(String... rules);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

// WCAG 2.0 Level A rules, plus the tabindex best-practice rule
assertThat(driver, isAxeClean().accordingTo("wcag2a").checking("tabindex"));

skipping(String...)

Deaktiviert die benannten Regeln, wobei der Rest des ausgewählten Regelsets oder der Tags bestehen bleibt.

skipping und checking setzen dieselbe Option, sodass nur der letzte der beiden Aufrufe wirksam wird, und ein zweiter skipping-Aufruf ersetzt die Regeln des ersten. Übergeben Sie alle Regel-IDs in einem Aufruf und kombinieren Sie nicht skipping mit checking in derselben Prüfung.

public AxeDevtoolsMatcher skipping(String... rules);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().skipping("color-contrast", "image-alt"));

ignoring(String, String)

Entfernt Verstöße gegen eine Regel aus den Ergebnissen, wenn diese Regel bei einem bestimmten Element fehlschlägt, sodass sie die Assertion nicht fehlschlagen lassen. Der Selektor muss genau mit dem target des Elements in den Ergebnissen übereinstimmen, in der Form "[#sidebar]".

Das Filtern funktioniert auf ganzen Regeln: Wenn ein Element, das die Regel nicht erfüllt, mit dem Selektor übereinstimmt, wird der gesamte Eintrag der Regel entfernt, einschließlich der Fehler bei anderen Elementen. Ein Anruf pro Regel reicht aus; zwei Anrufe für dieselbe Regel, die beide übereinstimmen, werfen eine IllegalStateException. Siehe AxeSelenium.ignoring(String, String) für Details.

public AxeDevtoolsMatcher ignoring(String selector, String ruleId);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().ignoring("[#sidebar]", "color-contrast"));

forConfig(URL)

Wählt die Audit-Suite (eine JSON-Regel-Konfigurationsdatei) zum Überprüfen aus, nach URL. Wie AxeSelenium.forConfig(URL) setzt dies die globale Audit-Suite, sodass sie auch für spätere Prüfungen gilt.

public AxeDevtoolsMatcher forConfig(URL auditPath);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

URL auditSuite = getClass().getResource("/config/my-audit-suite.json");
assertThat(driver, isAxeClean().forConfig(auditSuite));

forConfig(String)

Wählt die Audit-Suite aus, die anhand ihres Pfads im Dateisystem zu überprüfen ist. Wie forConfig(URL) setzt sie die globale Audit-Suite.

public AxeDevtoolsMatcher forConfig(String auditPath) throws MalformedURLException;

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Löst aus

MalformedURLException, wenn der Pfad nicht in eine URL umgewandelt werden kann.

Beispiel

@Test
public void matchesAuditSuite() throws MalformedURLException {
    assertThat(driver, isAxeClean().forConfig("/opt/axe/my-audit-suite.json"));
}

forRuleset(String)

Wählt das Regelset zum Überprüfen aus, wie wcag2.2 oder 508, mit ausgeschalteten Best-Practice-Regeln. Die Übergabe von null wählt das Standard-wcag2.1. Wie AxeSelenium.forRuleset(String) setzt dies das globale Regelset, sodass es auch für spätere Prüfungen gilt. Siehe AxeConfiguration.forRuleset(String) für die Regelset-IDs.

Die Matcher haben keine Möglichkeit, Best-Practice-Regeln zusammen mit einem Regelset einzuschalten. Um dies zu tun, rufen Sie AxeConfiguration.configure().forRuleset(rulesetId, true) vor der Prüfung auf und rufen Sie nicht auch den forRuleset des Matchers auf, was die Best-Practice-Regeln wieder ausschaltet.

public AxeDevtoolsMatcher forRuleset(String rulesetId);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().forRuleset("wcag2.2"));

logResults(AxeReportingOptions)

Erstellt einen Bericht dieser Prüfung: eine .log-Datei, die die Verstöße auflistet, und eine .json-Datei mit den vollständigen Ergebnissen. Die Dateinamen und der Speicherort stammen von reportingOptions; siehe AxeReportingOptions. Mit isAxeClean() wird kein Bericht geschrieben, es sei denn, Sie rufen logResults auf.

Wenn reportingOptions keine Zeilennummer gesetzt hat, zeichnet Axe DevTools die Zeile Ihres Tests auf, der logResults aufgerufen hat.

public AxeDevtoolsMatcher logResults(AxeReportingOptions reportingOptions);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

AxeReportingOptions options = new AxeReportingOptions()
    .testSuiteName("checkout")
    .uiState("page-loaded");

assertThat(driver, isAxeClean().logResults(options));

setReportingOptions(AxeReportingOptions)

Ersetzt die Berichtsoptionen, die isAuditedForAccessibility() verwendet, wenn Sie logResults nicht aufrufen. Es hat keine Auswirkungen auf isAxeClean(), die nur durch logResults einen Bericht schreibt. Die übergebenen Optionen ersetzen die Standardwerte vollständig: Jeder Wert, den Sie nicht setzen, fällt auf AxeConfiguration zurück (Berichte gehen zu axe-reports, es sei denn, Sie setzen outputDirectory), und Sie müssen uiState setzen.

public AxeDevtoolsMatcher setReportingOptions(AxeReportingOptions reportingOptions);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAuditedForAccessibility()
    .setReportingOptions(new AxeReportingOptions().testSuiteName("nightly").uiState("home")));

setTimeout(int)

Legt fest, wie lange axe-core in Sekunden die Seite analysieren darf, bevor die Prüfung mit einem Timeout fehlschlägt. Standardmäßig sind es 30 Sekunden.

public AxeDevtoolsMatcher setTimeout(int timeout);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().setTimeout(120));

enableAnalytics(boolean)

Schaltet den Nutzungsdienst für diese Prüfung ein oder aus. Der Nutzungsdienst ist standardmäßig eingeschaltet. Wenn die Umgebungsvariable AXE_TRACK_USAGE gesetzt ist, hat sie Vorrang und diese Methode hat keine Wirkung: true schaltet den Dienst ein und jeder andere Wert schaltet ihn aus.

public AxeDevtoolsMatcher enableAnalytics(boolean state);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().enableAnalytics(false));

trackingEnabled()

Berichtet, ob diese Prüfung Nutzungsdaten sendet.

public boolean trackingEnabled();

Rückgaben

true, wenn der Nutzungsdienst eingeschaltet ist.

setAnalyticsUrl(String)

Legt die URL fest, an die Nutzungsdaten gesendet werden. Standardmäßig ist dies die Umgebungsvariable AXE_METRICS_URL, oder https://usage.deque.com, wenn diese nicht gesetzt ist. Wenn AXE_METRICS_URL gesetzt ist, hat diese Methode keine Wirkung.

public AxeDevtoolsMatcher setAnalyticsUrl(String url);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().setAnalyticsUrl("https://usage.example.com"));

setAnalyticsDisinctId(String)

Legt die eindeutige ID fest, die mit Nutzungsdaten gesendet wird. Der Methodenname wird im API als Disinct geschrieben, daher bitte genau so eingeben. Die ID wird in ~/.deque/distinct_id gespeichert, sodass spätere Ausführungen auf der gleichen Maschine diese weiter nutzen. Wenn die ID aus der Umgebungsvariable AXE_DISTINCT_ID stammt, hat diese Methode keine Wirkung.

public AxeDevtoolsMatcher setAnalyticsDisinctId(String id);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean().setAnalyticsDisinctId("build-agent-7"));

setAnalyticsComponentName(String)

Legt den Projektnamen fest, der mit Nutzungsdaten gesendet wird. Dies setzt auch alle vorherigen setAnalyticsUrl und enableAnalytics Aufrufe an diesem Matcher auf ihre Standardwerte zurück, daher sollten Sie dies vor diesen Methoden aufrufen. Eine mit setAnalyticsDisinctId gesetzte eindeutige ID bleibt erhalten.

public AxeDevtoolsMatcher setAnalyticsComponentName(String name);

Parameter

Rückgaben

Dieser Matcher, zur Methodenkette.

Beispiel

assertThat(driver, isAxeClean()
    .setAnalyticsComponentName("storefront-tests")
    .setAnalyticsDisinctId("build-agent-7"));

com.deque.html.axedevtools.matchers.IsAccessible

Ein Matcher, der die Assertion zum Scheitern bringt, wenn die Seite Zugänglichkeitsprobleme aufweist. Er erweitert AxeDevtoolsMatcher, sodass jede oben stehende Methode daran angehängt werden kann, um den Umfang, die Regeln, die Prüfungs-Suite und das Reporting festzulegen.

Wenn die Assertion fehlschlägt, listet die Fehlermeldung jede Verletzung, die betroffenen Elemente und deren Behebung auf, im gleichen Format wie der .log Bericht. Wenn axe-core einen Fehler anstelle von Ergebnissen zurückgibt, wird der Check eine AxeRuntimeException auslösen, anstatt die Assertion scheitern zu lassen.

assertThat(driver, isAxeClean()
    .within("#header")
    .within("#footer")
    .excluding(".graphics")
    .accordingTo("wcag2a", "wcag2aa"));

isAxeClean()

Erstellt einen IsAccessible Matcher. Diese statische Methode ist der einzige Weg, um einen zu erhalten. Ohne weitere Konfiguration überprüft er die gesamte Seite anhand des globalen Regelwerks, das standardmäßig auf wcag2.1 gesetzt ist, und schreibt keinen Bericht.

public static IsAccessible isAxeClean();

Rückgaben

Ein neuer IsAccessible Matcher.

Beispiel

@Test
public void homePageIsAccessible() {
    webDriver.get("https://example.com");
    assertThat(driver, isAxeClean());
}

com.deque.html.axedevtools.matchers.IsAuditedForAccessibility

Ein Matcher, der die Seite scannt und einen Bericht erstellt, jedoch nie die Assertion aufgrund von Verstößen scheitern lässt. Ein axe-core Fehler löst jedoch weiterhin einen AxeRuntimeException aus, ebenso wie isAxeClean(). Verwenden Sie ihn, um Ergebnisse für die Überwachung zu sammeln, ohne den Build zu unterbrechen; Sie müssen Regressionen aus den Berichten verfolgen, außerhalb von Testdurchläufen und -fehlern. Er erweitert AxeDevtoolsMatcher, sodass jede oben stehende Methode daran angehängt werden kann.

Wenn Sie nicht logResults aufrufen, wird der Bericht an target/axe-report/accessibility-check.log und target/axe-report/accessibility-check.json geschrieben. Verwenden Sie setReportingOptions, um diese Standardwerte zu ändern. Jeder Check überschreibt den vorherigen Bericht am gleichen Pfad, daher sollten Sie jedem Check einen eigenen Test-Suite-Namen oder UI-Zustand über setReportingOptions oder logResults geben oder useUniqueFilename einschalten.

assertThat(driver, isAuditedForAccessibility()
    .within("#header")
    .within("#footer")
    .excluding(".graphics")
    .accordingTo("wcag2a", "wcag2aa"));

isAuditedForAccessibility()

Erstellt einen IsAuditedForAccessibility Matcher. Diese statische Methode ist der einzige Weg, um einen zu erhalten.

public static IsAuditedForAccessibility isAuditedForAccessibility();

Rückgaben

Ein neuer IsAuditedForAccessibility Matcher.

Beispiel

@Test
public void auditCheckoutPage() {
    webDriver.get("https://example.com/checkout");
    assertThat(driver, isAuditedForAccessibility()
        .logResults(new AxeReportingOptions().testSuiteName("checkout").uiState("loaded")));
}

com.deque.html.axedevtools.matchers.selectors.Selector

Das Interface, implementiert von ElementSelector und IFrameSelector. Übergeben Sie Selektoren an within(Selector...) oder excluding(Selector...).

toList()

Gibt den Selektor als Liste von CSS-Selektoren zurück: einen pro iFrame-Ebene, gefolgt vom Selektor für das Element. Beide Implementierungen bieten dies. Die Matcher rufen es für Sie auf; Sie müssen ihn nicht in Tests aufrufen.

List<String> toList();

Rückgaben

Die CSS-Selektoren, als List\<String>.

com.deque.html.axedevtools.matchers.selectors.ElementSelector

Ein Selector für ein Element im aktuellen Dokument. Für sich genommen ist es äquivalent zur Übergabe des CSS-Selektor-Strings an within oder excluding; der Hauptnutzen liegt in der Verwendung als innerster Teil eines IFrameSelector.

ElementSelector(String)

Erstellt einen Selektor für die Elemente, die von einem CSS-Selektor erfasst werden.

public ElementSelector(String cssSelector);

Parameter

Beispiel

// The form inside #inner-frame, which is inside #outer-frame
Selector form = new IFrameSelector("#outer-frame",
    new IFrameSelector("#inner-frame", new ElementSelector("form")));

com.deque.html.axedevtools.matchers.selectors.IFrameSelector

Ein Selector für ein Element innerhalb eines iFrame. Verschachteln Sie einen IFrameSelector in einen anderen, um ein Element innerhalb verschachtelter iFrames zu erreichen.

IFrameSelector(String, String)

Erstellt einen Selektor für ein Element innerhalb eines iFrame.

public IFrameSelector(String frameSelector, String cssSelector);

Parameter

Beispiel

assertThat(driver, isAxeClean().within(new IFrameSelector("#payment-frame", "form")));

IFrameSelector(String, Selector)

Erstellt einen Selektor für ein Element innerhalb eines iFrame, wobei das Element durch einen anderen Selector beschrieben wird. Übergeben Sie einen anderen IFrameSelector, um ein iFrame tiefer zu gehen, oder einen ElementSelector.

public IFrameSelector(String frameSelector, Selector selector);

Parameter

Beispiel

// The form inside #inner-frame, which is inside #outer-frame
assertThat(driver, isAxeClean().within(
    new IFrameSelector("#outer-frame", new IFrameSelector("#inner-frame", "form"))));