Deque.AxeCore.Playwright
4.7.2-alpha.58
Prefix Reserved
See the version list below for details.
dotnet add package Deque.AxeCore.Playwright --version 4.7.2-alpha.58
NuGet\Install-Package Deque.AxeCore.Playwright -Version 4.7.2-alpha.58
<PackageReference Include="Deque.AxeCore.Playwright" Version="4.7.2-alpha.58" />
paket add Deque.AxeCore.Playwright --version 4.7.2-alpha.58
#r "nuget: Deque.AxeCore.Playwright, 4.7.2-alpha.58"
// Install Deque.AxeCore.Playwright as a Cake Addin #addin nuget:?package=Deque.AxeCore.Playwright&version=4.7.2-alpha.58&prerelease // Install Deque.AxeCore.Playwright as a Cake Tool #tool nuget:?package=Deque.AxeCore.Playwright&version=4.7.2-alpha.58&prerelease
Deque.AxeCore.Playwright
Automated web accessibility testing with .NET, C#, and Playwright. Wraps the axe-core accessibility scanning engine and the Playwright browser automation framework.
Compatible with .NET Standard 2.1.
Getting Started
Install via NuGet:
PM> Install-Package Deque.AxeCore.Playwright
# or, use the Visual Studio "Manage NuGet Packages" UI
Ensure you have Playwright browsers installed. For reference, see https://playwright.dev/dotnet/docs/browsers
Example usage with Playwright's NUnit integration:
using System.Threading.Tasks;
using NUnit.Framework;
using Microsoft.Playwright.NUnit;
using Deque.AxeCore.Commons;
using Deque.AxeCore.Playwright;
[TestFixture]
class MyPlaywrightTests : PageTest
{
[Test]
public async Task CheckAxeClean()
{
const string expectedViolationId = "color-contrast";
await Page!.GotoAsync("https://playwright.dev/dotnet");
AxeResult axeResults = await Page!.RunAxe();
Assert.That(axeResults.Violations, Is.Null.Or.Empty);
}
}
API Reference
This library essentially wraps the axe-core library. Currently the two supported functions are for rule retrieval and for running.
GetAxeRules
This method retrieves metadata about the rules that axe is capable of running.
IList<AxeRuleMetadata> axeRules = await page.GetAxeRules();
foreach(var rule in axeRules)
{
Console.WriteLine($"Rule name: {rule.RuleId} Help: {rule.Help} HelpUrl: {rule.HelpUrl}");
Console.WriteLine($"Tags: {string.Join(", ", rule.Tags)}");
}
It is also possible to run this only selecting for rules with particular tags. Tags are considered in a disjunctive fashion.
// Only take rules which are wcag2aa or wcag2a.
IList<string> tags = new List<string>() { "wcag2aa", "wcag2a"}
IList<AxeRuleMetadata> axeRules = await page.GetAxeRules(tags);
foreach(var rule in axeRules)
{
Console.WriteLine($"Rule name: {rule.RuleId} Help: {rule.Help} HelpUrl: {rule.HelpUrl}");
Console.WriteLine($"Tags: {string.Join(", ", rule.Tags)}");
}
RunAxe
This method executes the axe run method, which will run rules against the current state of the page.
AxeResults axeResults = await page.RunAxe();
Console.WriteLine($"Axe ran against {axeResults.Url} on {axeResults.Timestamp}.");
Console.WriteLine($"Rules that failed:");
foreach(var violation in axeResults.Violations)
{
Console.WriteLine($"Rule Id: {violation.Id} Impact: {violation.Impact} HelpUrl: {violation.HelpUrl}.");
foreach(var node in violation.Nodes)
{
Console.WriteLine($"\tViolation found in Html: {node.Html}.");
foreach(var target in node.Target)
{
Console.WriteLine($"\t\t{target}.");
}
}
}
Console.WriteLine($"Rules that passed successfully:");
foreach(var pass in axeResults.Passes)
{
Console.WriteLine($"Rule Id: {pass.Id} Impact: {pass.Impact} HelpUrl: {pass.HelpUrl}.");
}
Console.WriteLine($"Rules that did not fully run:");
foreach(var incomplete in axeResults.Incomplete)
{
Console.WriteLine($"Rule Id: {incomplete.Id}.");
}
Console.WriteLine($"Rules that were not applicable:");
foreach(var inapplicable in axeResults.Inapplicable)
{
Console.WriteLine($"Rule Id: {inapplicable.Id}.");
}
This method can be run on an element via the context parameter. This allows the inclusion and exclusion of string selectors. When exclude is only specified, include will default to the entire document. Currently the node and node lists functionality are not supported.
AxeRunContext runContext = new AxeRunSerialContext("#my-id"); // Only run on this id.
runContext = new AxeRunSerialContext(null, "#my-id"); // Run on everything but this id.
runContext = new AxeRunSerialContext("button", "#my-id"); // Run on every button that does not have this id.
runContext = new AxeRunSerialContext(new List<string>()
{
new List<string>()
{
"#my-frame",
"#my-id"
}
}); // Run on the element with my-id Id and which is inside the frame with id my-frame.
AxeResults axeResults = await page.RunAxe(runContext);
The run method can also be run on a Playwright Locator. This does not support context parameter.
ILocator locator = page.Locator("text=Sign In");
AxeResults axeResults = await locator.RunAxe();
All these run methods support an AxeRunOptions parameter. This is roughly the equivalent of axe options .
AxeRunOptions options = new AxeRunOptions(
// Run only tags that are wcag2aa.
runOnly: new AxeRunOnly(AxeRunOnlyType.Tag, new List<string> { "wcag2aa" }),
// Specify rules.
rules: new Dictionary<string, AxeRuleObjectValue>()
{
// Don't run color-contrast.
{"color-contrast", new AxeRuleObjectValue(false)}
},
// Limit result types to Violations.
resultTypes: new List<AxeResultGroup>()
{
AxeResultGroup.Violations
},
// Don't return css selectors in results.
selectors: false,
// Return CSS selector for elements, with all the element's ancestors.
ancestry: true,
// Don't return xpath selectors for elements.
xpath: false,
// Don't run axe on iframes inside the document.
iframes: false
);
AxeResults axeResults = await page.RunAxe(options);
axeResults = await page.RunAxe(context, options);
axeResults = await locator.RunAxe(options);
RunAxeLegacy
Set the frame testing method to "legacy mode". In this mode, axe will not open a blank page in which to aggregate its results. This can be used in an environment where opening a blank page causes issues.
With legacy mode turned on, axe will fall back to its test solution prior to the 4.3 release, but with cross-origin frame testing disabled. The frame-tested rule will report which frames were untested.
Important: Use of .RunAxeLegacy()
is a last resort. If you find there is no other solution, please report this as an issue. It will be removed in a future release.
AxeResults axeResults = await page.RunAxeLegacy();
Migrating from Playwright.Axe
(PlaywrightAxeDotnet)
This project acts as a drop-in replacement for most of the functionality from Playwright.Axe
. (PlaywrightAxeDotnet). To migrate:
- Update your test
.csproj
file's<PackageReference>
forPlaywright.Axe
toDeque.AxeCore.Playwright
- Add a new
<PackageReference>
toDeque.AxeCore.Commons
at the same version number asDeque.AxeCore.Playwright
- Update all
using Playwright.Axe;
statements in your tests tousing Deque.AxeCore.Playwright;
and/orusing Deque.AxeCore.Commons;
In a move to standardize, we migrated this package away from Playwright specific typings, instead opting to use the typings from the Deque.AxeCore.Commons
package instead. The result is several minor breaking changes that may require updates to your code:
Replacements/Renamings
AxeResults
has now been renamed toAxeResult
; the previously usedAxeResult
for this package will now beAxeResultItem
.AxeNodeResult
has been replaced withAxeResultNode
AxeCheckResult
has been replaced withAxeResultCheck
AxeRelatedNode
has been replaced withAxeResultRelatedNode
AxeResultGroup
has been replaced withResultType
AxeRuleObjectValue
has been replaced withRuleOptions
AxeRunOnly
has been replaced withRunOnlyOptions
AxeResultRelatedNode
is now used in lieu ofAxeRelatedNode
. With this type, the Targets property is changed from aIList<string>
to aList<AxeResultTarget>
; users should expect to modify usages of the Targets property to include a.ToString()
method call.AxeRunSerialContext
has been replaced byAxeRunContext
andAxeSelector
types. Here are some examples of how to use the new types:```cs //finding a single element using the Playwright Locator API ILocator locator = page.GetByRole("menu").RunAxe(); //including/excluding elements in the main frame new AxeRunContext() { Include = new List<AxeSelector> { new AxeSelector("#foo") }, Exclude = new List<AxeSelector> {}, }; //including/excluding an element in a child frame new AxeRunContext() { Include = new List<AxeSelector> { new AxeSelector("#element-in-child-frame", new List<string> { "#iframe-in-main-frame" })}, Exclude = new List<AxeSelector> {}, }; ```
Type Modifications
- The Timestamp type in
AxeResult
changed from System.DateTime to System.DateTimeOffset - The url type in
AxeResult
changed from Uri to string - The
OrientationAngle
type inAxeTestEnvironment
changed from int to double - The
HelpUrl
inAxeResultItem
changed from Uri to string
Removals
- Removed
AxeEnvironmentData
interface and using the existing environment data info inDeque.AxeCore.Commons.AxeResult
- Removed
AxeImpactValue
andAxeRunOnlyType
enums in favor of usingstring
in the Commons typings (AxeResultItem.cs
andAxeRunOptions.cs
, respectively) FailureSummary
was removed fromAxeResultNode
(formerlyAxeNodeResult
)ElementRef
andPerformanceTimer
were removed fromAxeRunOptions
Contributing
Refer to the general axe-core-nuget CONTRIBUTING.md.
License
This package is distributed under the terms of the MIT License.
However, note that it has a dependency on the (MPL licensed) Deque.AxeCore.Commons
NuGet package.
Acknowledgements
This package builds on past work from the PlaywrightAxeDotnet project (see NOTICE.txt). We @IsaacWalker for his work on that project.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.1 is compatible. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.1
- Deque.AxeCore.Commons (>= 4.7.2-alpha.58)
- Microsoft.Playwright (>= 1.20.2)
- System.IO.Abstractions (>= 17.0.24)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.
Version | Downloads | Last updated |
---|---|---|
4.10.1 | 696 | 11/11/2024 |
4.10.1-alpha.91 | 41 | 11/8/2024 |
4.10.0 | 2,915 | 9/3/2024 |
4.10.0-alpha.90 | 36 | 11/8/2024 |
4.10.0-alpha.88 | 42 | 10/29/2024 |
4.10.0-alpha.82 | 59 | 8/7/2024 |
4.9.1 | 12,882 | 5/13/2024 |
4.9.1-alpha.81 | 50 | 7/30/2024 |
4.9.1-alpha.80 | 61 | 5/15/2024 |
4.9.1-alpha.78 | 80 | 5/8/2024 |
4.9.0 | 3,978 | 3/29/2024 |
4.9.0-alpha.79 | 67 | 5/9/2024 |
4.9.0-alpha.77 | 69 | 5/7/2024 |
4.9.0-alpha.76 | 51 | 3/29/2024 |
4.9.0-alpha.75 | 64 | 3/26/2024 |
4.8.2 | 3,762 | 2/14/2024 |
4.8.2-alpha.74 | 62 | 3/26/2024 |
4.8.2-alpha.73 | 73 | 2/14/2024 |
4.8.2-alpha.72 | 65 | 2/14/2024 |
4.8.2-alpha.71 | 68 | 2/14/2024 |
4.8.2-alpha.70 | 67 | 2/8/2024 |
4.8.1 | 1,480 | 1/11/2024 |
4.8.1-alpha.69 | 54 | 2/8/2024 |
4.8.1-alpha.68 | 64 | 2/8/2024 |
4.8.1-alpha.65 | 73 | 1/9/2024 |
4.8.0 | 16,357 | 10/2/2023 |
4.8.0-alpha.67 | 63 | 2/7/2024 |
4.8.0-alpha.64 | 70 | 1/9/2024 |
4.8.0-alpha.63 | 73 | 1/9/2024 |
4.8.0-alpha.62 | 75 | 1/9/2024 |
4.7.2 | 1,985 | 8/30/2023 |
4.7.2-alpha.61 | 67 | 12/21/2023 |
4.7.2-alpha.59 | 68 | 11/21/2023 |
4.7.2-alpha.58 | 78 | 11/2/2023 |
4.7.2-alpha.57 | 84 | 11/1/2023 |
4.7.2-alpha.56 | 71 | 10/30/2023 |
4.7.2-alpha.55 | 71 | 10/19/2023 |
4.7.2-alpha.54 | 81 | 10/16/2023 |
4.7.2-alpha.53 | 74 | 10/16/2023 |
4.7.2-alpha.52 | 75 | 10/5/2023 |
4.7.2-alpha.51 | 89 | 10/3/2023 |
4.7.2-alpha.50 | 70 | 10/3/2023 |
4.7.2-alpha.49 | 83 | 9/27/2023 |
4.7.1-alpha.48 | 75 | 9/27/2023 |
4.7.1-alpha.47 | 83 | 9/27/2023 |
4.7.1-alpha.46 | 97 | 9/14/2023 |
4.7.1-alpha.45 | 83 | 9/13/2023 |
4.7.1-alpha.44 | 83 | 9/8/2023 |
4.7.1-alpha.43 | 105 | 8/30/2023 |
4.7.1-alpha.42 | 95 | 8/30/2023 |
4.4.0-alpha.c9651f2c2284967... | 18,072 | 11/10/2022 |
4.4.0-alpha.41 | 91 | 8/30/2023 |
4.4.0-alpha.40 | 97 | 8/30/2023 |