中級者向け

Baseline で既存の違反を一時的に無効化する

既存のプロジェクトに katachi を入れると、最初の実行で 宣言していないファイルやディレクトリが違反として出ます。 出てきたパスを定義に足すか・移すか・消すかで片付けていくのが基本ですが、数が多いとすぐには片付けきれないでしょう。

baseline は既存の違反を一時的に抑制して、新しい違反をテストでエラーにする機能です。

設定する

1. 定義に `baseline()` を書く

val projectArchitecture: Architecture = architecture {
    // ...
    baseline()

    // ...
}

baseline を設定すると、デフォルトではプロジェクトルートの katachi-baseline.json が Baseline ファイルとして使われます。

2. Baseline ファイル自身を `layout { }` で宣言する

Baseline ファイルもプロジェクトのファイルの1つなので、Role として宣言しないと projectArchitecture.assert() でエラーになってしまいます。

慣例に従って “BaselineFile” という名前の Role を用意して architecture 定義内に追加してください。

val projectArchitecture = architecture {
    // ...
    "Tool".group {
      "Katachi".group {
        baselineFile()
      }
    }

    // ...
}

fun DeclarationContainerScope.baselineFile() = "BaselineFile" {
    title = "katachi Baseline ファイル"
    summary = "既存の違反を一時的に抑制するためのファイル"
    description = "参照: https://tbsten.github.io/katachi/ja/guides/baseline/"
    layout {
        "katachi-baseline.json".file()
    }
}

3. Baseline ファイルを作成する

-Dkatachi.baseline.update=true を付けてアーキテクチャテストを実行すると、全ての違反はエラーにならず、許容されて Baseline ファイルに書き込まれます。

./gradlew :architecture-test:test -Dkatachi.baseline.update=true

作成・更新されたファイルは、コミットすることをおすすめします。

許容していた違反を直したあと

許容されていた違反を直すと、Baseline ファイルにはもう存在しない違反の記録が残ります。放っておくと、あとで同じパスに置かれた別のファイルが気づかないうちに通ってしまうので、katachi はこの残りを [StaleBaselineEntry] として報告し、テストを落とします。

baseline のファイルから修正した違反を削除するには、-Dkatachi.baseline.prune=true を付けて、もう一度アーキテクチャテストを実行します。

./gradlew :architecture-test:test -Dkatachi.baseline.prune=true

prune は、記録の件数を減らすだけです。新しい違反を baseline のファイルに足すことはありません（足すのは -Dkatachi.baseline.update=true の役目です）。違反が減った Baseline ファイルは再度コミットしてください。

まとめ

baseline は、既存の違反を Baseline ファイルに記録して一時的に抑制し、新しく増えた違反と、直したのに Baseline ファイルに残っている分でだけテストを落とすための機能です。
Baseline ファイルは -Dkatachi.baseline.update=true を付けてアーキテクチャテストを実行すると作成・更新されます。できたファイルはコミットしておきましょう。
許容していた違反を直すと、baseline のファイルに残った分が [StaleBaselineEntry] でテストを落とします。-Dkatachi.baseline.prune=true で修正した違反を削除します。

次のステップ

初めてのアーキテクチャ定義 … baseline で許容する前の、最初の定義の書き方です。