A11yUITests

⚠️此库已不再维护，您可能不应该使用它。⚠️

相反，请考虑使用以下一个或多个工具，恕我直言，它们做得更好。

• AccessibilitySnapshot - 一个可访问性快照测试库，其覆盖范围比此方法更广。
• Reveal - 一个检查器，可以为您提供应用程序可访问性等的视觉表示。

A11yTests 是 XCTestCase 的扩展，它添加了针对常见可访问性问题的测试，这些测试可以作为 XCUI 测试套件的一部分运行。

测试可以单独运行，也可以集成到现有的 XCUI 测试中。

良好的可访问性不仅仅是勾选框并符合法规和指南，而是关于您的应用程序的用户体验。只有当真实用户使用您的应用程序时，您才能知道它是否真正可访问。将这些测试视为您可以做得更好的提示，并使用它们来检测回归。

这些测试的失败应被视为进一步调查的警告，而不是严格的失败。因此，我建议始终将 continueAfterFailure = true 设置为启用状态。

该库有两种类型的测试 - 断言 和 快照。断言测试检查每个单独的元素是否存在潜在的可访问性故障。快照测试创建应用程序可访问性树的快照，并将其存储为未来测试的参考。如果未来测试中可访问性树中发生任何更改，测试将失败，表示您应该验证更改。不会对可访问性树进行任何断言，只会检查自上次快照状态以来的任何更改。

失败分为两类：警告和失败。失败是指违反 WCAG 或 HIG。警告可能是可以接受的，但需要调查。

在您的测试文件顶部添加 import A11yUITests。

断言测试检查每个单独的元素是否存在潜在的可访问性故障。

测试可以单独运行或在套件中运行。

func test_allTests() {
    XCUIApplication().launch()
    a11yCheckAllOnScreen()
}

要指定元素和测试，请使用 a11y(tests: [A11yTests], on elements: [XCUIElement])，传递要运行的测试数组和要在其上运行测试的元素数组。要在所有按钮上运行所有交互式元素测试

func test_buttons() {
    let buttons = XCUIApplication().buttons.allElementsBoundByIndex
    a11y(tests: a11yTestSuiteInteractive, on: buttons)
}

要在单个元素上运行单个测试，请传递包含测试和元素的数组。要检查按钮是否具有有效的可访问性标签

func test_individualTest_individualButton() {
    let button = XCUIApplication().buttons["My Button"]
    a11y(tests: [.buttonLabel], on: [button])
}

当运行 a11yCheckAllOnScreen() 时，可以使用其可访问性标识符忽略元素，方法是传递您希望忽略的任何标识符作为 ignoringElementIdentifiers: [String] 参数。

A11yUITests 包含 4 个预构建的测试套件，其中包含适用于不同元素的测试。

a11yTestSuiteAll 运行所有测试。

a11yTestSuiteImages 运行适用于图像的测试。

a11yTestSuiteInteractive 运行适用于交互式元素的测试。

a11yTestSuiteLabels 运行适用于静态文本元素的测试。

或者，您可以为要运行的测试创建 A11yTests 枚举值的数组。

minimumSize 或检查元素是否至少为 14px x 14px。要指定最小尺寸，请将值设置为 A11yTestValues.minSize 严重性：警告

注意：14px 是任意值。

minimumInteractiveSize 检查可点击元素是否至少为 44px x 44px。这符合 WCAG 2.1 成功标准 2.5.5 目标尺寸 AAA 级别 要指定自定义最小交互尺寸，请将值设置为 A11yTestValues.minInteractiveSize。不建议这样做。严重性：错误

注意：Apple 的许多控件都未能满足此要求。因此，当运行包含 minimumInteractiveSize 的测试套件时，仅检查按钮和单元格。这可能仍然会导致例如 UITabBarButton 的一些失败。为了完全符合要求，您应该对用户可能与之交互的任何元素（例如，滑块、步进器、开关、分段控件）运行 a11yCheckValidSizeFor(interactiveElement: XCUIElement)。但是您需要创建自己的子类，因为 Apple 的控件并非严格遵守 WCAG。

labelPresence 检查元素是否具有至少 2 个字符长的可访问性标签。将 minMeaningfulLength 参数传递给 a11yCheckValidLabelFor(element: XCUIElement, minMeaningfulLength: Int ) 以更改最小长度。或者，要为所有测试设置最小长度，请将值设置为 A11yTestValues.minMeaningfulLength 这有助于满足 WCAG 2.1 指南 1.1 文本替代，但不保证完全符合。严重性：警告

此外，此测试还检查具有占位符但没有标签的元素，以及标签是否为大写。严重性：失败

注意：长度为 2 是任意值

buttonLabel 检查交互式元素的标签是否以大写字母开头，并且不包含句点或单词“button”。检查标签是否至少为 2 个字符长。检查按钮是否不包含常见的非描述性标题。这还会检查其他交互式元素在其标签中是否不包含其类型。将 minMeaningfulLength 参数传递给 a11yCheckValidLabelFor(interactiveElement: XCUIElement, minMeaningfulLength: Int ) 以更改最小长度。或者，要为所有测试设置最小长度，请将值设置为 A11yTestValues.minMeaningfulLength 这遵循 Apple 关于编写可访问性标签的指南。这遵循 WCAG 2.1 成功标准 2.4.9 链接目的（仅限链接） 严重性：错误

