Reference for XML Layout Testing

This page highlights the steps for setting up the library to scan android applications with XML layouts for accessibility issues. For steps to pull in the library, please see Getting Started with the Android SDK.

Automated Testing

Before running Espresso tests, initialize the main entry for the AxeDevTools library.

Initialize the Library

In the test class init, connect to the library with one of the following:

Connect with API key:

Generate an API key at axe.deque.com.

private val axe = AxeDevTools()

init {
     axe.loginWithApiKey(
        "DEQUE_API_KEY"
    )
}

Connect with username and password:

private val axe = AxeDevTools()

init {
    axe.loginWithUsername(
        "DEQUE_USERNAME",
        "DEQUE_PASSWORD"
    )
}

Run a Scan

When you're ready to run a scan from your tests, you'll want to run axe.scan(...). We've included a function below that highlights some additional functionality you may find helpful.

Read about these features and more on the Android Features page. This function is broken down below the snippet.

private fun a11yScan() {
    rule.scenario.onActivity { activity ->
        //1. Scan and receive the ScanResultHandler locally
        val scanResultHandler = axe.scan(activity)

        //2. Upload it to the dashboard
        scanResultHandler?.uploadToDashboard()

        //3. Using the results in your test suite
        val result: AxeResult? = scanResultHandler?.getSerializedResult()
        result?.axeRuleResults?.forEach { result ->
             if(result.status == AxeStatus.PASS) {
        
             }
             else if(result.status == AxeStatus.FAIL) {
        
             }
             else if(result.status == AxeStatus.INCOMPLETE) {
    
             }
         }

        //4. Save the result JSON to a local file for later use
        scanResultHandler?.saveResultToLocalStorage("your_file_prefix")
    }
}

Code snippet breakdown:

1. Call axe.scan(activity) anytime the UI should be scanned. The scan function can be called multiple times within the same test run. The current activity will be scanned for accessibility issues, and a scan result handler will be returned.
2. From the result handler, call uploadToDashboard() to send the most recent scan to the dashboard. The scan will be published from the authenticated account used in the init function.
3. From the result handler, call getSerializedResult() to use results from the library locally. For example, you may choose to fail the test when failures are found in the accessibility scan results. This will not upload your results to the server. Uploading your results is not required to get the results locally.
4. From the result handler, call saveResultToLocalStorage() to save the results as JSON in a local file within your test device. To access the saved file, refer to the feature documentation for Saving Results Locally.

Scan a Dialog

Released with version 3.1.0, axe DevTools for Android now supports scanning dialogs. From your dialogs Dialog.show() method, pass the returned dialog as a parameter to the scan method as well as a callback to handle the scan's result. The callback returns a ScanResultHandler by default so that you may handle the result as you see fit. See the following example:

Kotlin Example:

val dialog = AlertDialog.Builder(requireContext())
    .setTitle("Title")
    .setMessage("Message")
    .show()

MainScope().launch {
    delay(5000)
    axe.scan(dialog) { handler ->
         handler?.uploadToDashboard()
    }
}

When scanning a dialog the scan itself will take place immediately after the dialog has been inflated in automated testing. Note that a scan will only take place if the following are true:

• The user is authenticated
• Espresso tests are running
• The dialog is inflated before the timeout expires

Deinitialize

Once the test has been completed, call tearDown() on the AxeDevTools object you have created to clear the state of previous tests. We recommend putting this in your testing file's tearDown function, but it can also be called within a test if needed.

@After
fun tearDown() {
    axe.tearDown()
}

Example Espresso Test Class for XML

class ExampleInstrumentedTestWithAccessibility : Utils {

    @Rule
    @JvmField
    var rule: ActivityScenarioRule<MainActivity> = ActivityScenarioRule(MainActivity::class.java)

    private val axe = AxeDevTools()

    init {
        //Connect using an API Key
        axe.loginWithApiKey(
            "DEQUE_API_KEY"
        )
    }

