Tracera
开始试用

XCUITest

在 Package.swift 中为 UI 测试 target 添加 tracera-swift 的 TraceraXCUITest 依赖（会一并引入 Tracera）：

dependencies: [
  .package(url: "https://github.com/tracera-dev/tracera-swift", from: "0.1.0"),
],
targets: [
  .testTarget(
    name: "MyAppUITests",
    dependencies: [
      .product(name: "TraceraXCUITest", package: "tracera-swift"),
    ]
  ),
]

需要 Swift ≥ 6、macOS ≥ 15（或 iOS ≥ 18）以及 Xcode ≥ 16（见 自动化测试适配器）。

环境变量与运行模式：自动化测试适配器。

继承 TraceraXCTestCase，并在 class func setUp() 中调用一次 install()（媒体默认关闭 — 见截图）：

import XCTest
import Tracera
import TraceraXCUITest

final class CheckoutUITests: TraceraXCTestCase {
  override class func setUp() {
    install()
  }
  // …
}

若重写实例 setUp / tearDown（每个测试一次 — 不是 class func setUp），在 setUp 末尾调用 super.setUp()，在 tearDown 开头调用 super.tearDown()，这样步骤会进入 准备 / 测试 / 清理。

绑定 testCaseId 与 autotestName

在每个测试方法开头用 Tracera.testCase 绑定：

func testCheckout() {
  Tracera.testCase(42)
  // Tracera.testCase(42, "e2e/checkout")
  // …
}

若未指定 name，则 autotestName 取 XCTest 的测试名称。若多个方法共用同一用例 id，也可在实例 setUp 中绑定。

跳过

使用 skip("reason")，以便原因写入结果的 comment：

func testCheckout() throws {
  Tracera.testCase(42)
  try skip("needs a seeded account")
}

步骤

使用 Tracera.step("…") { } 或 await Tracera.step("…") { }。实例 setUp / tearDown 中的步骤进入结果的 准备 / 清理；测试体内的步骤进入 测试。

override func setUp() {
  Tracera.step("launch app") { }
  super.setUp()
}

func testCheckout() throws {
  Tracera.testCase(10)
  try Tracera.step("tap checkout") {
    try Tracera.step("nested leaf") { }
  }
}

override func tearDown() {
  super.tearDown()
  Tracera.step("terminate app") { }
}

注释、错误与附件

限制与允许的 MIME 类型：自动化测试适配器。

Tracera.comment、Tracera.error 和附件会添加到当前打开的步骤；若没有打开的步骤，则添加到结果。Tracera.attachmentFile 接收文件路径；Tracera.attachmentBytes 接收名称和字节（MIME 类型可选）。附件在结果上报时上传。

Tracera.comment("result-level note")
Tracera.error("result-level error")
Tracera.attachmentFile("Fixtures/screenshot.png")
Tracera.step("open login") {
  Tracera.comment("step note")
  Tracera.attachmentBytes("body.json", data: Data(#"{"ok":true}"#.utf8), mimeType: "application/json")
}

若在 Task 中调用 Tracera API（步骤、注释、错误、附件），请先在测试中调用 getContext()，再用 runWithContext 运行 worker — 否则这些调用不会写入报告：

let ctx = getContext()
Task {
  await runWithContext(ctx) {
    Tracera.step("worker") { /* ... */ }
  }
}

参数化测试

使用字面量 Tracera.testCase(id, name)（或省略 name → XCTest 测试名）。

截图与媒体

install() 是上报所必需的（见上文）。通过其参数可在每个测试结束时附加媒体（默认 .off）：screenshots: — .onFailure / .onSuccess / .always（iOS/tvOS：XCUIScreen；macOS：在允许屏幕录制时使用 ScreenCaptureKit）；hierarchy: → window-hierarchy.txt；logs: → device-log.txt（unified log / OSLogStore）。

override class func setUp() {
  install(screenshots: .onFailure, hierarchy: .onFailure, logs: .onFailure)
}

若要在选定时刻附加截图、层级或日志（例如点击之后），请手动调用：

Tracera.step("after login") {
  screenshot()
  attachHierarchy()
  attachDeviceLog()
}