注意：此测试未本地化。注意：长度为 2 是任意值

imageLabel 检查可访问图像是否不包含单词 image、picture、graphic 或 icon，并检查标签是否未重用图像文件名。检查标签是否至少为 2 个字符长。将 minMeaningfulLength 参数传递给 a11yCheckValidLabelFor(image: XCUIElement, minMeaningfulLength: Int ) 以更改最小长度。或者，要为所有测试设置最小长度，请将值设置为 A11yTestValues.minMeaningfulLength 这遵循 Apple 关于编写可访问性标签的指南。在决定是否使图像可访问时应谨慎，以避免产生不必要的噪音。严重性：错误

注意：此测试未本地化。注意：长度为 2 是任意值

labelLength 检查可访问性标签是否 <= 40 个字符。要为所有测试设置最大长度，请将值设置为 A11yTestValues.maxMeaningfulLength 这遵循 Apple 关于编写可访问性标签的指南。理想情况下，标签应尽可能简短，同时保留含义。如果您觉得您的元素需要更多上下文，请考虑添加可访问性提示。严重性：警告

注意：长度为 40 是任意值

header 检查屏幕是否至少有一个具有标题特征的文本元素。VoiceOver 用户使用标题来定位和快速导航内容。这遵循 WCAG 2.1 成功标准 2.4.10 严重性：错误

buttonTrait 检查按钮元素是否应用了“按钮”或“链接”特征。这遵循 Apple 关于使用特征的指南。严重性：错误

imageTrait 检查图像元素是否应用了“图像”特征。这遵循 Apple 关于使用特征的指南。严重性：错误

conflictingTraits 检查元素是否没有冲突的特征。元素不能既是按钮又是链接，也不能既是静态文本又是频繁更新的文本

disabled 检查元素是否未被禁用。如果用户不清楚元素为何被禁用，则禁用的元素可能会造成混淆。理想情况下，保持元素启用状态，并在您的应用程序尚未准备好处理操作时清晰地传达消息。严重性：警告

duplicated 检查提供的所有元素是否存在可访问性标签重复的情况。重复的可访问性标签可能会使您的屏幕难以通过 VoiceOver 导航，并导致语音控制失败。理想情况下，您应尽可能避免重复。严重性：警告

controlSpacing 检查控件之间是否具有最小间距。iPhone 为 8px，iPad 为 12px。HIG 建议 iPad 的最小值为 12px。iPhone 设置为 8px，可以通过将值设置为 A11yTestValues.iPhonePadding 来更改。

注意：iPhone 上的 8px 是任意值。

controlOverlap 检查控件是否没有重叠的框架。严重性：失败

快照在首次运行时创建屏幕可访问性树的 JSON 表示形式。在后续运行时，此初始快照将作为参考。如果参考快照和当前快照之间存在任何差异，则测试将失败。不会断言可访问性树是否正确或有效，您必须自行进行这些检查并生成已知的良好参考快照，以防止未来的回归。

在您的 UI 测试中调用 a11ySnapshot()。首次运行时，测试将失败，因为尚未为此测试创建快照。将生成参考快照。从失败消息中提供的 URL 获取参考快照，或在测试的 XCResult 中找到它。将此文件添加到您的 UITest 目标，确保文件名与生成的 json 文件的 filename 属性匹配。后续测试运行将与此快照进行比较，如果您希望生成新的快照，请从您的 UITest 目标中删除参考，运行测试，然后将生成新的参考。

快照测试检查以下方面的更改

• 可访问性标签
• 框架
• 启用状态
• 控件类型
• 可访问性特征

使用 A11yTestValues 为所有测试设置各种默认值。

要运行示例项目，请克隆 repo，并首先从 Example 目录运行 pod install。

A11yUITests_ExampleUITests.swift 包含示例测试，这些测试显示了上述每个测试的失败情况。

iOS 11

Swift 5

此库支持 Swift Package Manager。确保将软件包作为依赖项添加到您的 UITests 目标，而不是您的应用程序目标。

A11yUITests 可通过 CocoaPods 获得。要安装，请将 pod 添加到 podfile 中目标的测试目标。例如

target 'My_Application' do
    target 'My_Application_UITests' do
    pod 'A11yUITests'
    end
end

• 此库访问 iOS SDK 中的私有属性，因此在将其添加到您的项目时应小心，以确保您没有发布此代码。如果您将此代码提交给应用程序审核，您很可能会收到 Apple 的拒绝。如果您确实提交了此代码，则说明您安装错误，请再次查看 安装。

如果两个相同类型的元素具有相同的标识符（例如，两个都标记为“Next”的按钮），则可能导致测试在某些 iOS 版本上崩溃。这是 iOS 13 上的一个问题，并且在 iOS 15 中似乎已修复。

从可访问性中隐藏的元素仍然会受到这些测试的评估。这是由于 XCUI 如何向测试运行器呈现元素，我目前不知道有什么方法可以检测从可访问性中隐藏的元素。

Rob Whitaker, rw@rwapp.co.uk
https://mobilea11y.com

A11yUITests 在 MIT 许可证下可用。有关更多信息，请参见 LICENSE 文件。