Note: The following documentation describes the supported API provided by Axe.Windows. There are other, public interfaces and classes in various assemblies throughout the package; however, please be aware that interfaces and classes not described in this document are not supported and may change at any time.
Create the builder for the config for the specified process.
The ForProcessId method accepts the following parameters:
| Name | Type | Description |
|---|---|---|
| processId | int |
The process Id of the application to test. If the value is invalid, the automation session will throw an AxeWindowsAutomationException. |
The ForProcessId method returns a new instance of Config.Builder.
Specify the type(s) of output files you wish AxeWindows to create.
The OutputFileFormat enum currently defines the following values:
| Name | Description |
|---|---|
| None | Create no output files. |
| A11yTest | Create output files which can be opened using Accessibility Insights for Windows. |
The WithOutputFileFormat method accepts the following parameters:
| Name | Type | Description |
|---|---|---|
| format | OutputFileFormat |
The type(s) of output files you wish AxeWindows to create. No output files will be created if this is left unspecified or 0 errors are found. The default value is None. |
The WithOutputFileFormat method returns the Config.Builder configured with the specified format.
Specify the directory where any output files should be written.
The WithOutputDirectory method accepts the following parameters:
| Name | Type | Description |
|---|---|---|
| directory | string |
The directory where any output files should be written; is not used if output file format is None. Output files will be created in the current directory under folder AxeWindowsOutputFiles if left unspecified. |
The WithOutputDirectory method returns the Config.Builder configured with the specified output directory.
Override the default implementation of IDPIAwareness with a caller-specified implementation. The default implementation calls the Win32 SetDPIProcessAware function on Enable, and does nothing on Restore.
The WithDPIAwareness method accepts the following parameters:
| Name | Type | Description |
|---|---|---|
| dpiAwareness | IDPIAwareness |
The caller-provided implementation of IDPIAwareness. |
The WithDPIAwareness method returns the Config.Builder configured to use the specified implementation of IDPIAwareness.
Specify the path to a custom UIA configuration file.
The WithCustomUIAConfig method accepts the following parameters:
| Name | Type | Description |
|---|---|---|
| path | string |
The path to the configuration file. |
The WithCustomUIAConfig method returns the Config.Builder configured with the specified custom UIA configuration file.
Cause each scan to save a test file, even if no errors are reported. The default is to save a test file only is errors are found.
The WithAlwaysSaveTestFile method returns the Config.Builder configured to always save a test file.
Cause all Chromium HTML content to be included in scan results. The default is to omit Chromium HTML content from the scan results. This is intended only for use by browser development teams and should be omitted in other scenarios.
The WithTestAllChromiumContent method returns the Config.Builder configured to include all Chromium HTML content in the scan results..
Build an instance of Config.
The Build method accepts no parameters.
The Build method returns an instance of Config with any modifications made through the Config.Builder.
Create an object that implements IScanner using an instance of Config.
The ScannerFactory.CreateScanner method accepts the following parameters:
| Name | Type | Description |
|---|---|---|
| config | Config |
The configuration used by the returned IScanner object. |
The ScannerFactory.CreateScanner method returns an IScanner object.
The ScanAsync method asynchronously runs AxeWindows automated tests using the config provided at the time of creation of the scanner. This method should be awaited.
IScanner.ScanAsync accepts two parameters:
| Name | Type | Description |
|---|---|---|
scanOptions |
ScanOptions |
An object describing custom settings for this scan. Pass null for default options. |
cancellationToken |
CancellationToken |
A cancellation token. |
ScanAsync returns a ScanOutput object.
The Scan method synchronously runs AxeWindows automated tests using the config provided at the time of creation of the scanner, and blocks until the scan is complete.
IScanner.Scan accepts one parameter:
| Name | Type | Description |
|---|---|---|
scanOptions |
ScanOptions |
An object describing custom settings for this scan. Pass null for default options. |
Scan returns a ScanOutput object.
The ScanOptions constructor accepts the following arguments:
| Name | Type | Description | Default value |
|---|---|---|---|
| scanId | string |
A string identifier for the scan. If the scan produces output files based on the Config object used to create the scanner, the output files will be given the name of the scan id (e.g., MyScanId.a11ytest). |
null |
| scanRootWindowHandle | IntPtr |
The native window handle (HWND) of the UIA element whose sub-tree should be scanned. If not specified or no element matches the HWND, the process's full UIA tree will be scanned. | null |
Methods of IScanner return a ScanOutput object with the following properties:
| Name | Type | Description |
|---|---|---|
WindowScanOutputs |
IReadOnlyCollection<WindowScanOutput> |
The set of WindowScanOutput objects produced by this scan, one per top-level application window. |
A WindowScanOutput object contains the results of scanning one top level window and has the following properties:
| Name | Type | Description |
|---|---|---|
| ErrorCount | int |
A count of all errors across all elements scanned. |
| Errors | IEnumerable<ScanResult> |
A collection of errors found during the scan. |
| OutputFile | OutputFile |
Represents the output file(s), if any, associated with a WindowScanOutput object. |
The Errors property contains ScanResult objects which are the result of a single rule test on a single element and have the following properties:
| Name | Type | Description |
|---|---|---|
| Rule | RuleInfo |
Information about the rule (description, how to fix information, etc.) that was evaluated on the element. |
| Element | ElementInfo |
The element which was tested against the rule. |
RuleInfo contains the following properties:
| Name | Type | Description |
|---|---|---|
| ID | RuleId |
Contains a unique identifier for the rule from the RuleId enumeration. |
| Description | string |
Contains a short description of the rule. |
| HowToFix | string |
Detailed information on how to resolve a violation reported by the rule. |
| Standard | A11yCriteriaId |
The A11yCriteriaId enumeration identifies the standards documentation from which the rule was derived. |
| PropertyID | int |
In cases where the rule tests one specific UI Automation property, this contains the UI Automation property ID in question. This property is used to link elements with rule violations to relevant documentation. |
| Condition | string |
A description of the conditions under which a rule will be evaluated. |
ElementInfo contains the following properties:
| Name | Type | Description |
|---|---|---|
| Properties | Dictionary<string, string> |
A string to string dictionary where the key is a UI Automation property name and the value is the corresponding UI Automation property value. |
| Patterns | IEnumerable<string> |
A list of names of supported patterns. |
The OutputFile property is a struct with the following properties:
| Name | Type | Description |
|---|---|---|
| A11yTest | string |
The path to the A11yTest file that was generated (or null if no file was generated). |
| Sarif | string |
The path to the Sarif file that was generated (or null if no file was generated). |
UIA operates in physical screen coordinates, so DPI awareness must be enabled while scanning. Methods on this interface will be called in pairs on each call to IScanner's methods. Each successful call to Enable will have a corresponding call to Restore.
Enable DPI awareness for the scan.
The Enable method accepts no parameters
The return object from Enable is passed as a parameter to the Restore method. It allows calls to Enable and Restore to be easily associated and is not used by Axe.Windows.
If Enable throws an Exception, then Axe.Windows will not call the Restore method. Any required cleanup becomes the responsibility of the Exception handler inside the implementation of Enable.
Restore DPI awareness to its non-scanning state.
The Restore method accepts 1 parameter
| Name | Type | Description |
|---|---|---|
| dataFromEnable | object |
This is the data returned from the Enable method. It allows calls to Enable and Restore to be easily associated. |
The return object from Enable is passed as a parameter to the Restore method. It is not used by Axe.Windows.
You can get the files via a NuGet package; configure NuGet to retrieve the Axe.Windows package from https://api.nuget.org/v3/index.json, then use the classes in the Axe.Windows.Automation namespace (see example below):
- Prerequisite: Your project must be able to use .NET Standard 2.0 libraries.
- If you’re using NuGet, add the appropriate feed to your project.
- Add using Axe.Windows.Automation; to your code.
- Invoke Axe.Windows similar to the example below.
using System;
using System.Collections.Generic;
using System.Threading;
using System.Threading.Tasks;
using Axe.Windows.Automation;
namespace AxeWindowsDemo
{
class Program
{
/// <summary>
/// This is a quick and easy demo of the automation code
/// </summary>
static async Task Main(string[] args)
{
string testAppPath = Path.GetFullPath(@"..\myApplication.exe");
string outputDir = Path.GetFullPath(@".\TestOutput");
Process testProcess = Process.Start(testAppPath);
var config = Config.Builder.ForProcessId(testProcess.Id)
.WithOutputFileFormat(OutputFileFormat.A11yTest)
.WithOutputDirectory(outputDir)
.Build();
var scanner = ScannerFactory.CreateScanner(config);
try
{
var output = await scanner.ScanAsync(null, CancellationToken.None);
foreach (var window in output.WindowScanOutputs)
Assert.AreEqual(0, window.ErrorCount);
}
catch(Exception e)
{
var errorMessage = e.toString();
Assert.Fail(errorMessage);
}
}
}
}There may be occasions where you want to debug assemblies within the Axe.Windows NuGet package that your process is consuming. The specific steps depend on the version of Axe.Windows that you are using.
These versions require you to access the symbols from the NuGet symbol server for debugging. The steps to enable debugging are:
- In Visual Studio, go to Tools > Options > Debugging > General and uncheck "Enable Just My Code".
- In Visual Studio, go to Tools > Options > Debugging > Symbols and check "NuGet.org Symbol Server". This tells Visual Studio to attempt to download symbols for NuGet packages. (Note that this download will occur on the first app boot after the setting is enabled or after a version changes, so you may experience a delay in loading the app after making this change).
- You will need to have a local copy of the sources at the same commit as the release (one easy to do this is to download the source code zip file from the corresponding release). When Visual Studio needs the sources, it will prompt for the location of the source code.
- Run and debug as usual.
These versions embed the symbols into the assemblies and support SourceLink to easily obtain the source code at the correct commit. The steps to enable debugging are:
- In Visual Studio, go to Tools > Options > Debugging > General and uncheck "Enable Just My Code".
- In Visual Studio, go to Tools > Options > Debugging > General and check "Enable Source Link support". When Visual Studio needs the sources, it will ask for permission to retrieve them, then it will cache a local copy for future use.
- Run and debug as usual.
AxeWindowsAutomationException is thrown for errors in Axe.Windows.Automation's logic where meaningful error reporting can be generated. In some situations, the Exception.InnerException property may contain a corresponding system-level exception for errors encountered by Axe.Windows. Other exceptions may be thrown by the system from calls to this library.
If a CancellationToken is provided to the library which is later cancelled, the original task will throw an AggregateException containing a TaskCancelledException.
Migration from Axe.Windows 1.x to Axe.Windows 2.0 should require minimal code changes for most projects.
The ScanAll method for scanning multiple top-level windows has been removed. Use ScanAsync or Scan instead.
| In place of this | Do this |
|---|---|
IScanner.Scan() |
IScanner.Scan(null) |
IScanner.Scan("scanId") |
IScanner.Scan(new ScanOptions(scanId: "scanId")) |
The new return type of IScanner's methods is ScanOutput. This object contains a WindowScanOutputs field, a IReadOnlyCollection of WindowScanOutput objects. These objects contain the same fields as the previous ScanResults class.
| In place of this | Do this |
|---|---|
IScanner.Scan().ErrorCount |
IScanner.Scan(null).WindowScanOutputs.First().ErrorCount |
foreach (ScanResults item in IScanner.ScanAll()) |
foreach (WindowScanOutput item in IScanner.Scan(null).WindowScanOutputs) |