記事

テストへのタグの追加

タグを使用して、整理、フィルタリング、外観のカスタマイズのための意味情報を提供します。

概観

複雑なパッケージやプロジェクトには、数百、数千ものテストやスイートが含まれます。これらのテストの一部は、危機的 であったり、不安定 であったりするなど、共通の側面を持つ場合があります。テストライブラリには、テストをグループ化および分類するために追加できるタグと呼ばれる特性の型が含まれています。

タグはテストスイートとは異なります。テストスイートはソースレベルでテスト関数に構造体を付与しますが、タグはテストに意味情報を提供します。この情報は、テストスイート、ソースファイル、さらにはテストターゲット全体にわたって、全ての数の他のテストと共有できます。

タグの追加

テストにタグを追加するには、 tags(_:) 特性を使用します。この特性はタグのシーケンスを引数として受け取り、それらのタグは実行時に対応するテストに適用されます。テストスイートにタグが適用されると、そのスイート内のすべてのテストがそれらのタグを継承します。

テストライブラリはタグに意味を与えることはなく、タグの有無がテストライブラリによるテストの実行方法に影響を与えることもありません。

タグ自体は Tag のインスタンスであり、Tag の静的メンバーとして宣言された名前付き定数として表現されます。名前付き定数タグを宣言するには、Tag() マクロを使用します。

extension Tag {
  @Tag static var legallyRequired: Self
}

@Test("Vendor's license is valid", .tags(.legallyRequired))
func licenseValid() { ... }

同じ名前（上記の例では legallyRequired）のタグが 2 つ、異なるファイル、モジュール、またはその他のコンテキストで宣言されている場合、テストライブラリはそれらを同等として扱います。

パッケージやプロジェクト (またはその依存関係) 内の他の場所で宣言された類似のタグとタグを区別する必要がある場合は、逆 DNS 命名法を使用して、タグに一意の Swift シンボル名を作成します。

extension Tag {
  enum com_example_foodtruck {}
}

extension Tag.com_example_foodtruck {
  @Tag static var extraSpecial: Tag
}

@Test(
  "Extra Special Sauce recipe is secret",
  .tags(.com_example_foodtruck.extraSpecial)
)
func secretSauce() { ... }

タグを宣言できる場所

タグは、その型の拡張、または Tag 内にネストされた型において、常に Tag のメンバーとして宣言されなければなりません。タグを別の名前で再宣言しても効果はなく、追加した名前はテストライブラリによって認識されません。以下の例はサポートされていません。

extension Tag {
  @Tag static var legallyRequired: Self // ✅ OK: Declaring a new tag.

  static var requiredByLaw: Self { // ❌ ERROR: This tag name isn't
                                                      // recognized at runtime.
    legallyRequired
  }
}

タグが Tag 型の拡張の外部 (例えば、ファイルの root や関連のない他の型宣言内) で名前付き定数として宣言されている場合、そのタグはテスト関数やテストスイートに適用できません。以下の宣言はサポートされていません。

@Tag let needsKetchup: Self // ❌ ERROR: Tags must be declared in an extension
                                                // to Tag.
struct Food {
  @Tag var needsMustard: Self // ❌ ERROR: Tags must be declared in an extension
                                                // to Tag.
}