    @Before
    fun setup() {
        axe.tagScanAs(setOf("ScanningApp"))
        axe.setTestingConfig(AxeDevToolsEspressoConfig(IdlingRegistry.getInstance()))
    }

    @Test
    fun exampleTest() {
        onView(withText("Active View Name")).perform(click())
        onView(withText("Actionable Button")).perform(click())
        onView(withContentDescription("Share Data")).perform(click())
    }

    @After
    fun runAccessibilityScan() {
        rule.scenario.onActivity {
            val scan = axe.scan(it)
            scan?.uploadToDashboard()
            axe.tearDown()
        }
    }
}

Scan Dialog Espresso Example

class ExampleInstrumentedTestWithAccessibility : Utils {
    private lateinit var countingResource: CountingIdlingResource

    @Before
    fun setTestingConfig() {
        countingResource = CountingIdlingResource("DialogScan")
        IdlingRegistry.getInstance().register(countingResource)
        
        axe.setTestingConfig(AxeDevToolsEspressoConfig(IdlingRegistry.getInstance()))
    }

    @Test
    fun dialogScan() {
        countingResource.increment()

        rule.scenario.onActivity { activity ->
            val dialog = AlertDialog.Builder(activity)
                .setTitle("Title")
                .setMessage("Message")
                .show()

            axe.scan(dialog) { handler ->
                val result = handler?.uploadToDashboard()
                countingResource.decrement()
            }
        }

        while(!countingResource.isIdleNow) { Thread.sleep(100) }
    }

    @After
    fun tearDown() {
        IdlingRegistry.getInstance().unregister(countingResource)
        axe.tearDown()
    }
}

API Reference

loginWithUsername(params)

Generates an auth token to connect to the dashboard.

Required params:

Optional param:

loginWithApiKey(param)

Generates an auth token to connect to the dashboard.

Required param:

Optional param:

disconnect()

Clears the current axe DevTools network session to allow a new connection to be made.

isUserAuthenticated()

Returns a boolean to indicate whether the user is authenticated and ready to send scans.

Returns:

setScanName(param)

Set a name to the scan before uploading it to the dashboard.

Required param:

tagScanAs(param)

Tags a scan before uploading it to the dashboard.

Required param:

addCustomRule(param)

Add a rule to run against your application during scans.

Required param:

resetIgnoredRules()

Clear the ignored Rules list set by the ignored rules APIs. Helpful for changing rule configuration between automated tests.

ignoreRules(param)

Ignores rules completely from being run against any view.

Required param:

ignoreByViewId(param)

Ignores all rules provided for a given viewId.

Required param:

ignoreAllByViewId(param)

Ignores all rules for the provided viewIds.

Required param:

ignoreByView(param)

Ignores all rules provided for a given View.

Required param:

ignoreAllByView(param)

Ignores all rules for the provided View's.

Required param:

ignoreByClassName(param)

Ignores all rules for a given type that extends View.

Required param:

ignoreAllByClassName(param)

Ignores all rules for the provided types, which extend View.

Required param:

tearDown()

Resets tags and clears test state from prior testing.

getResult(param)

Requests a scan's result from the dashboard matching the provided result key.

Required param:

Returns:

deleteResult(param)

Delete a scan's result from the dashboard matching the provided result key.

Required param:

ScanResultHandler

uploadToDashboard(param)

Upload the accessibility scan's result to the dashboard. By default, the full result object is returned.

Optional param:

Returns:

saveResultToLocalStorage(param)

Save the accessibility scan result to a local file on your test device.

Required param:

getSerializedResult()

Grabs the result of your scan to use within the test.

Deprecated

connect(params)

Generates an auth token to connect to the dashboard.

Required params:

Optional param:

connect(param)

Generates an auth token to connect to the dashboard.

Required param:

Optional param:

setTestingConfig(param)

Registers an idling resource for the library.

Required param:

scan(param)

Scans an activity's view for accessibility issues.

Required param:

Returns:

scan(param)

Scans the provided dialog for accessibility issues and returns a callback.

Required param:

Returns: