API コレクション

既知の問題

テストを実行するときに、問題を既知としてマークします。

概観

テストライブラリには、問題を既知の問題としてマークするための withKnownIssue() という関数がいくつか用意されています。これらの関数を使用することで、既知の問題のみが記録されている場合はテストを失敗としてマークしないようテストライブラリに指示できます。

期待される失敗を既知としてマークする

単一の期待値を持つテスト関数を考えてみましょう。

@Test func grillHeating() throws {
  var foodTruck = FoodTruck()
  try foodTruck.startGrill()
  #expect(foodTruck.grill.isHeating) // ❌ Expectation failed
}

isHeating プロパティの値が false の場合、#expect は問題を記録します。根本的な問題を修正できない場合は、問題のあるコードを withKnownIssue() に渡されたクロージャで囲むことができます。

@Test func grillHeating() throws {
  var foodTruck = FoodTruck()
  try foodTruck.startGrill()
  withKnownIssue("Propane tank is empty") {
    #expect(foodTruck.grill.isHeating) // Known issue
  }
}

#expect によって記録された問題は「既知」とみなされ、テストは失敗としてマークされません。問題の説明や背景情報を提供するために、オプションでコメントを追加できます。

throw されたエラーを既知としてマークする

withKnownIssue() に渡されたクロージャによって Error がキャッチされた場合、そのキャッチされたエラーを表す問題は既知の問題としてマークされます。前の例の続きで、startGrill() 関数がエラーを throw しているという問題を考えてみましょう。この状況にも withKnownIssue() を適用できます。

@Test func grillHeating() {
  var foodTruck = FoodTruck()
  withKnownIssue {
    try foodTruck.startGrill() // Known issue
    #expect(foodTruck.grill.isHeating)
  }
}

クロージャから throw されたすべてのエラーはキャッチされ、既知の問題として解釈されるため、withKnownIssue() 関数はエラーを throw しません。したがって、エラーを throw する呼び出し関数が成功することを前提とする後続のコード (startGrill() の後の #expect など) は、追加の問題を回避するためにクロージャに含めなければなりません。

注意

既知の問題と見なされるエラーについては、テストのステータスと結果が状況をより正確に反映するように、#expect(throws:) ではなく withKnownIssue() を使用することをお勧めします。

特定の問題に一致する

デフォルトでは、withKnownIssue() は本体クロージャの呼び出し時に記録されたすべての問題を既知とみなします。複数の問題が記録される可能性がある場合は、matching: というラベルを追跡クロージャに渡すことができます。このクロージャは、記録された問題ごとに 1 回呼び出され、既知として扱うべきかどうかを判断します。

@Test func batteryLevel() throws {
  var foodTruck = FoodTruck()
  try withKnownIssue {
    let batteryLevel = try #require(foodTruck.batteryLevel) // Known
    #expect(batteryLevel >= 0.8) // Not considered known
  } matching: { issue in
    guard case .expectationFailed(let expectation) = issue.kind else {
      return false
    }
    return expectation.isRequired
  }
}

既知の問題を解決する

function の呼び出し中に問題が記録されていない場合、withKnownIssue() は、問題が記録されていないことを示す明確な問題を記録します。これは、根本的な問題が解決された可能性があることを通知するため、調査を行い、不要になった場合は withKnownIssue() を削除することを検討できます。

決定的でない失敗を処理する

withKnownIssue() は時々成功するが、他の時には既知の問題がなかったことを示す問題が記録される場合、これは決定的でない失敗または "flaky" テストを示している可能性があります。

決定的でないテストの失敗を解決するための最初のステップは、テスト対象のコードを分析し、予測不可能な動作の原因を特定することです。競合状態などのバグを発見した場合、理想的な解決策は、根本的な問題を修正し、既知の問題が引き続き発生している場合でも、コードが常に一貫した動作をするようにすることです。

根本的な問題が特定の状況でのみ発生する場合は、前提条件を含めることを検討してください。例えば、グリルがプロパンガスがないときにのみ加熱に失敗する場合は、"when:" というラベルの付いた追跡クロージャを渡すことができます。これは、本体クロージャに記録された問題を既知の問題と見なすかどうかを決定します。

@Test func grillHeating() throws {
  var foodTruck = FoodTruck()
  try foodTruck.startGrill()
  withKnownIssue {
    // Only considered known when hasPropane == false
    #expect(foodTruck.grill.isHeating)
  } when: {
    !hasPropane
  }
}

根本的な問題が予測不可能で、ランダムに発生する場合は、isIntermittent: true を渡してテストライブラリにその問題が常に発生するわけではないことを知らせることができます。こうすることで、既知の問題が 0 件しか記録されていない場合、テストライブラリは問題を記録しなくなります。

@Test func grillHeating() throws {
  var foodTruck = FoodTruck()
  try foodTruck.startGrill()
  withKnownIssue(isIntermittent: true) {
    #expect(foodTruck.grill.isHeating)
  }
}