devkuma – Kotest

Kotestフレームワーク(Framework)

kc@example.com (kc kim) — Sun, 10 Mar 2024 13:28:00 +0900

Kotest拡張(Extensions)

kc@example.com (kc kim) — Sun, 10 Mar 2024 13:03:00 +0900

Kotest アサーション(Assertions)

kc@example.com (kc kim) — Mon, 11 Mar 2024 12:42:00 +0900

Kotest プロパティテスト(Property Testing)

kc@example.com (kc kim) — Sun, 17 Mar 2024 21:13:00 +0900

Kotest IntelliJ プラグイン(IntelliJ Plugin)

kc@example.com (kc kim) — Sun, 25 Feb 2024 10:28:00 +0900

Kotest プロパティベーステスト(Property-based Testing)

kc@example.com (kc kim) — Sun, 17 Mar 2024 21:48:00 +0900

プロパティベーステスト

Kotest は、独立して使用できる複数のサブプロジェクトに分かれている。そのうちの 1 つがプロパティテストフレームワーク(Property-based Testing)である。当然だが、プロパティテストサポートの利点を得るために Kotest をテストフレームワークとして使用する必要はない。

プロパティテストとは何か

開発者は一般的に例ベースのテストを書く。これは、よく知られているさまざまな単体テストである。いくつかの入力値と期待結果を与えると、Kotest や JUnit のようなテストフレームワークが、実際の結果が期待に合っているかを確認する。

このアプローチの問題の 1 つは、開発者が思いつかなかったエッジケースや、選んだ入力のカバレッジ不足によって、エラーを見逃しやすいことである。代わりにプロパティテストを使うと、同じテストに数百または数千の値が入力され、その値は通常プロパティテストフレームワークによってランダムに生成される。

たとえば、優れたプロパティテストフレームワークには、負の無限大、空のリスト、非 ASCII 文字を含む文字列などの値が含まれる。これらは例ベースのテストを書くときに忘れがちなものである。

プロパティテストはもともと QuickCheck のようなフレームワークで、あるオブジェクトのプロパティ、つまりすべての入力に対して真でなければならないプロパティをテストする概念として考案された。言い換えると不変条件である。不変条件の例として、2 つの文字列 a と b がある場合、length(a + b) は常に length(a) + length(b) と同じでなければならない。

ここから property testing という用語が生まれた。

ただし、モナド則や基本的な数値関数のようなものだけをテストするためにプロパティテストを使う必要はない。さまざまな入力値を活用できるテストは、すべて良い候補である。たとえば、ユーザー名を検証する関数があり、有効なメールアドレスが受け入れられることをテストしたい場合、プロパティテストは検証ロジックを強化する数千の組み合わせを生成するのに役立つ。

はじめに

プロパティテストフレームワークはすべてのターゲットでサポートされる。

JVM/Gradle

ビルドに次の依存関係を追加する。

dependencies {
    testImplementation("io.kotest:kotest-property:$version")
}

JVM/Maven

ビルドに次の依存関係を追加する。

<dependency>
   <groupId>io.kotest</groupId>
   <artifactId>kotest-property-jvm</artifactId>
   <version>${version}</version>
   <scope>test</scope>
</dependency>

Multiplatform

commonTest ソースセットに次の依存関係を追加する。

kotlin {
  sourceSets {
    val commonTest by getting {
      dependencies {
        implementation("io.kotest:kotest-property:$version")
      }
    }
  }
}

または、特定のターゲットに依存関係を追加することもできる。たとえば JavaScript ターゲットに対して、jsTest ソースセットだけで使用する依存関係を追加できる。

kotlin {
   targets {
      js {
         browser()
         nodejs()
      }
   }
   sourceSets {
      val jsTest by getting {
         dependencies {
            implementation("io.kotest:kotest-property:$version")
         }
      }
   }
}

次のステップ

テストの入力値を生成するために、Kotest はジェネレーター(generator)という用語を使用する。入力引数ごとに 1 つのジェネレーターがテスト関数に渡され、テストは設定された反復回数だけ実行される。

詳しく見る内容:

テスト関数の使い方。
さまざまな種類のジェネレーターとその操作。
カスタムジェネレーターの書き方。
シードを含むテスト設定の指定方法。

参照

Property-based Testing | Kotest

Kotestテスト検証アサーション(Assertions)

kc@example.com (kc kim) — Mon, 11 Mar 2024 12:42:00 +0900

Kotestは、独立して使用できる複数のサブプロジェクトに分かれている。これらのサブプロジェクトの1つは、包括的なアサーション(assertion)/matcherサポートを提供する。これはKotestテストフレームワーク、またはJUnitやSpockのような他のテストフレームワークと一緒に使用できる。

アサーションモジュールの中核機能は、状態をテストする関数である。Kotestはこの種の状態アサーション関数をMatchersと呼ぶ。コアmatcherとサードパーティライブラリ向けmatcherがある。

例外テスト、非決定的コードのテストに役立つ関数、コレクション用のインスペクタ、アサーションをグループ化するソフトアサーションなど、テスト作成のための他の多くのユーティリティもある。

さまざまなmatcher

たとえば、変数に期待値があることを確認するには、shouldBe関数を使用できる。

name shouldBe "devkuma"

文字列の長さをテストするstr.shouldHaveLength(10)、特定のファイルがディレクトリを指しているかをテストするfile.shouldBeDirectory()のようなさまざまな特定シナリオ向けmatcherだけでなく、shouldBeのような汎用matcherもある。この関数はinfix形式と通常形式の両方で提供される。

たとえば、アサーションは通常チェーンできる。

"substring".shouldContain("str")
           .shouldBeLowerCase()

myImageFile.shouldHaveExtension(".jpg")
           .shouldStartWith("https")

複数のモジュールにわたって350以上のmatcherがある。すべてのmatcherについてはここで確認してほしい。

手がかり(Clues)

失敗したアサーションに、何が間違っているのかを正確に知るための十分な情報が含まれていない場合がある。

たとえば、次のように検証するとしよう。

user.name shouldNotBe null

この検証が失敗すると、単に次のように出力される。

<null> should not equal <null>

これは特に役立たない。手がかりを使用して、失敗メッセージに追加コンテキストを加えることができる。

インスペクタ(Inspectors)

インスペクタを使用すると、コレクションの要素をテストし、通過すると期待される要素数、all、none、exactly kなどを指定できる。

たとえば、次のようにmylistを3つ確認できる。

mylist.forExactly(3) {
    it.city shouldBe "Chicago"
}

ここでインスペクタについて確認してほしい。

カスタムmatcher

Matcher<T>インターフェースを拡張することで、自分だけのmatcherを簡単に追加できる。ここでTは一致させたい型である。カスタムmatcherは既存matcherを構成したり、完全に独立して使用したりできる。

完全な動作例を参照すること。

参考

Assertions | Kotest

Kotest外部拡張(Extensions)

kc@example.com (kc kim) — Sun, 10 Mar 2024 20:05:00 +0900

ここで紹介する拡張は、frameworkで説明したio.kotest.coreに含まれるListenersとは別に、ライブラリを新しく追加して使う拡張について紹介するものである。

Kotest Team Extensions

プロジェクト	説明
Allure	Allureフレームワーク向けの出力を提供する。
HTML Reporter	JUnit XMLを基にテスト結果のHTMLレポートを生成する。
Instant	`java.time`で`now`コンテキストを上書きする。
JUnit XML	ツールとの統合のためにJUnit XML形式の出力を提供する。
Ktor	Ktorエンドポイント向けのmatchersを提供する。
Koin	Kotlin DIフレームワーク。
Mockserver	モックHTTPサーバーをテストライフサイクルと統合する。
Spring	テストおよびSpringテストアノテーションでSpring Beanのサポートを追加する。
System	`System.*`関数との統合のためのユーティリティを提供する。
Testcontainers	テストライフサイクルの一部としてDockerイメージを実行する。
Wiremock	HTTPサーバーを提供する。プロジェクトホームページはこちらを参照。

Third Party Extensions

プロジェクト	説明
Android	KotestおよびAndroid作業のためのツールボックス。
FluentLenium	KotestとFluentLeniumの統合。
H2 Database Extension	KotestとH2データベースの統合。
Http4k	Kotlin HTTPアプリケーション用の機能ツールキット。
Kotless	KotestおよびKotless用ユーティリティ。
KotlinFixture	明確に定義されているが、デフォルトではランダムな入力を生成する。
LogCapture	ロギングメッセージをアサートするためのテストライブラリ。
Micronaut	簡単にテストできるモジュール式マイクロサービスを構築するためのMicronaut JVMベースのフルスタックフレームワーク。
Result4s	Result4s matcher。
Selfie	セルフスナップショットテスト(インライン、ディスク、メモ化)。
Sniffy	ネットワーク接続テスト。
TestFiles	テストのための体系的なファイルおよびディレクトリ生成。

参照

Extensions | Kotest

Kotest IntelliJ Plugin 紹介

kc@example.com (kc kim) — Sun, 25 Feb 2024 10:28:00 +0900

Kotest は、JetBrains プラグインマーケットプレイス、または IntelliJ 内の検索から利用できる IntelliJ プラグインを提供する。

このプラグインは、各テストの実行アイコン、テスト探索用のツールウィンドウ、重複テストのハイライト、アサーション intention などを提供する。

NOTE

IntelliJ プラグインには Kotest 4.2 以降が必要であり、マルチプラットフォームプロジェクトの common tests は実行されない。

Gutter Icons

IntelliJ プラグインには Kotest 4.2 以降が必要であり、マルチプラットフォームプロジェクトの common tests は実行されない。

bang によって無効化されたテスト、または xdescribe のような xfunctions によって無効化されたテストは、ガターに無効化されたテストアイコンが表示される。

テスト実行

Gutter Icons から spec を実行すると、その spec のすべてのテストが実行される。テストを実行すると、そのテストとネストされたすべてのテストが実行される。

重複テストのハイライト

同じ名前のテストを 2 つ持つことはできない。プラグインは重複したテスト名をエラーとしてハイライトする。

コンテキストメニュー Run/Debug

パッケージを右クリックすると、そのパッケージ内のすべてのテストを実行、デバッグ、またはカバレッジ付きで実行できる。

Intentions

このプラグインには、いくつかの基本的な intentions がある。たとえば、テストを素早く無効化済みとしてマークできる。

また、一部のテキストをハイライトして throw すべきものとしてマークしたり、soft assertion ブロックで囲んだりできる。

参照

IntelliJ Plugin | Kotest

Kotest概要

kc@example.com (kc kim) — Sun, 25 Feb 2024 10:28:00 +0900

Kotestとは？

Kotlinは、開発者が安定した堅牢なソフトウェアを開発できるようにする、現代的で強力な言語である。品質を維持し、機能を保証するには効果的なテストが不可欠であり、そのためKotlin開発者はKotestのような強力なテストフレームワークを使用する。

Java環境では、以前からJUnitがテストによく使われてきた。KotlinでもJUnitを使ったテストは可能であり、現在も広く使われている。JUnitはJavaで実装されたテストフレームワークだが、Kotestは純粋なKotlinで実装されたテストフレームワークである。Kotestを使うと、JUnitに比べてKotlinの構文を自然に利用できるため、コード量を減らせる。また、1つのテストケースの中に別のテストケースを含め、ネストして記述できる利点がある。これにより、テストをよりモジュール化し、構造化して表現できる。

KotestはKotlinで書かれた柔軟で強力なテストフレームワークである。KotestはKotlinの強力な機能を活用し、テストの作成と管理を簡単かつ効果的に行えるように支援する。このフレームワークはさまざまなテストスタイルと構成オプションを提供し、多様なテスト要件に対応できる。

詳しい内容は公式サイトに整理されているが、簡単に紹介すると、大きな特徴としてSpecと呼ばれるクラスが10種類用意されており、目的に合ったSpecを選んでテストを書ける。各Specはさまざまな言語やテストフレームワークの影響を受けて作られているため、別の言語からKotlinを始めた人は、自分に馴染みのあるテストSpecを選択できる。

Kotest公式サイト

そのほかにも、実験的な機能を含む多くの機能、Assertion、Extensionが用意されている。

ここではKotestの基本構文を整理し、Kotestをサポートするライブラリについても説明する。

もともとKotestは？

KotestはKotlinで使用できるテストフレームワークで、以前はKotlinTestという名前だったが、リリース4.0からJetBrains提供パッケージとの混同を避けるためKotestに名称変更された。

Kotestの利点と特徴

Kotestにはさまざまな利点と特徴がある。

Kotestの利点

KotestはKotlin言語と密接に統合されており、Kotlinの強力な機能を最大限に活用できる。
Kotestはさまざまなテストスタイルをサポートしており、開発者は自分の好みに合ったスタイルを選択できる。
Kotestはテスト作成と管理を改善するための多くの機能を提供する。

これらの機能には、AssertionとMatchers、モックとスタブ、テストデータ管理などがある。さらに、Kotestは拡張可能なプラグインアーキテクチャを提供しているため、必要に応じてライブラリを拡張できる。

KotestはKotlinベースのプロジェクトでテストを書くために必要なツールと機能を提供し、開発者が安定した高品質なソフトウェアを開発するうえで大きな助けになる。

Kotestの特徴

Kotest DSLを使用する
複数のTestStyleを使って、シンプルで読みやすいテストを書ける
データ駆動テストにより、大量のパラメータもテストできる
すべてのテストに対して、呼び出し回数、並列処理、タイムアウト、テストのグループ化、条件付き無効化などを細かく調整できる
ネストしたテスト機能を提供する
動的テストを提供する（実行時に条件付きでテストを追加できる）
テストライフサイクルに合わせた多様なコールバックを提供する

テスト駆動開発の紹介

Kotestはテスト駆動開発(Test-driven development, TDD)を支援するうえで非常に有用なツールである。TDDはソフトウェア開発方法論の1つで、まずテストを書き、そのテストを基にコードを実装する方式である。これによりコード品質を向上させ、バグを早期に発見できる。

テスト駆動開発(Test-driven development, TDD)

テスト駆動開発は、テストケースを先に作成し、そのテストケースを通過するコードを書く過程を繰り返してソフトウェアを開発する方法論である。この方法論はコード品質を向上させ、バグを減らすのに役立つ。

KotestはTDDをサポートする

KotestはTDDを支援するため、次のような機能を提供する。

簡単なテスト作成: Kotestはシンプルで直感的なAPIを提供し、テストを作成しやすくする。さまざまなスタイルとMatchersを活用することで、コードをより効果的にテストできる。
テストの自動実行: Kotestはテストが変更されるたびに自動実行できる機能を提供する。これにより、テストを継続的に実行し、コード変更の影響を素早く確認できる。
テストカバレッジツールとの統合: Kotestはコードカバレッジツールとの統合をサポートし、テストカバレッジを測定して未テストのコードを識別できる。これにより、テストの完成度を高められる。
モックオブジェクトとスタブのサポート: KotestはMockKのようなモックオブジェクトおよびスタブライブラリをサポートし、テスト中に外部依存関係を置き換えられる。これにより、テストをより分離し、安定性を高められる。

TDDの中核原則

TDDの中核原則である「Red, Green, Refactor」は、ソフトウェア開発過程で守るべきアプローチを示す。この原則は、テストを書き、コードを実装し、コードを改善する一連の段階を表している。

Red（赤）: 赤の状態はテストが失敗している状態を意味する。新しい機能を実装する前に赤の状態を作らなければならない。Kotestではテストを書いて実行し、テストが失敗するようにする。この段階では、テストがまだ存在しないか、期待した結果を返さないコードを書く。
Green（緑）: 緑の状態はテストが成功している状態を意味する。Red状態で失敗したテストを通過できるようにコードを書く。Kotestでは失敗したテストを通過できるようにコードを修正し、テストを再実行して緑の状態にする。
Refactor（リファクタ）: リファクタ段階は、テストによってコードの動作を保ちながらコードを改善する段階である。緑の状態ではテストは通過しているが、コードにはまだ改善の余地がある。Kotestではコードをリファクタリングし、可読性、保守性、性能などを向上させられる。このとき、テストによってコード変更で既存の動作が変わっていないことを確認する。

この「Red, Green, Refactor」のアプローチに従ってKotestを使用すると、ソフトウェア開発過程でテスト駆動開発をより効果的に実践できる。テストが失敗した後に成功するようコードを書き、その後コードを改善しながらも、テストによってコードの安定性を保証できる。

TDDはソフトウェアの設計、品質、保守性を向上させるのに役立ち、Kotestのようなテストライブラリを使うことで効果的に適用できる。TDDでソフトウェアを開発するときにKotestを活用すれば、より効果的にテストを作成し、維持できる。

簡単なKotestの例

まず、簡単なサンプルコードをいくつか見てみよう。

Test with Style

利用可能なスタイルの1つを使って、シンプルで表現力のあるテストを書ける。

class MyTests : StringSpec({
    "length should return size of string" {
        "hello".length shouldBe 5
    }
    "startsWith should test for a prefix" {
        "world" should startWith("wor")
    }
})

コードについては後で詳しく見るが、ここでは簡単に見ると、StringSpecクラスを継承していることがわかる。また、テストの説明を文字列で記述し、shouldBeとshouldで検証している。

このように、KotestではKotlinの構文で2つのテストコードをネストして記述できることが確認できる。

Kotestでは複数のスタイルでテストを作成できるため、自分に最も合ったスタイルを選択できる。

データ駆動テストによる複数テストケースの確認

データ駆動テストを使えば、大量の入力パラメータの組み合わせも簡単に扱える。

class StringSpecExample : StringSpec({
   "maximum of two numbers" {
      forAll(
         row(1, 5, 5),
         row(1, 0, 1),
         row(0, 0, 0)
      ) { a, b, max ->
         Math.max(a, b) shouldBe max
      }
   }
})

テスト実行の細かな調整

各テストまたはすべてのテストに対して、呼び出し回数、並列処理、タイムアウトを指定できる。また、タグごとにテストをグループ化したり、条件付きで無効化したりできる。configで設定するだけでよい。

class MySpec : StringSpec({
   "should use config".config(timeout = 2.seconds, invocations = 10, threads = 2, tags = setOf(Database, Linux)) {
      // test here
   }
})

参考

Introduction | Kotest

Kotest Spring拡張(SpringExtension)

kc@example.com (kc kim) — Sun, 31 Mar 2024 16:17:00 +0900

TIP

文書を読むより例を見たい場合は、[こちら](https://github.com/kotest/kotest-examples-spring-webflux)のSpring WebFluxを使用するサンプルプロジェクトを参照してほしい。

Spring Extension

依存関係の追加

この拡張機能を使用するには、テストコンパイルパスにio.kotest.extensions:kotest-extensions-springモジュールを追加する必要がある。最新バージョンはMaven Centralで確認できる。

まずSpringでKotestを使用するには、以下の依存関係を追加する。

testImplementation("io.kotest.extensions:kotest-extensions-spring:1.0.0")

参考: MavenグループIDは、コアテストフレームワーク(io.kotest.extensions)とは異なる。

Configuration

すべてのテストにSpringExtensionを適用するには、グローバル設定で構成できる。

class GlobalProjectConfig : AbstractProjectConfig() {
    override fun extensions() = listOf(SpringExtension)
}

Spring拡張を使用するには、すべてのテストクラスまたはテストクラスごとに有効化する必要がある。

グローバルに有効化するには、プロジェクト構成でSpringExtensionを登録する。

class ProjectConfig : AbstractProjectConfig() {
   override fun extensions() = listOf(SpringExtension)
}

場合によっては、SpringExtensionをグローバルに有効化せずにテストを使用したいこともある。この場合、グローバル設定をせず、SpringExtensionを使用するテストクラスでのみextensionsを設定して使用できる。

テストクラスごとに有効化する方法は次のとおりである。

class SpringTest : FunSpec() {
    override fun extensions() = listOf(SpringExtension)
}

Springで使用する構成クラスを知らせるには、Specクラスに@ContextConfigurationアノテーションを追加する必要がある。このアノテーションは、Springの@Configurationアノテーションが付いたクラスを指す必要がある。または、@ActiveProfilesを使用して特定のアプリケーションコンテキストファイルを指すこともできる。

NOTE

Kotest 4.3以前では、Spring拡張は`SpringListener`と呼ばれていた。この拡張は現在非推奨となり、`SpringExtension`に置き換えられた。使用方法は同じだが、`SpringExtension`にはより多くの機能が提供される。

コンストラクタインジェクション

コンストラクタインジェクションの場合、自動スキャンが有効であると仮定すると、Springモジュールがビルドに追加されたとき、KotestはSpringAutowireConstructorExtensionを自動登録する。自動スキャンが無効の場合は、プロジェクト構成で手動で拡張をロードする必要がある。

この拡張は、Specインスタンスを生成する各呼び出しをインターセプトし、プライマリコンストラクタで宣言されたBeanを自動配線する。

次の例は、プライマリコンストラクタにUserServiceというサービスを必要とするテストクラスである。このサービスクラスは@Componentでアノテーションされた通常のSpring Beanである。

@ContextConfiguration(classes = [(Components::class)])
class SpringAutowiredConstructorTest(service: UserService) : WordSpec() {
  init {
    "SpringExtension" should {
      "have autowired the service" {
        service.repository.findUser().name shouldBe "system_user"
      }
    }
  }
}

@SpringBootTestを使う方法もある。

@SpringBootTest(classes = [FooService::class])
class SpringTest(fooService: FooService) : FunSpec() {
    override fun extensions() = listOf(SpringExtension)

    init {
        test("getFoo test") {
            val actual = fooService.getFoo()
            actual shouldBe Foo("id", "foo")
        }
    }
}

@Service
class FooService {
    fun getFoo(): Foo {
        return Foo("id", "foo")
    }
}

data class Foo(
    val id: String,
    val title: String,
)

テストコンテキスト

Spring拡張は、テストが実行されるコルーチンコンテキストを通じてTestContextManagerを使用できるようにする。このインスタンスへのハンドルはtestContextManager()拡張メソッドで取得できる。

これにより、Springが使用しているテストコンテキストを取得できる。

class MySpec(service: UserService) : WordSpec() {
  init {
    "SpringExtension" should {
      "provide the test context manager" {
         println("The context is " + testContextManager().testContext)
      }
    }
  }
}

テストメソッドコールバック

Springには、テストがメソッドであるという概念に基づいたbeforeTestMethodなど、さまざまなテストコールバックがある。この前提はJUnitのような従来のテストフレームワークには適しているが、テストが関数であるKotestのような現代的なテストフレームワークには適用されない。

したがって、ネストされたSpecスタイルを使用する場合、テストメソッドコールバックが実行されるタイミングをカスタマイズできる。デフォルトではリーフノードである。SpringTestLifecycleMode引数を拡張に渡すことで、ルートノードで実行されるよう設定できる。

class ProjectConfig : AbstractProjectConfig() {
   override fun extensions() = listOf(SpringTestExtension(SpringTestLifecycleMode.Root))
}

ファイナルクラス

ファイナルクラスを使用すると、Kotestから次のような警告を受けることがある。

Using SpringListener on a final class. If any Spring annotation fails to work, try making this class open

必要であれば、システムプロパティkotest.listener.spring.ignore.warningをtrueに設定して、この警告を無効化できる。

参照

Kotest IntelliJ Plugin テストエクスプローラー(Test Explorer)

kc@example.com (kc kim) — Sun, 31 Mar 2024 14:10:00 +0900

プラグインは、テストの構造を表示するツールウィンドウビューを提供する。このウィンドウには現在選択されているテストファイルが説明され、そのファイルに定義された spec と、その spec に含まれるテストが含まれる。ツリーレイアウトはテストの構造を反映し、簡単に探索できるようにする。

ツールウィンドウには、定義されている場合、テスト前/後などのライフサイクルコールバックメソッドと、含まれる test factory が表示される。

spec、test、include、callback をクリックすると、ソースエディタ内の該当要素へ直接移動する。

Bang 接頭辞を使用して無効化されたすべてのテストには、別のアイコンが表示される。

このウィンドウから直接テストまたは spec を実行できる(run/debug/run with coverage)。また、このウィンドウにはすべてのテストモジュールが表示され、そのモジュールのすべてのテストを実行できる。

モジュール、コールバック、include は、表示したくない場合にフィルタリングして除外できる。デフォルトでは含まれている。

参照

Test Explorer | Kotest

Kotest プロパティテスト関数(Property Test Functions)

kc@example.com (kc kim) — Mon, 18 Mar 2024 22:01:00 +0900

For All

まず forAll は、プロパティ(Property)をテストする n-arity 関数 (a, ..., n) -> Boolean を受け取る。すべての入力値に対して関数が true を返すと、テストは成功する。

import io.kotest.core.spec.style.StringSpec
import io.kotest.property.forAll

class PropertyExample: StringSpec({
    "String size" {
        forAll<String, String> { a, b ->
            (a + b).length == a.length + b.length
        }
    }
})

この関数は引数型の型パラメータを受け取り、最大 14 個の arity をサポートする。Kotest はこれらの型パラメータを使って、適切な型のランダム値を提供、つまり生成するジェネレーターを探す。

たとえば、forAll<String, Int, Boolean> { a, b, c -> } は、引数 a がランダムな文字列、引数 b がランダムな int、引数 c がランダムな boolean である 3-arity プロパティテストである。

Check All

次に checkAll は、入力に対して単純にアサーションを実行できる n-arity 関数 (a, ..., n) -> Unit を受け取る。このアプローチでは、例外が発生しなければテストは有効と見なされる。次は同じ例を checkAll を使って同じ方法で書き直したものである。

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.string.shouldHaveLength
import io.kotest.property.checkAll

class PropertyExample: StringSpec({
    "String size" {
        checkAll<String, String> { a, b ->
            a + b shouldHaveLength a.length + b.length
        }
    }
})

2 つ目のアプローチは boolean を返すよりも汎用的だが、1 つ目のアプローチはこのライブラリに影響を与えた元の Haskell ライブラリに由来する。

Iterations

デフォルトでは、Kotest はプロパティテストを 1000 回実行する。テストメソッドを呼び出すときに反復回数を指定すると、簡単にカスタマイズできる。

テストを 10,000 回実行するとする。

import io.kotest.core.spec.style.StringSpec
import io.kotest.property.checkAll

class PropertyExample: StringSpec({
    "a many iterations test" {
        checkAll<Double, Double>(10_000) { a, b ->
            // test here
        }
    }
})

ジェネレーターの指定

前の例では、Kotest が型パラメータに基づいて自動的に値を提供することを見た。これは、必要な型の値を生成するジェネレーターを探して行われる。たとえば、自動的に提供される整数ジェネレーターは、負の値、正の値、無限大、0 など、可能なすべての値からランダムな整数を生成する。

これは基本的なテストには適しているが、サンプル空間をより細かく制御したいことも多い。たとえば、特定範囲の数値だけで関数をテストしたい場合がある。その場合は、ジェネレーターを手動で指定する必要がある。

import io.kotest.core.spec.style.StringSpec
import io.kotest.property.Arb
import io.kotest.property.arbitrary.int
import io.kotest.property.forAll

class PropertyExample4 : StringSpec({

    fun isDrinkingAge(a: Int): Boolean =
        a in 19..Int.MAX_VALUE

    "is allowed to drink in Chicago" {
        forAll(Arb.int(21..150)) { a ->
            isDrinkingAge(a) // assuming some function that calculates if we're old enough to drink
        }
    }
    "is allowed to drink in London" {
        forAll(Arb.int(18..150)) { a ->
            isDrinkingAge(a) // assuming some function that calculates if we're old enough to drink
        }
    }
})

2 つのテストが作成され、それぞれのテストで適切な int 範囲を持つジェネレーターを forAll 関数に渡していることがわかる。

組み込みジェネレーターの一覧はこちらを参照する。

参照

Property Test Functions | Kotest

Kotestプロジェクト設定

kc@example.com (kc kim) — Mon, 26 Feb 2024 21:59:00 +0900

依存関係の追加

Kotestを使用するには、まずプロジェクトにライブラリを追加する必要がある。 KotestテストフレームワークはJVM、JavaScript、Nativeでサポートされている。複数のプラットフォームでKotestを使用するには、以下で説明するように各プラットフォームに合わせて設定すればよい。

JVM/Gradle

JVM/GradleプロジェクトでのKotestは、JUnit Platform Gradleプラグインを使用する。 Gradle 4.6以上では、テスト型がTestであるタスクにuseJUnitPlatform()を追加し、Kotest JUnit 5ランチャー依存関係を追加するだけでよい。

Gradle + Groovy（ビルドファイル: build.gradle）を使用する場合:

test {
  useJUnitPlatform()
}

またはGradle + Kotlin（ビルドファイル: build.gradle.kts）を使用する場合:

tasks.withType<Test>().configureEach {
   useJUnitPlatform()
}

続いて、次のようにKotest依存関係を追加する。

repositories {
    mavenCentral()
}

dependencies {
    testImplementation("io.kotest:kotest-runner-junit5:${kotestVersion}")
    // 必要に応じて他のモジュールへの依存関係も追加する。
}

JVM/Maven

JVM/Mavenプロジェクトの場合は、ビルドファイル（pom.xml）に次のような構成が必要である。

JUnitテストのためにSurefireプラグインを構成する必要がある。

<plugin>
   <groupId>org.apache.maven.plugins</groupId>
   <artifactId>maven-surefire-plugin</artifactId>
   <version>2.22.2</version>
</plugin>

その後、Kotest JUnit 5ランナー依存関係を追加する。

<dependencies>
    <dependency>
        <groupId>io.kotest</groupId>
        <artifactId>kotest-runner-junit5</artifactId>
        <version>{kotestVersion}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

Kotlin/JS

TIP

単体テストおよびデータ駆動テストの例とともに、JVM、Native、JavaScriptがすべて構成された動作中のマルチプラットフォームプロジェクトは、以下のサイトで確認できる。 - https://github.com/kotest/kotest-examples-multiplatform ビルドにKotestマルチプラットフォームGradleプラグインを追加する。

例えば、次のようにする。

plugins {
  id("io.kotest.multiplatform") version "5.0.2"
}

エンジン依存関係をcommonTest依存関係ブロックに追加する。

kotlin {
  targets {
    js(IR) { // LEGACY or BOTH are unsupported
      browser() // to compile for the web
      nodejs() // to compile against node
    }
  }

  sourceSets {
    val commonTest by getting {
      dependencies {
        implementation("io.kotest:kotest-framework-engine:$version")
      }
    }
  }
}

CAUTION

Kotlin/JS用の新しいIRコンパイラバックエンドのみがサポートされている。レガシーコンパイラバックエンドでJSをコンパイルする場合、テストにKotestを使用できない。

FunSpec、ShouldSpec、StringSpecを使ってテストを書ける。テストはcommonTestまたはjsTestソースセットに配置できる。gradle checkコマンドを使ってテストを実行する。

JavaScriptテストエンジンは、JVMテストエンジンと比べると機能が制限されている。最大の制限は、Kotlinが実行時にアノテーションをJavaScriptコードへ公開しないため、アノテーションベースの構成が動作しないことである。

NOTE

JavaScript用のテストはネストできない。これは、基盤となるJavaScriptテストランナー（MochaやKarmaなど）が親テストでコルーチンと互換性のあるPromiseをサポートしておらず、Kotestではすべてのテストスコープがコルーチンであるためである。そのため、サポートされるSpecは`FunSpec`、`ShouldSpec`、`StringSpec`に限定される。

INFO

IntelliJ Kotestプラグインは、緑色の実行アイコンを使ってIDEから直接、通常、Native、JSテストを実行することをサポートしていない。Gradle経由での実行のみがサポートされる。

Kotlin/Native

Kotlin/Nativeプロジェクトでも、Kotlin/JSプロジェクトと同様にKotestマルチプラットフォームGradleプラグインを追加する必要がある。

plugins {
  id("io.kotest.multiplatform") version "5.0.2"
}

エンジン依存関係をcommonTest依存関係ブロックに追加する。

kotlin {
  targets {
    linuxX64() // can add any supported native targets such as linux, mac, windows etc
  }
}
sourceSets {
  val commonTest by getting {
    dependencies {
      implementation("io.kotest:kotest-framework-engine:$version")
    }
  }
}

テストはcommonTestまたは特定のNativeソースセットに配置できる。gradle checkコマンドを使ってテストを実行する。

Nativeテストエンジンは、JVMテストエンジンと比べると機能が制限されている。最大の制限は、Kotlinが実行時にアノテーションをNativeコードへ公開しないため、アノテーションベースの構成が動作しないことである。

参考 IntelliJ Kotestプラグインは、IDEから通常、Native、JSテストを実行することをサポートしていない。Gradleのcheckタスクを使用する必要がある。

Android

INFO

現在、KotestではJVMテストのみが公式にサポートされている。次の手順により、通常はモジュールの`src/test`フォルダにある、Androidフレームワークを必要としない、またはモックされるユニットテストおよび統合テストでKotestを使用できる。

AndroidのKotestはJUnit Platform Gradleプラグインを使用する。そのためには、ビルドファイルでAndroidテストオプションブロックを構成し、その後Kotest JUnit 5ランチャー依存関係を追加する必要がある。

android.testOptions {
   unitTests.all {
      it.useJUnitPlatform()
   }
}

dependencies {
   testImplementation 'io.kotest:kotest-runner-junit5:{version}'
}

Kotestバージョン

ここでは${kotestVersion}に使用したいKotestバージョンを指定する。

2024年4月時点で、Kotestの最新バージョンは2024年3月11日にリリースされた5.8.1である。 https://central.sonatype.com/artifact/io.kotest/kotest-runner-junit5

kotest-runner-junit5とkotest-runner-junit5-jvmの違いは？

KotestテストをJUnit 5テストエンジンとして実行するための基本的なランナーには、`jvm`が付いたバージョンと付いていないバージョンの2種類が存在する。この2つのバージョンの違いは、Kotestがどこで使用されるかによって異なる。 - **kotest-runner-junit5**: - このモジュールはKotestテストエンジンとJUnit 5を統合し、KotestテストをJUnit 5テストとして実行できるようにする。このモジュールはKotlin Multiplatformプロジェクトで使用され、複数のプラットフォーム（JVM、JS、Nativeなど）でJUnit 5とともにKotestを実行できるよう支援する。 - **kotest-runner-junit5-jvm**: - このモジュールはJVM上でKotlinで書かれたコードに対するJUnit 5テストを実行するために使用される。このモジュールはJVMプラットフォームに特化しており、KotestテストをJUnit 5で実行するために必要なすべての構成を提供する。各モジュールは、それぞれのプラットフォームに応じてKotestテストをJUnit 5テストとして実行できるよう支援する。この統合により、Kotestをさまざまな環境で使用でき、JUnit 5との互換性を保証して、Kotestを既存のテストフレームワークと統合できる。

IntelliJ IDEAでKotest環境を作る

IntelliJ IDEAでKotestを動かすには、Kotestプラグインをインストールする必要がある。

[Setting]-[Plugins]へ移動し、kotestを検索してインストールする。

参考

Setup | Kotest

Kotest Ktor拡張

kc@example.com (kc kim) — Sat, 13 Apr 2024 21:45:00 +0900

kotest-assertions-ktorモジュールは、Ktorアプリケーションに対するレスポンスmatcherを提供する。サーバーサイドテストサポートを使用する場合はTestApplicationResponse向けのmatcherがあり、Ktor HTTPクライアントを使用する場合はHttpResponse向けのmatcherがある。

Ktor matcherを追加するには、プロジェクトに次の依存関係を追加する必要がある。

io.kotest.extensions:kotest-assertions-ktor:${version}

サーバーサイドテストサポートとともにmatcherを使用する例である。

withTestApplication({ module(testing = true) }) {
   handleRequest(HttpMethod.Get, "/").apply {
      response shouldHaveStatus HttpStatusCode.OK
      response shouldNotHaveContent "failure"
      response.shouldHaveHeader(name = "Authorization", value = "Bearer")
      response.shouldNotHaveCookie(name = "Set-Cookie", cookieValue = "id=1234")
   }
}

そして、クライアントサポートの使用例である。

val client = HttpClient(CIO)
val response = client.post("http://mydomain.com/foo")
response.shouldHaveStatus(HttpStatusCode.OK)
response.shouldHaveHeader(name = "Authorization", value = "Bearer")

参照

Ktor | Kotest

Kotest IntelliJ Plugin プロパティ(Properties)

kc@example.com (kc kim) — Sun, 31 Mar 2024 14:21:00 +0900

IntelliJ runner を通じてテストを実行する場合、runner が Gradle を使用するように設定されていないため、gradle.properties または Gradle ビルドファイルで設定したプロパティは選択されない。

実行時システムプロパティをサポートするために、Kotest フレームワークは常にクラスパス上、たとえば src/main/resources にある kotest.properties ファイル内のキー値ペアを探す。

このファイル内のすべてのキー値ペアは、テストが実行される前にシステムプロパティとして設定される。

TIP

`kotest.properties` ファイルに指定されたすべてのプロパティは、Gradle 経由のコマンドラインと IntelliJ プラグイン経由で実行されるテストの両方で動作する。

たとえば、クラスパス上の kotest.properties ファイルに次のように追加する。

foo=bar

すると、次のテストは成功する。

class FooTest : DescribeSpec() {
  init {
    describe("after adding kotest.properties") {
      it("foo should be set") {
         System.getProperty("foo") shouldBe "bar"
      }
    }
  }
}

一般的な使用例

これらの機能を使用しない場合、起動時間を短縮するために Kotest のクラスパススキャン機能を無効にするのが一般的である。これを行うには、kotest.properties ファイルに次のように追加する。

kotest.framework.classpath.scanning.config.disable=true
kotest.framework.classpath.scanning.autoscan.disable=true

プロパティファイル名を指定する

ファイル名を kotest.properties にしたくない場合、または環境に応じて別のファイルをサポートしたい場合は、システムプロパティ kotest.properties.filename を使用してプロパティファイル名を設定できる。

たとえば、kotest.properties.filename=cluster.prd.properties でテストを開始すると、テストが実行される前に cluster.prd.properties というキー値ファイルがロードされる。

参照

Properties | Kotest

Kotest ジェネレーター(Generators)

kc@example.com (kc kim) — Mon, 18 Mar 2024 21:58:00 +0900

生成された値は、sealed class Gen のインスタンスによって提供される。Gen は入力ストリームに似ているが、プロパティテスト値のためのものだと考えられる。各 Gen は、特定の型に対してこれらの値の通常は無限のストリームを提供する。

Kotest には、任意(arbitrary)の値を生成する Arb と、閉じた空間から有限の値集合を生成する Exhaustive という 2 種類のジェネレーターがある。

2 種類のジェネレーターはプロパティテストで混在して使用できる。たとえば、0 から 200 までのすべての偶数(exhaustive)と、100 個のランダムな正の整数(an arb)を使って関数をテストできる。

一部のジェネレーターは JVM でのみ使用できる。完全な一覧はこちらで確認する。

Arbitrary

Arbs は、ハードコードされたエッジケースの集合と、ランダムに選択されたサンプルの無限ストリームという 2 種類の値を生成する。

サンプルは繰り返されることがあり、一部の値はまったく生成されないこともある。たとえば、0 と Int.MAX の間の整数を 1000 個生成しても、可能なすべての値を返すことはできず、一部の値は複数回生成される可能性がある。同様に、0 から 500 の間のランダムな整数を 1000 個生成すると、一部の値が複数回現れる可能性がある。

範囲ありまたは範囲なしの数値、Unicode 集合の文字列、任意のリスト、任意のパラメータを持つデータクラス、メール、コードポイント、文字などが一般的な任意値である。

任意値に加えて、arbs はエッジケースを提供できる。Kotest のプロパティテストの設計上の特徴の 1 つは、一部の型の値にはテストに含めたい「一般的な」エッジケースが常に含まれることである。

たとえば、整数を受け取る関数をテストするときは、少なくとも 0、正数、負数でテストしたいはずである。任意値だけが提供される場合、0 が現れる確率はかなり低いため、Kotest は整数に対して常にいくつかの「エッジケース」を提供する。ただし、別途指定した場合は除く。

テスト実行時、フレームワークはサンプルとエッジケースをランダムに交互に使用する。この分割は構成値によって決まり、デフォルトでは 2% がエッジケースに設定されている。

すべての arb にエッジケースがあるわけではないが、最も一般的な型の arb にはエッジケースがある。次は一部の arb で使用されるエッジケースの例である。

ints: 0, 1, -1, Int.MAX_VALUE, Int.MIN_VALUE
double: 0, 1, -1, Double.MAX_VALUE, Double.MIN_VALUE, Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY, Double.NaN
strings: empty string, 最小長の文字列, 最小コードポイント
lists: empty list, 単一要素リスト, 重複要素を持つリスト
maps: empty map
nullable values: null

Exhaustive

Exhaustive は指定された空間のすべての値を生成する。その空間のすべての値が使用されるようにしたい場合に便利である。たとえば enum 値の場合、enum 値からランダムに選択して一部の値が欠落し他の値が重複する可能性を持つよりも、各 enum 値が使用されるようにする方が一般的に有用である。

一般的な exhaustive には、小さなコレクション、enum、boolean 値、リストやセットの冪集合、事前定義された整数範囲、事前定義された文字列範囲が含まれる。

exhaustive がすべての値を提供すると、繰り返し最初から始まるため、入力が必要なテストで exhaustive を使用できる。

例:

enum class Season { Winter, Fall, Spring, Summer }

forAll<Int, Season>(100) { a, season -> ... }

ここでは 100 回の反復を要求しているため、季節の各値が 25 回ずつ提供される。

参照

Generators | Kotest

Kotestの基本的な書き方

kc@example.com (kc kim) — Mon, 26 Feb 2024 21:59:00 +0900

テストコードの書き方

Kotestのインストールと設定が完了したら、テストコードの書き方について見ていく。

Kotlinが提供する言語機能を使うと、テストを定義するための、より強力でシンプルなアプローチを利用できる。テストをJavaファイルのメソッドとして定義しなければならなかった時代は過ぎた。

Kotestでは、テストは本質的にテストロジックを含むTestContext -> Unit関数にすぎない。この関数内で呼び出されたすべてのアサーション文（Kotest用語ではMatchers）は、例外を発生させるとフレームワークに捕捉され、そのテストを失敗または成功として示すために使用される。

テスト関数は手動で定義するのではなく、これらの関数を生成し、ネストできる複数の方法を提供するKotest DSLを使って定義する。DSLは、特定のテストスタイルを実装するクラスを拡張したクラスを作成して記述する。

任意のパスにテストクラスを作成した後、テストスタイルであるSpecクラスを継承する必要がある。

例えば、Fun Specスタイルを使用するには、FunSpecクラスを継承し、testキーワード、名前、実際のテスト関数を使ってテスト関数を作成する。

class MyFirstTestClass : FunSpec({

   test("my first test") {
      1 + 2 shouldBe 3
   }

})

テストコードの内部を書く方法には、主にDSL（Domain-Specific Language）で書く方法と、init {}ブロックを使う方法の2つがある。

この2つの方法について説明する。

DSLで書く

まず、DSL（Domain-Specific Language）で書く方法について説明する。

Kotestはテストを書くためのDSLを提供する。このDSLを使うと、テストをより自然に表現できる。
各テストスタイルに対応するDSLが提供されており、それを使ってテストを構成できる。例えば、StringSpec、WordSpec、FunSpecなどは、それぞれ文字列、単語、関数を使ってテストを定義するDSLを提供する。

これらのDSLはテストを構造化して表現するうえで便利であり、可読性と保守性を向上させる。

import io.kotest.core.spec.style.StringSpec

class MyStringSpec : StringSpec({
    "This is a test" {
        // テストコードを作成する
    }
})

initブロックを指定して書く

Kotlinのinitブロックを使って、テストを初期化し設定できる。これは一般的に、より多くの柔軟性が必要な場合に使用される。

initブロックはテストクラスのコンストラクタ内部に位置し、クラスがインスタンス化されるときに初期化される。そのため、テストクラスのすべてのメソッドでこれを共有できる。

import io.kotest.core.spec.style.StringSpec

class MyStringSpec : StringSpec() {
    init {
        "This is a test" {
            // テストコードを作成する
        }
    }
}

DSLとinitブロックは、それぞれ異なるユースケースや開発者の好みに応じて選択される。より構造化されたテストを書きたい場合はDSLを使用でき、特定の設定が必要な場合はinitブロックを使用できる。

ネストしたテスト

ほとんどのスタイルは、テストをネストする機能を提供する。実際の構文はスタイルごとに異なるが、基本的には外側のテストに使用されるキーワードが異なるだけである。

例えば、Describe Specでは外側のテストをdescribe関数で作成し、内側のテストをit関数で作成する。JavaScriptやRubyの開発者は、それぞれの言語のテストフレームワークで一般的に使われているため、このスタイルをすぐに理解できる。

class NestedTestExamples : DescribeSpec({

   describe("an outer test") {

      it("an inner test") {
        1 + 2 shouldBe 3
      }

      it("an inner test too!") {
        3 + 4 shouldBe 7
      }
   }

})

Kotest用語では、他のテストを含められるテストをテストコンテナ(test containers)と呼び、終端またはリーフノードのテストをテストケース(test cases)と呼ぶ。どちらもテストロジックとアサーションを含めることができる。

動的テスト

テストは単なる関数なので、実行時に検証される。

このアプローチには、テストを動的に生成できるという大きな利点がある。テストが常にメソッドでありコンパイル時に宣言される従来のJVMテストフレームワークとは異なり、Kotestは実行時に条件付きでテストを追加できる。

例えば、リストの要素に基づいてテストを追加できる。

class DynamicTests : FunSpec({

    listOf(
      "sam",
      "pam",
      "tim",
    ).forEach {
       test("$it should be a three letter name") {
           it.shouldHaveLength(3)
       }
    }
})

これにより、実行時に3つのテストが生成される。次のように書くのと同じである。

class DynamicTests : FunSpec({

   test("sam should be a three letter name") {
      "sam".shouldHaveLength(3)
   }

   test("pam should be a three letter name") {
      "pam".shouldHaveLength(3)
   }

   test("tim should be a three letter name") {
     "tim".shouldHaveLength(3)
   }
})

ライフサイクルコールバック

Kotestはテストライフサイクル中のさまざまな時点で呼び出される複数のコールバックを提供する。これらのコールバックは、状態のリセット、テストで使用するリソースの設定と解放などに役立つ。

前述のように、Kotestのテスト関数はテストコンテナまたはテストケースとしてラベル付けされ、包含クラスはSpecとしてラベル付けされる。テスト関数、コンテナ、テストケース、またはSpec自体の前後に呼び出されるコールバックを登録できる。

コールバックを登録するには、コールバックメソッドのいずれかに関数を渡すだけでよい。

例えば、関数リテラルを使ってテストケースの前後にコールバックを追加できる。

class Callbacks : FunSpec({

   beforeEach {
      println("Hello from $it")
   }

   test("sam should be a three letter name") {
      "sam".shouldHaveLength(3)
   }

   afterEach {
      println("Goodbye from $it")
   }
})

ファイル内でのコールバックの順序は重要ではない。例えば、必要ならafterEachブロックをクラスの最初に配置してもよい。

共通コードを抽出するには、名前付き関数を作成して複数のファイルで再利用できる。例えば、2つ以上のファイルですべてのテスト前にデータベースをリセットしたい場合、次のようにできる。

val resetDatabase: BeforeTest = {
  // truncate all tables here
}

class ReusableCallbacks : FunSpec({

   beforeTest(resetDatabase)

   test("this test will have a sparkling clean database!") {
       // test logic here
   }
})

すべてのコールバックの詳細と、コールバックが呼び出されるタイミングについては、Lifecycle HooksとExtensionsを参照する。

AssertionとMatchers

KotestはさまざまなMatchersを提供し、テスト結果を検証できる。これにより、期待結果と実際の結果を比較し、テストが成功したかを確認できる。例えば、上の例でresult shouldBe 2の部分は、resultが2と等しいかを検証するAssertionである。

そのほかにも多くのMatchersが存在する。以下はKotestを使って主なMatchersを使用するサンプルコードである。

package com.devkuma.kotest.tutorial.assertions

import io.kotest.core.spec.style.FreeSpec
import io.kotest.matchers.collections.shouldContain
import io.kotest.matchers.collections.shouldContainAll
import io.kotest.matchers.collections.shouldContainExactly
import io.kotest.matchers.collections.shouldNotContain
import io.kotest.matchers.ints.shouldBeGreaterThan
import io.kotest.matchers.ints.shouldBeInRange
import io.kotest.matchers.ints.shouldBeLessThan
import io.kotest.matchers.shouldBe
import io.kotest.matchers.shouldNotBe
import io.kotest.matchers.string.shouldBeBlank
import io.kotest.matchers.string.shouldBeEqualIgnoringCase

class MatchersTest : FreeSpec({

    "Matchers" - {
        val number = 10
        "値が期待値と同じかを確認する" {
            number shouldBe 10
        }

        "値が期待値と異なるかを確認する" {
            number shouldNotBe 20
        }

        val blankString = ""
        "文字列が空白だけで構成されているかを確認する" {
            blankString.shouldBeBlank()
        }

        val numbers = listOf(1, 2, 3, 4, 5)

        "コレクションが指定した要素を含むかを確認する" {
            numbers shouldContain 3
        }

        "コレクションが指定した要素を含まないかを確認する" {
            numbers shouldNotContain 6
        }

        "コレクションが指定したすべての要素を含むかを確認する" {
            numbers shouldContainAll listOf(2, 4)
        }

        "コレクションが指定した要素と完全に一致するかを確認する" {
            numbers.shouldContainExactly(1, 2, 3, 4, 5)
        }

        val value = 10
        "値が指定した範囲に含まれるかを確認する" {
            value shouldBeInRange 5..15
        }

        "値が指定した値より大きいかを確認する" {
            value shouldBeGreaterThan 5
        }

        "値が指定した値より小さいかを確認する" {
            value shouldBeLessThan 15
        }

        val message = "Hello, Kotest"
        "大文字小文字を無視して一致するかを確認する" {
            message shouldBeEqualIgnoringCase "HELLO, KOTEST"
        }
    }
})

このほかにも多くのMatchersが存在し、詳細は改めて説明する。

テスト実行とレポート

テストを実行するには、IDEでテストを実行するか、GradleまたはMavenを使ってテストを実行できる。テスト実行後は、テスト結果のレポートを確認できる。Kotestはテスト結果を詳細に記録し、レポートを生成して、開発者がテストの状態を把握できるようにする。

テストを実行するには、IDEで該当するテストクラスやファイルを実行するか、GradleまたはMavenを使ってテストを実行できる。テスト実行後は、各テストケースの結果をレポート形式で確認できる。Kotestは実行されたテストの結果を詳細なレポートとして提供し、テストの成功または失敗を把握できるようにする。

IntelliJ IDEAでテストを実行する

IntelliJ IDEAでテストクラスおよびファイルを選択し、左側のKotestタブを選択すると、下のようにテストケースが表示される。

表示されたテストケースを選択した状態でRunボタンを押すと、下のようにテストコードが実行されることを確認できる。

Gradleテスト実行

KotestをGradle経由で実行する方法は次のとおりである。

テストコマンドの実行

ターミナルまたはコマンドウィンドウでプロジェクトディレクトリへ移動した後、次のコマンドを実行してGradleでプロジェクトのテストを実行する。

./gradlew test

実行が完了すると、テスト結果がターミナルに出力される。以下は、テストが通過した場合にBUILD SUCCESSFULメッセージが出力される例である。

% ./gradlew test

BUILD SUCCESSFUL in 548ms
3 actionable tasks: 3 up-to-date

失敗したテストが発生すると、BUILD FAILEDメッセージが出力される。

 % ./gradlew test 

BUILD SUCCESSFUL in 28s
3 actionable tasks: 3 executed
user@AL02263852 kotest-tutorial % ./gradlew test

> Task :test

com.devkuma.kotest.tutorial.MyTest > My first test FAILED
    io.kotest.assertions.AssertionFailedError at MyTest.kt:9

58 tests completed, 1 failed, 8 skipped

> Task :test FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':test'.
> There were failing tests. See the report at: file:///Users/user/develop/kotlin-tutorial/kotest-tutorial/build/reports/tests/test/index.html

* Try:
> Run with --scan to get full insights.

BUILD FAILED in 26s
3 actionable tasks: 2 executed, 1 up-to-date

テストレポートの確認

テスト実行後、build/reports/testsディレクトリに生成されたHTML形式のテストレポートを確認すると、テスト結果を詳しく見られる。

上で失敗した場合に出力された内容を見ると、テストレポートのリンクが次のように表示されている。

> There were failing tests. See the report at: file:///Users/user/develop/kotlin-tutorial/kotest-tutorial/build/reports/tests/test/index.html

このファイルをブラウザで開くと、下のように表示される。

実行テストが何件か、失敗した件数が何件かが詳細に表示される。

これは成功した場合でも、コマンド出力に表示されないだけで、同じファイル位置にファイルが生成される。

このように、Kotestを使用すると、簡単な設定とテストコード作成で、容易かつ効率的にテストを実行できる。次のセクションでは、Kotestのさらに多くの機能と活用方法について扱う。

参考

Writing Tests | Kotest

Kotestカスタムmatcher(Custom Matchers)

kc@example.com (kc kim) — Sun, 25 Feb 2024 10:28:00 +0900

カスタムmatcher

Kotestでは自分だけのmatcherを簡単に定義できる。

Matcher<T>インターフェースを拡張するだけでよい。ここでTは一致させたい型である。Matcherインターフェースは、MatcherResultのインスタンスを返す1つの関数testを定義する。

interface Matcher<in T> {
   fun test(value: T): MatcherResult
}

このMatcherResult型は、テスト通過 여부を表すブール値を返す関数と2つの失敗メッセージ、計3つの関数を定義する。

interface MatcherResult {
   fun passed(): Boolean
   fun failureMessage(): String
   fun negatedFailureMessage(): String
}

passed
- アサーションを満たすか(true)、満たさないか(false)を表す。
failureMessage
- 一致条件が失敗した場合にユーザーへ送るメッセージである。
- アサーションが失敗したときに表示し、成功させるには何をすべきかを知らせるメッセージである。
- 一般に期待値と実際値の詳細や差分を含めることができる。
negatedFailureMessage
- 一致条件が否定モードで真と評価された場合にユーザーへ送るメッセージである。
- Matcherを否定で使用し、Matcherが失敗する場合に表示すべきメッセージである。
- ここには一般に、述語が失敗すると期待していたことを示す。

カスタムmatcher定義

2つの失敗メッセージの違いは、例を通じてより明確に分かる。文字列に必要な長さがあるか確認するために、文字列向けの長さmatcherを書くと仮定しよう。構文はstr.shouldHaveLength(8)のような形式が必要である。

すると最初のメッセージは"string had length 15 but we expected length 8"のようになるべきである。2つ目のメッセージは"string should not have length 8"のようになるべきである。

まずmatcher型を実装する。

import io.kotest.matchers.Matcher
import io.kotest.matchers.MatcherResult

fun haveLength(length: Int) = Matcher<String> { value ->
    MatcherResult(
        value.length == length,
        { "string had length ${value.length} but we expected length $length" },
        { "string should not have length $length" },
    )
}

エラーメッセージを関数呼び出しでラップし、必要でない場合は評価しないようにする。これは生成に時間がかかるエラーメッセージの場合に重要である。

その後、このmatcherを次のようにshouldおよびshouldNot接頭辞関数へ渡すことができる。

"hello foo" should haveLength(9)
"hello bar" shouldNot haveLength(3)

拡張バリアント

ここではmatcher関数を呼び出し、関数チェーンのために元の値を返す拡張関数を定義する。これはKotestが組み込みmatcherを構成する方法であり、KotestはshouldXYZ命名戦略に合わせようとする。例:

fun String.shouldHaveLength(length: Int): String {
    this should haveLength(length)
    return this
}

fun String.shouldNotHaveLength(length: Int): String {
    this shouldNot haveLength(length)
    return this
}

これにより、次のように呼び出せる。

"hello foo".shouldHaveLength(9)
"hello bar".shouldNotHaveLength(3)

偶数を含むか確認するカスタムmatcher定義

次に、リストに偶数が含まれているか確認するカスタムMatcherを作ってみよう。

次はcontainEvenNumbersというカスタムMatcherを作り、リストに2で割って余りが0になる要素があるかを確認している。

package com.devkuma.kotest.tutorial.assertions.custommatchers

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.*
import io.kotest.matchers.should

fun containEvenNumbers() = Matcher<List<Int>> { value ->
    MatcherResult(
        value.any { it % 2 == 0 },
        { "List should contain even numbers" },
        { "List should not contain even numbers" }
    )
}

fun List<Int>.shouldContainEvenNumbers(): List<Int> {
    this should containEvenNumbers()
    return this
}

infix fun <T> T.should(matcher: (T) -> Unit) = matcher(this)

class ContainEvenNumbersCustomMatcher : FunSpec({
    test("should") {
        val list = listOf(1, 2, 3, 4, 5)
        list should containEvenNumbers()
    }

    test("shouldContainEvenNumbers") {
        val list = listOf(1, 2, 3, 4, 5)
        list.shouldContainEvenNumbers()
    }
})

カスタムmatcherによってテストコードの可読性を高められる。ただし、命名を誤るとかえって逆効果になる可能性がある点に注意しよう。

参照

Custom Matchers | Kotest

Kotestシステム拡張(System Extensions)

kc@example.com (kc kim) — Sun, 31 Mar 2024 16:13:00 +0900

システム拡張

java.lang.Systemを使用するコードをテストする必要がある場合、Kotestはシステムを変更し、各テスト後に復元できる拡張機能を提供する。この拡張はJVMでのみ使用できる。

この拡張を使用するには、プロジェクトに依存関係を追加する。

io.kotest:kotest-extensions-jvm:${version}

CAUTION

この拡張機能は同時(concurrent)テスト実行をサポートしない。JVM仕様により、このような拡張は1つのインスタンスだけを実行できる。たとえば、環境マップは1つだけ存在する必要があるためである。一度に2つ以上のインスタンスを実行しようとすると、結果は未定義である。

システム環境

システム環境拡張を使用すると、システム環境がどのように動作するかをシミュレートできる。つまり、System.getenv()から得られるものをシミュレートできる。

Kotestは、特定スコープのシステム環境を提供するいくつかの拡張関数を提供している。

withEnvironment("FooKey", "BarValue") {
    System.getenv("FooKey") shouldBe "BarValue" // System environment overridden!
}

INFO

JDK 17で`withEnvironment`を使用するには、テストを実行するJVMの引数に`--add-opens=java.base/java.util=ALL-UNNAMED`を追加する必要がある。 Gradleでテストを実行する場合、`build.gradle.kts`に次のように追加する。 ```kotlin tasks.withType().configureEach { jvmArgs("--add-opens=java.base/java.util=ALL-UNNAMED") } ```

この拡張機能では、MapやPairのリストを通じて複数の値を使用することもできる。

withEnvironment(mapOf("FooKey" to "BarValue", "BarKey" to "FooValue")) {
  // Use FooKey and BarKey
}

この関数は、キーと値が現在の環境にない場合は追加し、ある場合は上書きする。関数によって触れられていないキーは環境にそのまま残り、変更されない。

拡張関数の代わりに、提供されているリスナーを使用して、より広いスコープにこの機能を適用することもできる。Spec/テスト単位レベル向けの代替手段と、プロジェクトレベル向けの代替手段がある。

import io.kotest.core.spec.style.FreeSpec
import io.kotest.extensions.system.SystemEnvironmentTestListener
import io.kotest.matchers.shouldBe

class MyTest : FreeSpec() {

    override fun listeners() = listOf(SystemEnvironmentTestListener("foo", "bar"))

    init {
        "MyTest" {
            System.getenv("foo") shouldBe "bar"
        }
    }
}

import io.kotest.core.config.AbstractProjectConfig
import io.kotest.extensions.system.SystemEnvironmentProjectListener

class ProjectConfig : AbstractProjectConfig() {
    override fun listeners() = listOf(SystemEnvironmentProjectListener("foo", "bar"))
}

システムプロパティ拡張

環境拡張と同じ方法で、システムプロパティ(System.getProperties())を上書きできる。

withSystemProperty("foo", "bar") {
    System.getProperty("foo") shouldBe "bar"
}

そして、リスナーとしても提供される。

import io.kotest.core.spec.style.FreeSpec
import io.kotest.extensions.system.SystemPropertyTestListener
import io.kotest.matchers.shouldBe

class MyTest : FreeSpec() {

    override fun listeners() = listOf(SystemPropertyTestListener("foo", "bar"))

    init {
        "MyTest" {
            System.getProperty("foo") shouldBe "bar"
        }
    }
}

システムセキュリティマネージャ

同様に、システムセキュリティマネージャを使用すると、システムセキュリティマネージャ(System.getSecurityManager())を上書きできる。

withSecurityManager(myManager) {
    // Usage of security manager
}

そして、リスナーとしても提供される。

import io.kotest.core.spec.style.FreeSpec
import io.kotest.extensions.system.SecurityManagerListener

class MyTest : FreeSpec() {

    override fun listeners() = listOf(SecurityManagerListener(myManager))

    init {
        // Use my security manager
    }
}

システム終了拡張

コードがSystem.exitを呼び出すかテストしたい場合がある。そのためにシステム終了リスナーを使用できる。リスナーはSystem.exitが呼び出されると例外を投げるため、それを捕捉して確認できる。

import io.kotest.assertions.throwables.shouldThrow
import io.kotest.core.spec.style.FreeSpec
import io.kotest.extensions.system.SpecSystemExitListener
import io.kotest.extensions.system.SystemExitException
import io.kotest.matchers.shouldBe

class MyTest : FreeSpec() {

    override fun listeners() = listOf(SpecSystemExitListener)

    init {
        "Catch exception" {
            val thrown: SystemExitException = shouldThrow<SystemExitException> {
                System.exit(22)
            }

            thrown.exitCode shouldBe 22
        }
    }
}

no-stdout/no-stderrリスナー

デバッグメッセージを残していないか、またはロギングに常にロガーを使用しているかを確認したい場合がある。

このために、KotestはNoSystemOutListenerとNoSystemErrListenerを提供する。これらのリスナーは、それぞれSystem.outまたはSystem.errへ直接メッセージを出力することを許可しない。

    // In Project or in Spec
    override fun listeners() = listOf(NoSystemOutListener, NoSystemErrListener)

Locale/Timezoneリスナー

一部のコードはデフォルトのLocaleおよびTimezoneを使用したり、それに影響を受けたりする。システムデフォルトを直接操作する代わりに、Kotestに処理させることができる。

withDefaultLocale(Locale.FRANCE) {
  println("My locale is now France! Très bien!")
}

withDefaultTimeZone(TimeZone.getTimeZone(ZoneId.of("America/Sao_Paulo"))) {
  println("My timezone is now America/Sao_Paulo! Muito bem!")
}

そして、リスナーとしても提供される。

// In Project or in Spec
override fun listeners() = listOf(
    LocaleTestListener(Locale.FRANCE),
    TimeZoneTestListener(TimeZone.getTimeZone(ZoneId.of("America/Sao_Paulo")))
)

参照

System Extensions | Kotest

Kotest ジェネレーター一覧(Generators List)

kc@example.com (kc kim) — Mon, 18 Mar 2024 22:15:00 +0900

このページには、Kotest の現在のすべてのジェネレーターが一覧されている。ジェネレーターには Arbitrary ジェネレーターと Exhaustive ジェネレーターの 2 種類がある。

ほとんどのジェネレーターはすべてのプラットフォームで使用できる。一部は JVM または JS 専用である。

また、Arrow 用のジェネレーターは別モジュールとして提供される。

ジェネレーター	説明	JVM	JS	Native
Nulls
`arb.orNull()`	null 値を混ぜた arb インスタンスから任意の値を生成する。たとえば `Arb.int().orNull()` は `1, -1, null, 8, 17` などを生成できる。null 生成頻度を制御するオーバーロード版がある。	✓	✓	✓
`arb.orNull(nullProbability)`	定義した確率で null 値を混ぜ、arb インスタンスから任意の値を生成する。	✓	✓	✓
Booleans
`Arb.boolean()`	`Boolean` を生成する `Arb` を返す。	✓	✓	✓
`Arb.booleanArray(length, content)`	`BoolArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
`Exhaustive.boolean()`	true と false を交互に返す。	✓	✓	✓
Chars
`Arb.char(range1, range2,...)`	1 つ以上の指定範囲から生成された任意の文字を返す。複数範囲をサポートすることで、連続していない特定の文字範囲にも値を埋められる。	✓	✓	✓
`Arb.char(List<CharRange>)`	文字範囲リスト全体に分散した文字を返す。たとえば `Arb.char(listOf('A'..'C', 'X'..'Z'))` は A, B, C, X, Y, Z を同じ確率で生成する。
`Arb.charArray(length, content)`	`CharArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
Constants
`Arb.constant(t)`	常に `t` を返す `Arb` を返す。	✓	✓	✓
Bytes
`Arb.byte(min, max)`	`min` から `max` まで、両端を含む `Byte` を生成する `Arb` を返す。エッジケースは `min`, -1, 0, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.positiveByte(min, max)`	`min` から `max` までの正の `Byte` を生成する `Arb` を返す。エッジケースは 1 と `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.negativeByte(min, max)`	`min` から `max` までの負の `Byte` を生成する `Arb` を返す。エッジケースは `min` と -1 で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.byteArray(length, content)`	`ByteArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
`Arb.uByte(min, max)`	`min` から `max` までの `UByte` を生成する `Arb` を返す。エッジケースは `min`, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.uByteArray(length, content)`	`UByteArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
Shorts
`Arb.short(min, max)`	`min` から `max` までの `Short` を生成する `Arb` を返す。エッジケースは `min`, -1, 0, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.positiveShort(min, max)`	`min` から `max` までの正の `Short` を生成する `Arb` を返す。エッジケースは 1 と `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.negativeShort(min, max)`	`min` から `max` までの負の `Short` を生成する `Arb` を返す。エッジケースは `min` と -1 で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.shortArray(length, content)`	`ShortArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
`Arb.uShort(min, max)`	`min` から `max` までの `UShort` を生成する `Arb` を返す。エッジケースは `min`, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.uShortArray(length, content)`	`UShortArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
Ints
`Arb.int(min, max)`	`min` から `max` までの `Int` を生成する `Arb` を返す。エッジケースは `min`, -1, 0, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.positiveInt(min, max)`	`min` から `max` までの正の `Int` を生成する `Arb` を返す。エッジケースは 1 と `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.nonNegativeInt(min, max)`	`min` から `max` までの非負 `Int` を生成する `Arb` を返す。エッジケースは 0, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.negativeInt(min, max)`	`min` から `max` までの負の `Int` を生成する `Arb` を返す。エッジケースは `min` と -1 で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.nonPositiveInt(min, max)`	`min` から `max` までの非正 `Int` を生成する `Arb` を返す。エッジケースは `min`, -1, 0 で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.intArray(length, content)`	`IntArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
`Arb.uInt(min, max)`	`min` から `max` までの `UInt` を生成する `Arb` を返す。エッジケースは `min`, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.uIntArray(length, content)`	`UIntArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
`Exhaustive.ints(range)`	指定した範囲のすべての整数を返す。	✓	✓	✓
`Arb.multiple(k, max)`	最大値までの `k` の倍数を生成する。エッジケースは `0` である。	✓	✓	✓
`Arb.factor(k)`	`k` の因数を生成する。	✓	✓	✓
Longs
`Arb.long(min, max)`	`min` から `max` までの `Long` を生成する `Arb` を返す。エッジケースは `min`, -1, 0, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.positiveLong(min, max)`	`min` から `max` までの正の `Long` を生成する `Arb` を返す。エッジケースは 1 と `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.negativeLong(min, max)`	`min` から `max` までの負の `Long` を生成する `Arb` を返す。エッジケースは `min` と -1 で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.longArray(length, content)`	`LongArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
`Arb.uLong(min, max)`	`min` から `max` までの `ULong` を生成する `Arb` を返す。エッジケースは `min`, 1, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.uLongArray(length, content)`	`ULongArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
`Exhaustive.longs(range)`	指定した範囲のすべての Long を返す。	✓	✓	✓
Floats
`Arb.float(min, max)`	`min` から `max` までの `Float` を生成する `Arb` を返す。エッジケースには `Float.NEGATIVE_INFINITY`, `min`, -1.0, -`Float.MIN_VALUE`, -0.0, 0.0, `Float.MIN_VALUE`, 1.0, `max`, `Float.POSITIVE_INFINITY`, `Float.NaN` があり、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.positiveFloat(min, max)`	`min` から `max` までの正の `Float` を生成する `Arb` を返す。`Float.MIN_VALUE`, 1.0, `max`, `Float.POSITIVE_INFINITY` は指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.negativeFloat(min, max)`	`min` から `max` までの負の `Float` を生成する `Arb` を返す。エッジケースは `Float.NEGATIVE_INFINITY`, `min`, -1.0, -`Float.MIN_VALUE` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.numericFloat(min, max)`	`min` から `max` までの数値 `Float` を生成する `Arb` を返す。エッジケースは `min`, -1.0, -`Float.MIN_VALUE`, -0.0, 0.0, `Float.MIN_VALUE`, 1.0, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.floatArray(length, content)`	`FloatArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
Doubles
`Arb.double(min, max)`	`min` から `max` までの `Double` を生成する `Arb` を返す。エッジケースには `Double.NEGATIVE_INFINITY`, `min`, -1.0, -`Double.MIN_VALUE`, -0.0, 0.0, `Double.MIN_VALUE`, 1.0, `max`, `Double.POSITIVE_INFINITY`, `Double.NaN` があり、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.positiveDouble(min, max)`	`min` から `max` までの正の `Double` を生成する `Arb` を返す。`Double.MIN_VALUE`, 1.0, `max`, `Double.POSITIVE_INFINITY` は指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.negativeDouble(min, max)`	`min` から `max` までの負の `Double` を生成する `Arb` を返す。エッジケースは `Double.NEGATIVE_INFINITY`, `min`, -1.0, -`Double.MIN_VALUE` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.numericDouble(min, max)`	`min` から `max` までの数値 `Double` を生成する `Arb` を返す。エッジケースは `min`, -1.0, -`Double.MIN_VALUE`, -0.0, 0.0, `Double.MIN_VALUE`, 1.0, `max` で、指定範囲に含まれる場合のみ含まれる。	✓	✓	✓
`Arb.doubleArray(length, content)`	`DoubleArray` を生成する `Arb` を返す。`length` は配列長を生成し、`content` は配列内容を生成する。	✓	✓	✓
Enums
`Arb.enum<T>()`	指定した enum から定数をランダムに選択する。	✓	✓	✓
`Exhaustive.enum<T>()`	指定した enum に定義されたすべての定数を反復する。	✓	✓	✓
Regional
`localeArb()`	`en_US` や `ca_ES_VALENCIA` のような Java 形式のロケールを生成する。	✓	✓	✓
`Arb.timezoneCodeThree()`	BST や EST のような 3 文字形式のタイムゾーンを生成する。可能なすべてのタイムゾーンを含むわけではなく、データサンプリングのみに使用される。	✓	✓	✓
`Arb.geoLocation()`	地球上に均一分布するランダムな緯度/経度地点を使って `GeoLocation` オブジェクトを生成する。	✓	✓	✓
Strings
`Arb.string(range)`	指定範囲からランダムに選ばれたサイズで、印字可能なランダム文字列を生成する。範囲を指定しない場合は `(0..100)` が使用される。エッジケースには空文字列と Unicode 文字列が含まれる。	✓	✓	✓
`Arb.stringPattern(pattern)`	RgxGen を使用して、指定したパターンに一致する文字列を生成する。	✓
`Exhaustive.azstring(range)`	指定範囲のすべての AZ 文字列を返す。たとえば範囲が 1..2 の場合、a, b, c, …, yz, zz が含まれる。	✓	✓	✓
`Arb.email(localPartGen, domainGen)`	ローカル部とドメイン部が指定ジェネレーターで生成されるランダム文字列である、任意のメールアドレスを生成する。両方にデフォルト値がある。	✓	✓	✓
`Arb.emailLocalPart()`	任意のローカルメール部を生成する。	✓	✓	✓
`Arb.uuid(type)`	指定した型のランダム UUID を生成する。	✓
`Arb.domain(tlds, labelArb)`	ランダムな TLD、デフォルトでは上位 120 個の TLD のいずれか、とドメイン部分を生成するラベルジェネレーターを使って任意のドメインを生成する。	✓	✓	✓
Builders
`Arb.bind(arbA, arbB, fn)`	指定した 2 つの arb それぞれから値を取得し、その値を提供された関数に渡して値を生成する。	✓	✓	✓
`Arb.bind(arbA, arbB, arbC, fn)`	指定した 3 つの arb それぞれから値を取得し、その値を提供された関数に渡して値を生成する。	✓	✓	✓
`Arb.bind(arbA, ...., fn)`	指定した各 arb から値を取得し、その値を提供された関数に渡して値を生成する。	✓	✓	✓
Combinatorics
`Arb.choice(arbs)`	指定した Arb の 1 つをランダムに選択し、それを使って次の要素を生成する。	✓	✓	✓
`Arb.choose(pairs)`	重みに基づいて値を生成する。たとえば `Arb.choose(1 to 'A', 2 to 'B')` は ‘A’ を 33%、‘B’ を 66% 生成する。	✓	✓	✓
`Arb.frequency(list)`	choose の別名。	✓	✓	✓
`Arb.shuffle(list)`	リストのランダム順列を生成する。たとえば `Arb.shuffle(listOf(1,2,3))` は `listOf(3,1,2)`, `listOf(1,3,2)` などを生成できる。	✓	✓	✓
`Arb.subsequence(list)`	インデックス 0 から始まり、空リストを含む、指定リストのランダム部分列を生成する。たとえば `Arb.subsequence(listOf(1,2,3))` は `listOf(1)`, `listOf(1,2)` などを生成できる。	✓	✓	✓
Collections
`Arb.element(collection)`	指定したコレクションの要素の 1 つをランダムに選択する。	✓	✓	✓
`Arb.element(vararg T)`	可変長引数から要素の 1 つをランダムに選択する。	✓	✓	✓
`Arb.list(gen, range)`	指定した要素ジェネレーターによって値が生成されるリストを生成する。各リストのサイズは指定範囲に基づいてランダムに決定される。	✓	✓	✓
`Arb.set(gen, range)`	指定した要素ジェネレーターによって値が生成されるセットを生成する。各セットのサイズは指定範囲に基づいてランダムに決定される。slippage 引数は、基礎 arb が要求サイズを満たすだけの一意な値を十分に生成できない場合に、失敗する前に各要素生成を何回試行するかを指定する。	✓	✓	✓
`Arb.set(gen, range, slippage)`	指定した要素ジェネレーターによって値が生成されるセットを生成する。各セットのサイズは指定範囲に基づいてランダムに決定される。	✓	✓	✓
`Arb<T>.chunked(range)`	このレシーバーの要素で各リストを埋めるリストを生成する。各チャンクサイズは指定範囲内でランダムに選択される。	✓	✓	✓
`Arb<T>.chunked(minSize, maxSize)`	このレシーバーの要素で各リストを埋めるリストを生成する。各チャンクサイズは指定範囲パラメータ内でランダムに選択される。	✓	✓	✓
`Exhaustive.collection(list)`	リストの各要素を 1 つずつ列挙する。	✓	✓	✓
Maps
`Arb.map(Arb<Pair<K,V>>, minSize, maxSize)`	`minSize` と `maxSize` の間のサイズを持つランダムなマップを生成し、各要素は指定したペア arb から生成される。	✓	✓	✓
`Arb.map(Arb<K>, Arb<V>, minSize, maxSize)`	`minSize` と `maxSize` の間のサイズを持つランダムなマップを生成し、各キーは指定したキー arb から、各値は指定した値 arb から生成される。	✓	✓	✓
Tuples
`Arb.pair(arb1, arb2)`	提供された 2 つの `Arb` からペアの各値を取得する `Pair` インスタンスを生成する。	✓	✓	✓
`Arb.triple(arb1, arb2, arb3)`	提供された 3 つの `Arb` からトリプルの各値を取得する `Triple` インスタンスを生成する。	✓	✓	✓
Dates
`Arb.date(range)`	指定範囲内の年を使用して任意の日付を生成する。		✓
`Arb.datetime(range)`	指定範囲内の年を使用して任意の日時を生成する。		✓
`Arb.localDateTime(range)`	指定範囲内の年を使用して任意の `LocalDateTime` を生成する。	✓
`Arb.localDate(range)`	指定範囲内の年を使用して任意の `LocalDate` を生成する。	✓
Durations
`Arb.duration(range)`	指定範囲から任意の duration を生成する。	✓	✓	✓
Kotlinx Date/Time	`io.kotest.extensions:kotest-property-datetime` モジュールが必要。
`Arb.date(yearRange)`	指定範囲内の年と他のフィールドを使って `LocalDate` をランダムに生成する。	✓	✓	✓
`Arb.datetime(yearRange, hourRange, minuteRange, secondRange)`	指定範囲のすべてのフィールドを使って `LocalDateTime` を生成する。	✓	✓	✓
`Arb.instant(range)`	指定範囲からランダムに生成された epoch を持つ `Instant` を生成する。	✓	✓	✓
Networking
`Arb.ipAddressV4()`	a.b.c.d 形式の任意の IP アドレスを生成する。各部分は 0 から 255 の間である。	✓	✓	✓

参照

Generators List | Kotest

Kotestのテストスタイル(Testing Styles)

kc@example.com (kc kim) — Tue, 27 Feb 2024 22:53:00 +0900

テストスタイル

Kotestはさまざまなテストスタイル(Testing Styles)を提供している。ここでは、Kotestがサポートする10種類のテストスタイルを紹介する。

Testing Style	影響を受けたもの
Fun Spec	ScalaTest
String Spec	A Kotest original
Should Spec	A Kotest original
Describe Spec	Javascript frameworks and RSpec
Behavior Spec	BDD frameworks
Word Spec	ScalaTest
Free Spec	ScalaTest
Feature Spec	Cucumber
Expect Spec	A Kotest original
Annotation Spec	JUnit

それぞれのスタイルは特定の構文に従い、状況に応じて選択して使用できる。各テストスタイルにはそれぞれの特徴と長所、短所があるため、プロジェクトの要件に合わせて適切なスタイルを選択できる。

以下では各テストスタイルについて説明し、基本的な使い方を、いずれかのスタイルを継承するサンプルコードで確認する。

FunSpec

FunSpecは関数ベースのテストスタイルである。各テストケースを関数として作成し、テスト本体をその関数内に記述する。

FunSpecを使用すると、テストを説明する文字列引数を指定してtest関数を呼び出し、テスト自体をラムダとして渡すことでテストを作成できる。どのスタイルを使うべきか迷う場合は、このスタイルを使うのがよい。

以下はFunSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe

class FunSpecTest : FunSpec({
    test("FunSpecの例 - 加算テスト") {
        val result = 2 + 2
        result shouldBe 4
    }
})

通常の方法に加えて、xcontextおよびxtestのバリエーションを使用してテストを無効にできる。

class MyTests : FunSpec({
    context("this outer block is enabled") {
        xtest("this test is disabled") {
            // test here
        }
    }
    xcontext("this block is disabled") {
        test("disabled by inheritance from the parent") {
            // test here
        }
    }
})

StringSpec

StringSpecは文字列ベースのテストスタイルである。自然言語に近い構文でテストを記述できる。主に各テストケースを文字列として記述し、テスト本体を波括弧{}内に記述する。

StringSpecは構文を最小限に抑える。テストコードでは、文字列の後にラムダ式を書くだけでよい。

以下はStringSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class StringSpecTest : StringSpec({
    "StringSpecの例 - 加算テスト" {
        val result = 2 + 2
        result shouldBe 4
    }
})

テストに設定を追加することもできる。

class MyTests : StringSpec({
    "strings.length should return size of string".config(enabled = false, invocations = 3) {
        "hello".length shouldBe 5
    }
})

ShouldSpec

ShouldSpecはFunSpecに似ているが、testの代わりにshouldキーワードを使って記述する。主にテストケースの動作を仕様として表現するために使用される。

以下はShouldSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.ShouldSpec
import io.kotest.matchers.shouldBe

class ShouldSpecTest : ShouldSpec({
    should("ShouldSpecの例 - 加算テスト") {
        val result = 2 + 2
        result shouldBe 4
    }
})

テストは1つ以上のコンテキストブロックにネストすることもできる。

class MyTests : ShouldSpec({
    context("String.length") {
        should("return the length of the string") {
            "sammy".length shouldBe 5
            "".length shouldBe 0
        }
    }
})

通常の方法に加えて、xcontextおよびxshouldのバリエーションを使用してテストを無効にできる。

class MyTests : ShouldSpec({
    context("this outer block is enabled") {
        xshould("this test is disabled") {
            // test here
        }
    }
    xcontext("this block is disabled") {
        should("disabled by inheritance from the parent") {
            // test here
        }
    }
})

DescribeSpec

DescribeSpecテストスタイルはdescribe / itキーワードを使用するため、RubyやJavaScriptの背景を持つ人にとってなじみやすいスタイルである。describe構文を使用してテストケースをグループ化し、テストは1つ以上の説明ブロックにネストする必要がある。主にテストケースを説明するために使用される。

以下はDescribeSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.DescribeSpec
import io.kotest.matchers.shouldBe

class DescribeSpecTest : DescribeSpec({
    describe("DescribeSpecの例") {
        it("加算テスト") {
            val result = 2 + 2
            result shouldBe 4
        }
    }
})

通常の方法に加えて、xdescribeおよびxitのバリエーションを使用してテストを無効にできる。

class MyTests : DescribeSpec({
    describe("this outer block is enabled") {
        xit("this test is disabled") {
            // test here
        }
    }
    xdescribe("this block is disabled") {
        it("disabled by inheritance from the parent") {
            // test here
        }
    }
})

BehaviorSpec

振る舞い駆動開発(BDD, Behavior Driven Development)スタイルの書き方である。 given、when、thenブロックを使用してテストを記述する。主要な機能や動作に焦点を当ててテストケースを作成する。

以下はBehaviorSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.BehaviorSpec
import io.kotest.matchers.shouldBe

class BehaviorSpecTest : BehaviorSpec({
    Given("BehaviorSpecの例") {
        When("加算テスト") {
            val result = 2 + 2
            Then("2と2を足すと4になるべきである") {
                result shouldBe 4
            }
        }
    }
})

NOTE

`when`はKotlinのキーワードであるため、バッククォートで囲む必要がある。バッククォートを使いたくない場合は、`Given`、`When`、`Then`のようなタイトルケース版を使用できる。

Given、WhenにAndキーワードを使用して深さを追加することもできる。

class MyTests : BehaviorSpec({
    given("a broomstick") {
        and("a witch") {
            `when`("The witch sits on it") {
                and("she laughs hysterically") {
                    then("She should be able to fly") {
                        // test code
                    }
                }
            }
        }
    }
})

通常の方法に加えて、xgiven、xwhen、xthenのバリエーションを使用してテストを無効にできる。

class MyTests : BehaviorSpec({
    xgiven("this is disabled") {
        When("disabled by inheritance from the parent") {
            then("disabled by inheritance from its grandparent") {
                // disabled test
            }
        }
    }
    given("this is active") {
        When("this is active too") {
            xthen("this is disabled") {
               // disabled test
            }
        }
    }
})

WordSpec

WordSpecは文字列ベースのテストスタイルである。自然言語に近い構文を使用してテストを記述する。 shouldキーワードを使用して、コンテキスト文字列の後にテストをネストする。各テストケースを文字列として記述し、テスト本体をshouldブロック内に記述する。

以下はWordSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.WordSpec
import io.kotest.matchers.shouldBe

class WordSpecTest : WordSpec({
    "WordSpecの例 - 加算テスト" should {
        "2と2を足すと4になるべきである" {
            val result = 2 + 2
            result shouldBe 4
        }
    }
})

また、別のネストレベルを追加できるようにwhenキーワードもサポートしている。whenはKotlinのキーワードであるため、バッククォートまたは大文字のバリエーションを使用する必要がある点に注意する。

class MyTests : WordSpec({
    "Hello" When {
        "asked for length" should {
            "return 5" {
                "Hello".length shouldBe 5
            }
        }
        "appended to Bob" should {
            "return Hello Bob" {
                "Hello " + "Bob" shouldBe "Hello Bob"
            }
        }
    }
})

FreeSpec

FreeSpecは自由形式のテストスタイルである。テストケース間の依存性を減らし、独立してテストを記述できる。

FreeSpecを使用すると、外側のテストでは-(マイナス)キーワードを使用し、最終テストではテスト名だけを使用して、任意の深さでネストできる。

以下はFreeSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.FreeSpec
import io.kotest.matchers.shouldBe

class FreeSpecTest : FreeSpec({
    "FreeSpecの例 - 加算テスト" - {
        val result = 2 + 2
        "2と2を足すと4になるべきである" {
            result shouldBe 4
        }
    }
})

CAUTION

最も内側のテストでは、テスト名の後に`-`(マイナス)キーワードを使用してはいけない。

FeatureSpec

FeatureSpecは機能(Feature)ベースのテストスタイルである。各テストケースを機能またはシナリオに合わせて作成する。

FeatureSpecを使用すると、機能とシナリオを使用できる。これはCucumberを使ったことがある人にはなじみがあるだろう。Cucumberと完全に同じではないが、キーワードはそのスタイルを模倣している。

以下はFeatureSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.FeatureSpec
import io.kotest.matchers.shouldBe

class FeatureSpecTest : FeatureSpec({
    feature("FeatureSpecの例") {
        scenario("加算テスト") {
            val result = 2 + 2
            result shouldBe 4
        }
    }
})

通常の方法に加えて、xfeatureおよびxscenarioのバリエーションを使用してテストを無効にできる。

class MyTests : FeatureSpec({
    feature("this outer block is enabled") {
        xscenario("this test is disabled") {
            // test here
        }
    }
    xfeature("this block is disabled") {
        scenario("disabled by inheritance from the parent") {
            // test here
        }
    }
})

ExpectSpec

テスト仕様をexpect構文を使用して記述する。主に期待結果を明示するために使用される。

ExpectSpecはFunSpecやShouldSpecに似ているが、expectキーワードを使用する。

以下はExpectSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.ExpectSpec
import io.kotest.matchers.shouldBe

class ExpectSpecTest : ExpectSpec({
    context("ExpectSpecの例") {
        expect("加算テスト") {
            val result = 2 + 2
            2 + 2 shouldBe 4
        }
    }
})

テストは1つ以上のコンテキストブロックにネストすることもできる。

class MyTests : ExpectSpec({
    context("a calculator") {
        expect("simple addition") {
            // test here
        }
        expect("integer overflow") {
            // test here
        }
    }
})

通常の方法に加えて、xcontextおよびxexpectのバリエーションを使用してテストを無効にできる。

class MyTests : ExpectSpec({
    context("this outer block is enabled") {
        xexpect("this test is disabled") {
            // test here
        }
    }
    xcontext("this block is disabled") {
        expect("disabled by inheritance from the parent") {
            // test here
        }
    }
})

AnnotationSpec

アノテーションベースのテストスタイルである。特定のアノテーションを使用してテストを記述する。

JUnitから移行する場合、AnnotationSpecはJUnit 4/5のようなアノテーションを使用するSpecである。Specクラスに定義した関数に@Testアノテーションを追加するだけでよい。

JUnitと同様に、before tests/specsとafter tests/specsにアノテーションを追加できる。

@BeforeAll / @BeforeClass
@BeforeEach / @Before
@AfterAll / @AfterClass
@AfterEach / @After

テストを無視するには@Ignoreを使用する。

NOTE

このSpecを使用しても、通常はインポートを調整するだけで済むためJUnitを使う場合と比べて大きな利点はないが、既存テストを比較的簡単に移行できる。

以下はAnnotationSpecのサンプルコードである。

package com.devkuma.kotest.tutorial.testingstyles

import io.kotest.core.spec.style.AnnotationSpec
import io.kotest.matchers.shouldBe

class AnnotationSpecExample : AnnotationSpec() {

    @BeforeEach
    fun beforeTest() {
        println("Before each test")
    }

    @Test
    fun test1() {
        1 shouldBe 1
    }

    @Test
    fun test2() {
        3 shouldBe 3
    }
}

テストの構造化

Kotestでは、テストを構造化するためにcontextブロックを使用し、テスト階層またはグループとしてテストケースを作成できる。これにより、テストを論理的に分類し、関連するテストケースをまとめて管理できる。

例えば、次はテストグループを使用してテストを構造化する例である。

import io.kotest.core.spec.style.FunSpec

class ContextTest : FunSpec({

    context("Calculator tests") {
        test("Addition") {
            // Test logic for addition
        }

        test("Subtraction") {
            // Test logic for subtraction
        }
    }

    context("String tests") {
        test("Length") {
            // Test logic for string length
        }

        test("Concatenation") {
            // Test logic for string concatenation
        }
    }
})

上の例では、contextブロックを使用してテストを分類して分けている。

contextブロックはFunSpec、ShouldSpec、ExpectSpecでのみ使用できる。

参考

Testing Styles | Kotest

Kotest ジェネレーター操作(Generator Operations)

kc@example.com (kc kim) — Mon, 01 Apr 2024 22:53:00 +0900

プロパティテストでなくても、値を返すためだけに Arb を使用したい場合は、次を呼び出せばよい。

val arbA: Arb<A> = ...
val a = arbA.next() // use Random.Default
val a2 = arbA.next(rs) // pass in Random

Filter

Arb があり、値のサブセットを提供する新しい Arb を作成したい場合は、元の Arb で filter を呼び出すことができる。たとえば、偶数を生成する 1 つの方法は、整数ジェネレーターを取得して奇数値をフィルタリングすることである。

val evens = Arb.int().filter { it.value % 2 == 0 }
val odds = Arb.int().filter { it.value % 2 == 1 }

Map

Arb があり、生成された値を変換したい場合は map を使用できる。

val integerStrings: Arb<String> = Arb.int().map { it.toString() }

FlatMap

放出値またはエッジケースが以前の任意放出値に依存する arb がある場合は、flatMap を使用できる。

val dependentArbs: Arb<String> = Arb.of("foo", "bar").flatMap { prefix ->
   Arb.int(1..10).map { integer ->
      "${prefix}-${integer}"
   }
}

Merging

2 つのジェネレーターをマージして、結果要素が両方のジェネレーターから均等にサンプリングされるようにできる。

val merged = arbA.merge(arbB)

そのため、次の例では各ランダムサンプルで "A" または "B" が出る確率が同じになる。

val a = arbitrary { "a" }
val b = arbitrary { "b" }
val ab = a.merge(b)

println(ab.take(1000).groupingBy { it }.eachCount())
// {a=493, b=507}

3 つ以上の arbitrary オブジェクトをマージする場合は、Arb.choice または Arb.choose の方が適していることがある。たとえば次のように使用できる。

Arb.choice(arbA, arbB, arbC) は arbA、arbB、arbC の間で均一サンプリングするために使用できる。
また、各 arbitrary の頻度をより細かく制御するには Arb.choose(4 to arbA, 1 to arbB, 5 to arbC) を使用できる。この例では、arbA、arbB、arbC がそれぞれ 40%、10%、50% の確率でサンプリングされる。

Bind

Bind は、複数の任意値を適用したい場合に便利である。bind を使ってデータクラスの値を構築する方法を見てみる。

data class Person(val name: String, val age: Int)

val personArb: Arb<Person> = Arb.bind(
   Arb.string(),
   Arb.int()
) { name, age -> Person(name, age) }

参照

Generator Operations | Kotest

Kotestテストコンテナ(Testcontainers)拡張

kc@example.com (kc kim) — Sun, 31 Mar 2024 15:11:00 +0900

Testcontainers

Testcontainersは、独立して再利用可能なテスト環境を構築するためのツールである。コンテナベースのテストをサポートし、ローカルマシンで実行されるテスト環境と同じ環境をプログラムで構築できる。KotestはTestcontainersと一緒に使用でき、テストに必要な外部リソースを管理し、より堅牢で信頼できるテストを書くのに役立つ。

Testcontainersを使用する主な利点は次のとおりである。

一貫した環境: 各テストが実行されるたびに一貫した環境を提供し、テスト結果を予測できる。
独立性: 外部リソースをコンテナ化し、テストが互いに影響しないよう保証する。
テスト環境構築の容易さ: コードでテスト環境をプログラム的に構築し管理できる。
多様なコンテナサポート: Docker、Kubernetesなど、さまざまな種類のコンテナをサポートし、多様なテストシナリオを構築できる。

Testcontainersプロジェクトは、テスト内部で使用するのに理想的な一般的なデータベース、Elasticsearch、Kafka、Selenium Webブラウザ、またはその他Dockerコンテナで実行できるあらゆるものの軽量な一時インスタンスを提供する。

Kotestは、データベースおよびKafka向けの特殊な拡張、サポートされるすべてのDockerイメージに対する汎用コンテナサポートなど、複数の拡張機能を提供する追加モジュールを通じてTestcontainersとの統合を提供する。

依存関係の追加

使用するには、Gradleビルドファイルに次の依存関係を追加する必要がある。

dependencies {
    testImplementation("io.kotest.extensions:kotest-extensions-testcontainers:${kotestVersion}")
}

参考: io.kotest.extensionsのGroup IDは、基本Kotest(io.kotest)とは異なる。

Mavenプロジェクトの場合は、次のように依存関係を追加する。

<dependency>
    <groupId>io.kotest.extensions</groupId>
    <artifactId>kotest-extensions-testcontainers</artifactId>
    <version>${kotest.version}</version>
    <scope>test</scope>
</dependency>

Databases

KotestでTestcontainersを使用する方法は簡単である。テストコード内でTestcontainersライブラリを使って必要なコンテナを起動し、テストを実行した後にコンテナを整理すればよい。

たとえば、データベース連携テストを行う場合、テスト開始時にデータベースコンテナを起動し、テスト終了時にコンテナを停止するのが一般的である。

このためにKotestでは、beforeTestとafterTestを使用して、テスト実行前後に必要な作業を実行できる。

以下はKotestとTestcontainersを一緒に使用するサンプルコードである。

import io.kotest.core.spec.style.FreeSpec
import org.testcontainers.containers.PostgreSQLContainer
import org.testcontainers.junit.jupiter.Container
import org.testcontainers.junit.jupiter.Testcontainers

@Testcontainers
class PostgreSqlTest : FreeSpec() {

    companion object {
        @Container
        val postgresContainer: PostgreSQLContainer<Nothing> = PostgreSQLContainer<Nothing>()
            .withDatabaseName("test")
            .withUsername("test")
            .withPassword("test")
            .withExposedPorts(5432)
    }

    override fun beforeTest(testCase: TestCase) {
        postgresContainer.start()
        System.setProperty("DB_URL", postgresContainer.jdbcUrl)
        System.setProperty("DB_USERNAME", postgresContainer.username)
        System.setProperty("DB_PASSWORD", postgresContainer.password)
    }

    override fun afterTest(testCase: TestCase, result: TestResult) {
        postgresContainer.stop()
    }

    init {
        "Database test" {
            // データベーステストコード作成
        }
    }
}

上のコードでは、PostgreSQLコンテナを使用してデータベーステストを行う。@Testcontainersアノテーションを使用してTestcontainersを有効化し、@Containerアノテーションを使用してコンテナを定義する。そしてbeforeTestとafterTestをオーバーライドし、テスト実行前後にコンテナを起動、停止する。

参照

Kotest手がかり(Clues)

kc@example.com (kc kim) — Sun, 17 Mar 2024 21:22:00 +0900

手がかり

NOTE

手がかり(clues)は、Kotestアサーションライブラリを使用する場合にのみ動作する。

経験則として、失敗したテストは良いバグ報告のように見えるべきである。つまり、何が間違っているのか、理想的にはなぜ間違っているのかを知らせるべきである。

失敗したアサーションのエラーメッセージに、何が間違っているのかを知るための十分な情報が含まれている場合もある。

例:

username shouldBe "devkuma"

次のようなエラーが発生することがある。

expected:<"devkuma"> but was:<"devkuma@devkuma.com">

これが失敗すると、単に次のように得られることがある。

<null> should not equal <null>

これはあまり役立たない。ここでwithClueを活用できる。

withClueおよびasClueヘルパーは、アサーションに追加コンテキストを加え、失敗が自ら説明できるようにする。

たとえば、文字列メッセージとともにwithClueを使用できる。

withClue("Name should be present") {
    user.name shouldNotBe null
}

次のようなエラーが発生する。

Name should be present
<null> should not equal <null>

エラーメッセージはかなり改善されたが、まだ完璧ではない。たとえば、データベースを確認するにはユーザーIDが分かると役立つ場合がある。

asClueを使用して、エラーメッセージにユーザーIDを追加できる。

withClue({ "Name should be present (user_id=${user.id})" }) {
    user.name shouldNotBe null
}

また、asClue拡張関数を使用して、任意のオブジェクトを手がかりメッセージに変換することもできる。

{ "Name should be present (user_id=${user.id})" }.asClue {
    user.name shouldNotBe null
}

このメッセージはテストが失敗した場合にのみ生成されるため、コストの高い処理と一緒に使用しても安全である。

TIP

テスト失敗には、失敗したアサーション、テスト名、手がかり、スタックトレースが含まれる。何が失敗し、なぜ失敗したのかを両方分かるように、この方法で使用することを推奨する。これにより、特にテスト作成者の意図をリバースエンジニアリングする場合に、テストを保守しやすくなる。

TIP

アサーションの上にコードコメントを書きたくなる場合は、代わりに`asClue`または`withClue`を使用することを推奨する。テスト失敗、特にCIでは手がかりが表示されるが、コメントは表示されない。

ドメインオブジェクトを手がかりとして使用することもできる。

data class HttpResponse(val status: Int, val body: String)

val response = HttpResponse(404, "the content")

response.asClue {
    it.status shouldBe 200
    it.body shouldBe "the content"
}

次のように出力される。

HttpResponse(status=404, body=the content)
Expected :200
Actual   :404

NOTE

Kotestはすべての`() -> Any?`のような手がかりを遅延手がかりと見なし、それを計算して関数自体に`.toString()`を呼び出す代わりに、結果値に`.toString()`を使用する。ほとんどの場合、これは必要な処理を正確に行うが、手がかりオブジェクトが`() -> Any?`を実装しており、`clue.toString()`を使用したい場合は、手がかりを`{ clue.toString() }.asClue {... }`のように手動でラップすることを推奨する。

ネストされた手がかり

手がかりはネストでき、失敗したアサーションメッセージですべて確認できる。

{ "Verifying user_id=${user.name}" }.asClue {
  "email_confirmed should be false since we've just created the user".asClue {
    user.emailConfirmed shouldBe false
  }
  "login".asClue {
    user.login shouldBe "sksamuel"
  }
}

失敗は次のように表示されることがある。

Verifying user_id=42
email_confirmed should be false since we've just created the user
<true> should equal <false>

参照

Clues | Kotest

Kotestの条件付きテスト(Conditional evaluation)

kc@example.com (kc kim) — Wed, 28 Feb 2024 21:19:00 +0900

Config

Kotestは、テストに設定フラグを指定してテストを無効にできる。この設定フラグには、enabled、enabledIf、enabledOrReasonIfがある。

enabled flags

config関数のenabledパラメータをfalseに設定すると、テストケースを無効にできる。逆に、trueに設定すると有効になる。

enabledパラメータを設定する例を見てみよう。

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class ConfigEnabledTest : StringSpec({

    "常に実行される".config(enabled = true) {
        // このテストは常に実行される。
        1 + 1 shouldBe 2
    }

    "常に実行されない".config(enabled = false) {
        // このテストは実行されない。
        1 + 1 shouldBe 3
    }
})

falseに設定した場合は実行されず、trueに設定した場合は実行される。

同じ仕組みを使用して、特定の条件でのみテストを実行できる。例えば、Apache Commons LangのSystemUtils.IS_OS_LINUXを使用して、Linux環境でのみ特定のテストを実行するといった使い方ができる。

"Linuxの場合のみ実行".config(enabled = IS_OS_LINUX) {
    // このテストはLinuxの場合に実行される。
}

"Macの場合のみ実行".config(enabled = IS_OS_MAC) {
    // このテストはMacの場合に実行される。
}

Enabled if

テストが呼び出されるたびに評価される関数を使用したい場合は、enabledIfを使用できる。この関数は(TestCase) -> Boolean形式であり、実行時にテストの有効化または無効化を評価するときにテストへアクセスできる。

例えば、Linux環境ではない場合に、dangerという単語で始まるすべてのテストを無効にしたい場合は、次のようにできる。

import io.kotest.core.spec.style.StringSpec
import io.kotest.core.test.EnabledIf
import org.apache.commons.lang3.SystemUtils.IS_OS_LINUX

class ConfigEnabledIf : StringSpec({

    val disableDangerOnNotLinux: EnabledIf = { !it.name.testName.startsWith("danger") || IS_OS_LINUX }

    "danger will robinson".config(enabledIf = disableDangerOnNotLinux) {
        // test here
    }

    "very safe will".config(enabledIf = disableDangerOnNotLinux) {
        // test here
    }
})

Enabled or Reason If

有効化フラグの3つ目のバリエーションとして、テストが無効化された理由を返せるenabledOrReasonIfがある。このバリエーションは(TestCase) -> Enabled形式であり、ここでEnabledはスキップ理由を含められる型である。この理由文字列はテストレポートに渡される。

例えば、前述のdangerの例は次のように書き換えられる。

import io.kotest.core.spec.style.StringSpec
import io.kotest.core.test.Enabled
import io.kotest.core.test.TestCase
import org.apache.commons.lang3.SystemUtils

class ConfigEnabledOrReasonIfTest : StringSpec({

    val disableDangerOnFridays: (TestCase) -> Enabled = {
        if (it.name.testName.startsWith("danger") || SystemUtils.IS_OS_LINUX)
            Enabled.disabled("It's a linux, and we don't like danger!")
        else
            Enabled.enabled
    }

    "danger Will Robinson".config(enabledOrReasonIf = disableDangerOnFridays) {
        // test here
    }

    "safe Will Robinson".config(enabledOrReasonIf = disableDangerOnFridays) {
        // test here
    }
})

以下の結果がコンソールに表示される。

Process finished with exit code 0

It's a linux, and we don't like danger!

Focus

KotestにおけるFocusは、特定のテストを実行するときに優先順位を与える機能である。Focusを使用すると、特定のテストやテストグループに焦点を当てて実行できる。これにより、開発者は特定の部分に集中し、デバッグや開発をより効率的に進められる。

Focusの設定方法は簡単である。テスト関数やテストグループの前にf:を付けると、そのテストまたはテストグループがFocusされる。つまり、そのテストと、その範囲内に定義されたすべての子テストだけが実行され、残りのテストは実行されない。

例えば、次はFocusを使用したサンプルコードである。

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class FocusTest: StringSpec({
    "このテストはFocusされない" {
        // このテストは実行されない。
        1 + 1 shouldBe 2
    }

    // このテストはFocusされて実行される。
    "f:を使用したFocusの例" {
        1 + 1 shouldBe 2
    }

    "このテストもFocusされない" {
        // このテストは実行されない。
        1 + 1 shouldBe 2
    }
})

上のコードでは、"f:を使用したFocusの例"テストだけがFocusされて実行される。残りのテストは実行されない。これにより、開発者は重要な部分だけに集中して、より効率的に開発できる。

また、ネストしたテストは親テストが実行された後にのみ検出されるため、フォーカスモードはネストしたテストには機能しない。

Bang

KotestにおけるBang(!)は、そのテストを無視して実行しないように指定するために使用される。これは、特定のテストを現在の状況で実行すべきでない場合に便利である。特に、開発中のテストを一時的に無効にするときに役立つ。特定のテストを完全に削除せず、あとで再び有効にできる。

Bangはテスト関数やテストグループの前に使用する。

例えば、次はBangを使用したサンプルコードである。

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class BangTest : StringSpec({
    "!このテストは実行されない" {
        // このテストは実行されない。
        1 + 1 shouldBe 2
    }

    "このテストは実行される" {
        // このテストは実行される。
        1 + 1 shouldBe 2
    }
})

上のコードでは、接頭辞として!が付いた"!このテストは実行されない"というテストは実行されない。他のテストは実行される。

このようにBangを使用して、特定のテストを一時的に無効にでき、必要になったときに再び有効にできる。

X-Method

KotestにおけるX-Methodは、テストを無効にするために使用されるメタデータである。特定のテスト関数やテストグループの前にxを付けると、そのテストは実行されない。これにより、特定のテストを一時的に無効にし、あとで再び有効にできる。

例えば、次はX-Methodを使用したサンプルコードである。

import io.kotest.core.spec.style.DescribeSpec

class XMethodTest : DescribeSpec({

    xdescribe("このブロックとその子要素は無効化された") {
        it("このテストは実行されない") {
            // disabled test
        }
    }
})

上のコードでは、X-Methodを使用して特定のテストグループとテストを無効にしている。xdescribeは無効化されたグループとテストを表す。残りのテストは実行される。

このようにX-Methodを使用して、特定のテストやテストグループを一時的に無効にでき、あとで必要になったときに再び有効にできる。

`@Ignored`

Kotestにおける@Ignoredアノテーションは、すべてのテスト関数を無効にするために使用される。このアノテーションを使用すると、そのテスト関数は実行されない。これにより、特定のテストを一時的に無効にし、あとで再び有効にできる。

例えば、次は@Ignoredアノテーションを使用したサンプルコードである。

package com.devkuma.conditional.evaluation

import io.kotest.core.annotation.Ignored
import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

@Ignored
class IgnoredTest : StringSpec({
    "このテストは実行されない" {
        // このテストは実行されない。
        1 + 1 shouldBe 3
    }
}) {
    init {
        error("boom") // Specが作成されないため、このエラーは発生しない。
    }
}

上のコードでは、@Ignoredアノテーションを使用してすべてのテストを無効にしている。

このようにして、特定のテスト関数を一時的に無効にでき、必要になったときに再び有効にできる。

`@EnabledIf`

Kotestにおける@EnabledIfアノテーションは、特定の条件が真の場合にのみテスト関数を有効にするために使用される。このアノテーションを使用すると、特定の条件を満たす場合にのみテストを実行できる。

@EnabledIfアノテーションを使用するには、EnabledConditionインターフェースを実装するクラスを作成する必要がある。このインターフェースにはisEnabledメソッドが含まれており、このメソッドでは特定の条件を判定して真または偽を返す。

例えば、次は@EnabledIfアノテーションを使用して、特定の条件に応じてテストを有効にするサンプルコードである。

package com.devkuma.conditional.evaluation

import io.kotest.core.annotation.EnabledCondition
import io.kotest.core.annotation.EnabledIf
import io.kotest.core.spec.Spec
import io.kotest.core.spec.style.StringSpec

import io.kotest.matchers.shouldBe
import kotlin.reflect.KClass

@EnabledIf(MyEnabledCondition::class)
class EnabledIfTest2 : StringSpec({
    "このテストは特定の条件が真の場合に実行される" {
        // このテストはMyEnabledConditionで指定した条件が真の場合に実行される。
        1 + 1 shouldBe 2
    }
})

object MyEnabledCondition : EnabledCondition {
    override fun enabled(kclass: KClass<out Spec>): Boolean {
        // ここでは特定の条件を判定し、真または偽を返す。
        return true // 特定の条件が真ならtrueを返してテストを有効にする。
    }
}

上のコードでは、MyEnabledConditionオブジェクトがEnabledConditionインターフェースを実装している。enabledメソッドでは特定の条件を判定し、真または偽を返す。@EnabledIfアノテーションには、この条件を指定するために使用される。したがって、特定の条件が真の場合にのみ、そのテストが実行される。

このようにして、特定の条件に応じてテストを条件付きで有効にでき、テストが実行される条件を柔軟に制御できる。

Kotest 例外(Exceptions)

kc@example.com (kc kim) — Sun, 17 Mar 2024 21:23:00 +0900

例外

Kotest には、例外を検証するためのアサーションがいくつか用意されている。

shouldThrow を使うと、ブロックが指定した型の例外をスローすることを検証できる。

shouldThrow<IllegalArgumentException> {
    // IllegalArgumentException をスローするコード
}

例外を受け取り、内容を検証することもできる。

val exception = shouldThrow<IllegalArgumentException> {
    // IllegalArgumentException をスローするコード
}

exception.message shouldBe "expected message"

shouldThrow<T> は、スローされた例外が T のサブタイプである場合にも成功する。厳密に同じ例外型であることを確認したい場合は、shouldThrowExactly を使用する。

shouldThrowExactly<IllegalArgumentException> {
    // 正確に IllegalArgumentException をスローするコード
}

何らかの例外がスローされることだけを確認したい場合は、shouldThrowAny を使用する。

shouldThrowAny {
    // 任意の Throwable をスローするコード
}

参照

Exceptions | Kotest

Kotest Kafka (EmbeddedKafkaListener)拡張

kc@example.com (kc kim) — Sun, 10 Mar 2024 20:04:00 +0900

組み込みKafka拡張

Kotestは、組み込みKafkaインスタンスを実行する拡張機能を提供する。これは、Kafka Dockerイメージの使用が問題になる状況で便利に使える。

一般に、Apache Kafkaを使ってメッセージキューベースのシステムを開発またはテストする場合、実際のKafkaサーバーをインストールして設定する過程は手間がかかり時間もかかる。EmbeddedKafkaListenerは、テスト環境でApache Kafkaを組み込み形式で使用できるようにし、この問題を解決する。

依存関係の追加

組み込みKafka拡張機能を使用するには、テストコンパイルパスにio.kotest.extensions:kotest-extensions-embedded-kafkaモジュールを依存関係として追加する必要がある。最新バージョンはMaven Centralで確認できる。

testImplementation("io.kotest.extensions:kotest-extensions-embedded-kafka:<version>")

Configuration

テストクラスにembeddedKafkaListenerリスナーを登録する。

import io.kotest.core.spec.style.FunSpec
import io.kotest.extensions.embedded.kafka.embeddedKafkaListener

class EmbeddedKafkaListenerTest : FunSpec({
    listener(embeddedKafkaListener)
})

または:

import io.kotest.core.spec.style.FunSpec
import io.kotest.extensions.embedded.kafka.embeddedKafkaListener

class EmbeddedKafkaListenerTest : FunSpec() {
    init {
        listener(embeddedKafkaListener)
    }
}

そして、ブローカーはSpecが生成されると開始され、Specが完了すると停止される。

EmbeddedKafkaListenerを使用すると、テスト実行中に組み込みKafkaサーバーが開始および停止される。これにより、テスト実行中に実際のKafkaサーバーへ依存せず、Kafkaベースのアプリケーションをテストできる。

NOTE: 基本の組み込みKafkaライブラリはstateにグローバルオブジェクトを使用する。複数のKafkaインスタンスを同時に開始してはならない。

Consumer / Producer

コンシューマとプロデューサを作成するために、リスナーの便利なメソッドを使用できる。

import io.kotest.assertions.nondeterministic.eventually
import io.kotest.core.spec.style.FunSpec
import io.kotest.extensions.embedded.kafka.embeddedKafkaListener
import io.kotest.matchers.shouldBe
import org.apache.kafka.clients.producer.ProducerRecord
import java.time.Duration
import java.time.temporal.ChronoUnit
import kotlin.time.Duration.Companion.seconds

class EmbeddedKafkaListenerTest : FunSpec({

    listener(embeddedKafkaListener)

    test("send / receive") {

        val producer = embeddedKafkaListener.stringStringProducer()
        producer.send(ProducerRecord("foo", "a"))
        producer.close()

        val consumer = embeddedKafkaListener.stringStringConsumer("foo")
        eventually(10.seconds) {
            consumer.poll(Duration.of(1, ChronoUnit.SECONDS)).first().value() shouldBe "a"
        }
        consumer.close()
    }
})

stringStringProducerとstringStringConsumerメソッドは、キーと値に文字列を受け付けるプロデューサ/コンシューマを返す。バイトペアにも似たメソッドがある。

または、Kafkaインスタンスが配置されたホスト/ポートへアクセスし、直接クライアントを作成することもできる。

class EmbeddedKafkaListenerTest : FunSpec({

  listener(embeddedKafkaListener)
   
  val props = Properties().apply {
      put(CommonClientConfigs.BOOTSTRAP_SERVERS_CONFIG, "${embeddedKafkaListener.host}:${embeddedKafkaListener.port}")
  }
   
  val producer = KafkaProducer<String, String>(props)
   
})

カスタムポートの指定

ポートを指定するリスナーの新しいインスタンスを作成し、デフォルトインスタンスの代わりにそのインスタンスを使用できる。

import io.kotest.assertions.nondeterministic.eventually
import io.kotest.core.spec.style.FunSpec
import io.kotest.extensions.embedded.kafka.EmbeddedKafkaListener
import io.kotest.matchers.shouldBe
import org.apache.kafka.clients.producer.ProducerRecord
import java.time.Duration
import java.time.temporal.ChronoUnit
import kotlin.time.Duration.Companion.seconds

class EmbeddedKafkaCustomPortTest : FunSpec({

    val listener = EmbeddedKafkaListener(5678)
    listener(listener)

    test("send / receive") {

        val producer = listener.stringStringProducer()
        producer.send(ProducerRecord("foo", "a"))
        producer.close()

        val consumer = listener.stringStringConsumer("foo")
        eventually(10.seconds) {
            consumer.poll(Duration.of(1, ChronoUnit.SECONDS)).first().value() shouldBe "a"
        }
        consumer.close()
    }
})

さらにZooKeeperポートも指定できる。

val listener = EmbeddedKafkaListener(kafkaPort = 6005, zookeeperPort = 9005)

参照

Kotest分離モード(Isolation Modes)

kc@example.com (kc kim) — Fri, 01 Mar 2024 10:01:00 +0900

Isolation Modes

Isolation Modesをどのように設定するかによってテスト性能に差が出ることがあり、インスタンスの再利用によるテスト失敗も防げるため、必ず理解しておく必要がある。

Isolation Modeを設定する方法は3つある。IsolationModeというenumで制御でき、InstancePerTest、SingleInstance、InstancePerLeafがある。状況に合わせて必要な方式を使えばよい。

テスト間で共有される状態を初期化できるように、テストを新しいインスタンス内で実行したい場合は分離モードを変更する。

これは次のDSLを使ってisolationModeに値を代入することで設定できる。

class MyTest : WordSpec({
    isolationMode = IsolationMode.SingleInstance
    
    // tests here
})

または、fun isolationMode(): IsolationMode関数をオーバーライドして設定できる。

class MyTest : WordSpec() {
    override fun isolationMode() = IsolationMode.SingleInstance

    init {
        // tests here
    }
}

DANGER

Kotestのデフォルトは単一インスタンスである。これは、このフレームワークのモチーフになったScalaTestや、Jest、Jasmine、その他のJavaScriptフレームワークと同じだが、JUnitとは異なる。

SingleInstance

デフォルトの分離モードであるSingleInstanceは、Specクラスのインスタンスを1つ生成した後、すべてのテストが完了するまで各テストケースを順番に実行する方式である。

このモードではすべてのテスト間で状態を共有できるため、テスト間の依存関係を維持したい場合に便利である。

package com.devkuma.kotest.tutorial.isolation

import io.kotest.core.spec.style.WordSpec
import java.util.*

class SingleInstanceExample : WordSpec({

    val id = UUID.randomUUID()

    "a" should {
        println("a: $id")
        "b" {
            println("b: $id")
        }
        "c" {
            println("c: $id")
        }
    }
})

次は例を実行した結果である。

a: 3823310d-43d3-47a0-953b-fa3afeb39307
b: 3823310d-43d3-47a0-953b-fa3afeb39307
c: 3823310d-43d3-47a0-953b-fa3afeb39307

すべてのテストで同じインスタンスが使われるため、同じIDが3回出力される。

InstancePerTest

次のIsolationMode.InstancePerTestモードでは、内部コンテキストを含むすべてのテストケースに対して新しいSpecが生成される。つまり、外側のコンテキストはSpec自身のインスタンスでスタンドアロンのテストとして実行される。

例を見ると分かりやすい。

package com.devkuma.kotest.tutorial.isolation

import io.kotest.core.spec.IsolationMode
import io.kotest.core.spec.style.WordSpec
import java.util.*

class InstancePerTestExample : WordSpec() {

    override fun isolationMode(): IsolationMode = IsolationMode.InstancePerTest

    val id = UUID.randomUUID()

    init {
        "a" should {
            println("a: $id")
            "b" {
                println("b: $id")
            }
            "c" {
                println("c: $id")
            }
        }
    }
}

次は例を実行した結果である。

a: 19c3b379-a688-428c-b3e8-8cb507bdf083
a: ffaff5f6-5c6a-41a9-98b9-52f9ca134dfa
b: ffaff5f6-5c6a-41a9-98b9-52f9ca134dfa
a: 08e42544-def7-4859-8b2b-34bb50fe83b0
c: 08e42544-def7-4859-8b2b-34bb50fe83b0

外側のコンテキスト、つまりテスト"a"が最初に実行され、その後テスト"b"のために再実行され、さらにテスト"c"のために再実行される。 Specクラスのクリーンなインスタンスで毎回変数を再利用したい場合に非常に便利である。

InstancePerLeaf

IsolationMode.InstancePerLeafモードは、内部コンテキストを含むすべてのテストケースに対して新しいインスタンスを生成し、独立して実行する。このモードはテストケース間の状態共有を防ぎ、テストの独立性を保証する。ただし、その分リソースを多く消費する点に注意して使う必要がある。

例で確認してみよう。

package com.devkuma.kotest.tutorial.isolation

import io.kotest.core.spec.IsolationMode
import io.kotest.core.spec.style.WordSpec
import java.util.*

class InstancePerLeafExample : WordSpec() {

    override fun isolationMode(): IsolationMode = IsolationMode.InstancePerLeaf

    private val id = UUID.randomUUID()

    init {
        "a" should {
            println("a: $id")
            "b" {
                println("b: $id")
            }
            "c" {
                println("c: $id")
            }
        }
    }
}

次は例を実行した結果である。

a: 71830c57-6ee0-4b1f-8c32-812defac2b1e
b: 71830c57-6ee0-4b1f-8c32-812defac2b1e
a: 480ee65a-df4c-4a78-ac80-b6ae2c85ee20
c: 480ee65a-df4c-4a78-ac80-b6ae2c85ee20

"a"テストが最初に実行され、同じインスタンスで"b"テストが実行される。その後、新しいSpecが生成され、テスト"a"が再実行されてからテスト"c"が実行される。

Global Isolation Mode

システムプロパティを通じてIsolation Modeをグローバルに設定することもできる。

object GlobalIsolationConfiguration : AbstractProjectConfig() {
    override val isolationMode = IsolationMode.SingleInstance
}

参考

Isolation Modes | Kotest

Kotestライフサイクルフック(Lifecycle Hooks)

kc@example.com (kc kim) — Tue, 23 Apr 2024 00:37:00 +0900

テストライフサイクル管理

テストライフサイクル管理とは、各テストケースの実行前後に必要な作業を行うことを意味する。KotestはbeforeTestとafterTestブロックを提供しており、テストライフサイクルを管理できる。これにより、各テストケースの実行前後に必要な設定や後処理を行える。

ライフサイクルフック

各テストケースの実行前後に何らかの作業が必要になることがある。たとえば、データベース接続の設定や後処理、テスト時間の計測など、必要な設定または後処理が考えられる。このとき使うのがライフサイクルフック(Lifecycle Hooks)である。

Kotestは、Spec内で直接定義できるさまざまな種類のフックを提供している。配布可能なプラグインや再利用可能なフックの作成など、より高度な場合には拡張(Extensions)を使用できる。

このセクションの最後には、使用可能なフックの一覧と実行されるタイミングを示している。

Kotestでフックを使う方法はいくつかある。

DSLメソッドで作成する

最初のもっとも簡単な方法は、Spec内で使用できるDSLメソッドを使ってTestListenerを生成し登録することである。たとえば、次のようにbeforeTest、afterTestを直接呼び出せる。

package com.devkuma.kotest.tutorial.lifecycle.ex1

import io.kotest.core.spec.style.WordSpec

class TestSpec : WordSpec({
    beforeTest {
        println("Starting a test $it")
    }

    afterTest { (test, result) ->
        println("Finished spec with result $result")
    }

    "this test" should {
        "be alive" {
            println("devkuma is alive!")
        }
    }
})

次は例を実行した結果である。

Starting a test TestCase(descriptor=TestDescriptor... 省略 ...
Starting a test TestCase(descriptor=TestDescriptor... 省略 ...
Johnny5 is alive!
Finished spec with result Success(duration=6ms)
Finished spec with result Success(duration=51ms)

バックグラウンドでは、これらのDSLメソッドが適切な関数を再定義し、このテストリスナーが実行されるように登録されたTestListenerのインスタンスを生成する。

プロジェクトリスナーのインスタンスを生成するDSLメソッドとしてafterProjectを使用できるが、フレームワークがSpecを検出する段階ではすでにプロジェクトが開始されているため、beforeProjectは存在しない。

関数を受け取るDSLメソッド

これらのDSLメソッドは関数を受け取るため、関数にロジックを切り出して複数の場所で再利用できる。

package com.devkuma.kotest.tutorial.lifecycle.ex2

import io.kotest.core.spec.style.WordSpec
import io.kotest.core.test.TestCase

val startTest: suspend (TestCase) -> Unit = {
    println("Starting a test $it")
}

class TestSpec : WordSpec({

    // used once
    beforeTest(startTest)

    "this test" should {
        "be alive" {
            println("devkuma is alive!")
        }
    }
})

class OtherSpec : WordSpec({

    // used twice
    beforeTest(startTest)

    "this test" should {
        "fail" {
            println("boom")
        }
    }
})

次は例を実行した結果である。

Starting a test TestCase(descriptor=TestDescriptor... 省略 ...
boom
Starting a test TestCase(descriptor=TestDescriptor... 省略 ...
devkuma is alive!

Specでコールバック関数を再定義する

2つ目の方法は、Specでコールバック関数を再定義することである。以下の例は1つ目の方法を変形したものである。

package com.devkuma.kotest.tutorial.lifecycle.ex3

import io.kotest.core.spec.style.WordSpec
import io.kotest.core.test.TestCase
class TestSpec : WordSpec() {

    override suspend fun beforeTest(testCase: TestCase) {
        println("Starting a test $testCase")
    }

    init {
        "this test" should {
            "be alive" {
  println("devkuma is alive!")
            }
        }
    }
}

ライフサイクルコールバック

すべてのコールバックを正しく理解するには、指定可能なTestTypeの値を理解することが重要である。

Container: 他のテストを含めることができるコンテナ
Test: ネストされたテストを含めることができないリーフ(Leaf)テスト。つまり、他のテストを呼び出さずに独立して実行できるテスト
Dynamic: コンテナまたはテストになり得るもので、プロパティテストやデータテストのような機能によってテストが動的に追加されるときに使われる

Kotestでは、テストライフサイクルに応じて実行される複数のコールバック関数を提供している。

以下はKotestで使われる各コールバックの説明である。

コールバック	説明
`beforeContainer`	コンテナ(Test container)内のすべてのテストが実行される前に呼び出されるコールバックである。
`afterContainer`	コンテナ(Test container)内のすべてのテストが実行された後に呼び出されるコールバックである。
`beforeEach`	各テストケース(Test case)の実行前に呼び出されるコールバックである。テストごとに個別の設定を行いたい場合に使う。
`afterEach`	各テストケース(Test case)の実行後に呼び出されるコールバックである。テストごとに個別の後処理を行いたい場合に使う。
`beforeAny`	特定のコンテナまたはSpec内のすべてのテストが実行される前に呼び出されるコールバックである。特定のコンテナやSpec内のすべてのテストに共通する設定作業を行いたい場合に使う。
`afterAny`	特定のコンテナまたはSpec内のすべてのテストが実行された後に呼び出されるコールバックである。特定のコンテナやSpec内のすべてのテストに共通する後処理を行いたい場合に使う。
`beforeTest`	各テストメソッド(Test method)の実行前に呼び出されるコールバックである。この関数を使って各テストの設定を行える。 beforeAnyと同じ動作をする。
`afterTest`	各テストメソッド(Test method)の実行後に呼び出されるコールバックである。この関数を使って各テストの後処理を行える。 afterAnyと同じ動作をする。
`beforeSpec`	各Specの実行前に呼び出されるコールバックである。Spec全体に対する設定作業を行いたい場合に使う。たとえば、データベース接続を設定したり、特定のリソースを初期化したりできる。 `IsolationMode`が`SingleInstance`の場合、`prepareSpec`と同じ動作をする。
`afterSpec`	各Specの実行後に呼び出されるコールバックである。Spec全体に対する後処理を行いたい場合に使う。たとえば、データベース接続を閉じたり、特定のリソースを整理したりできる。 `IsolationMode`が`SingleInstance`の場合、`finalizeSpec`と同じ動作をする。このCallbackで例外が発生すると、その後の`beforeSpec`、`AfterSpec`はスキップされる。
`prepareSpec`	Specが実行される前に呼び出されるコールバックで、ユーザー定義の初期化作業を行うために使われる。 `IsolationMode`がSingleInstanceの場合、beforeSpecと同じ動作をする。
`finalizeSpec`	Specが実行された後に呼び出されるコールバックで、ユーザー定義の後処理を行うために使われる。 `IsolationMode`が`SingleInstance`の場合、`afterSpec`と同じ動作をする。
`beforeInvocation`	各テストメソッド(Test method)またはテストケース(Test case)の実行前に呼び出されるコールバックである。 invocation設定がない場合はbeforeTestと同じ動作をする。
`afterInvocation`	各テストメソッド(Test method)またはテストケース(Test case)の実行後に呼び出されるコールバックである。 invocation設定がない場合はafterTestと同じ動作をする。

これらのコールバックは、各テストの実行前後やSpecの実行前後など、さまざまな時点で特定の処理を行えるようにする。各コールバックは対応するタイミングで呼び出され、必要に応じて適切なロジックを実装して使用できる。

beforeAnyとbeforeTestは同じ関数の別名にすぎないが、beforeEachとは異なる。beforeAny、beforeTestはそれぞれTestType.Testの前に呼び出される一方、beforeEachはTestType.ContainerとTestType.Testの前に呼び出される。afterAny、afterTest、afterEachについても同様である。

次のコールバック関数がいつ実行されるかを例で確認する。

package com.devkuma.kotest.tutorial.lifecycle.ex4

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class CallbackTest : StringSpec({

    // 各Specが実行される前に呼び出されるコールバック
    beforeSpec {
        println("beforeSpec: Spec実行前の設定を行う。")
        // Spec全体に対する設定作業を追加する。
    }

    // 各Specが実行された後に呼び出されるコールバック
    afterSpec {
        println("afterSpec: Spec実行後の後処理を行う。")
        // Spec全体に対する後処理を追加する。
    }

    // 各テスト実行前に呼び出されるコールバック
    beforeTest { testCase ->
        println("beforeTest: ${testCase.name.testName}実行前の設定を行う。")
        // ここにテストの共通設定作業を追加する。
    }

    // 各テスト実行後に呼び出されるコールバック
    afterTest { (testCase, testResult) ->
        println("afterTest: ${testCase.name.testName}実行後の後処理を行う。")
        println("結果: $testResult")
        // ここにテストの共通後処理を追加する。
    }

    // すべてのテストが実行される前に呼び出されるコールバック
    beforeAny { testCase ->
        println("beforeAny: ${testCase.name.testName}テスト実行前の設定を行う。")
        // ここにすべてのテストに対する共通設定作業を追加する。
    }

    // すべてのテストが実行された後に呼び出されるコールバック
    afterAny { (testCase, testResult) ->
        println("afterAny:${testCase.name.testName}テスト実行後の後処理を行う。")
        println("結果: $testResult")
        // ここにすべてのテストに対する共通後処理を追加する。
    }

    // 各テスト実行前に呼び出されるコールバック
    beforeEach { testCase ->
        println("beforeEach: ${testCase.name.testName}テスト実行前の設定を行う。")
        // ここにテストの個別設定作業を追加する。
    }

    // 各テスト実行後に呼び出されるコールバック
    afterEach { (testCase, testResult) ->
        println("afterEach: ${testCase.name.testName}テスト実行後の後処理を行う。")
        println("結果: $testResult")
        // ここにテストの個別後処理を追加する。
    }

    // テストケース1
    "TestCase1" {
        println("TestCase1実行。")
        val result = 2 + 2
        result shouldBe 4
    }

    // テストケース2
    "TestCase2" {
        println("'TestCase2'実行。")
        val list = mutableListOf<Int>()
        list.add(1)
        list.add(2)
        list.size shouldBe 2
    }
})

次は上の例を実行した結果である。

beforeSpec: Spec実行前の設定を行う。
beforeEach: TestCase1テスト実行前の設定を行う。
beforeTest: TestCase1実行前の設定を行う。
beforeAny: TestCase1テスト実行前の設定を行う。
TestCase1実行。
afterAny:TestCase1テスト実行後の後処理を行う。 結果: Success(duration=36ms)
afterTest: TestCase1実行後の後処理を行う。 結果: Success(duration=36ms)
afterEach: TestCase1テスト実行後の後処理を行う。 結果: Success(duration=36ms)
beforeEach: TestCase2テスト実行前の設定を行う。
beforeTest: TestCase2実行前の設定を行う。
beforeAny: TestCase2テスト実行前の設定を行う。
'TestCase2'実行。
afterAny:TestCase2テスト実行後の後処理を行う。 結果: Success(duration=1ms)
afterTest: TestCase2実行後の後処理を行う。 結果: Success(duration=1ms)
afterEach: TestCase2テスト実行後の後処理を行う。 結果: Success(duration=1ms)
afterSpec: Spec実行後の後処理を行う。

参考

Lifecycle hooks | Kotest

Kotestモックサーバー(MockServer)

kc@example.com (kc kim) — Sun, 31 Mar 2024 14:47:00 +0900

KotestはMockServerライブラリとの統合のための拡張機能を提供する。

NOTE

ビルドに`io.kotest.extensions:kotest-extensions-mockserver`モジュールを追加する必要がある。

MockServer

MockServerは仮想HTTPサーバーを提供する。このライブラリを使用すると、別途Mockingライブラリ(mockkなど)を使用せず、実際のサーバーと通信するかのようにテストを行える。

KotestはMockServerライブラリとの統合のための拡張機能を提供する。

依存関係の追加

MockServerで使用するには、io.kotest.extensions:kotest-extensions-mockserverモジュールを依存関係に追加する必要がある。最新バージョンはMaven Centralで確認できる。

testImplementation("io.kotest.extensions:kotest-extensions-mockserver:<version>")

Configuration

モックサーバーを使用すると、テストしたいパスに対してハードコードされたインプロセスHTTPサーバーを定義できる。

Kotestで使用するには、テスト対象のSpecにMockServerListenerインスタンスをアタッチすると、Kotestが自動的にライフサイクルを制御する。

モックサーバー接続

その後、MockServerClientを使ってレスポンスを接続するだけでよい。

例:

class MyMockServerTest : FunSpec() {
  init {

      // this attaches the server to the lifeycle of the spec
      listener(MockServerListener(1080))

      // we can use the client to create routes. Here we are setting them up
      // before each test by using the beforeTest callback.
      beforeTest {
         MockServerClient("localhost", 1080).`when`(
            HttpRequest.request()
               .withMethod("POST")
               .withPath("/login")
               .withHeader("Content-Type", "application/json")
               .withBody("""{"username": "foo", "password": "bar"}""")
         ).respond(
            HttpResponse.response()
               .withStatusCode(202)
               .withHeader("X-Test", "foo")
         )
      }

      // this test will confirm the endpoint works
      test("login endpoint should accept username and password json") {

         // using the ktor client to send requests
         val client = HttpClient(CIO)
         val resp = client.post<io.ktor.client.statement.HttpResponse>("http://localhost:1080/login") {
            contentType(ContentType.Application.Json)
            body = """{"username": "foo", "password": "bar"}"""
         }

         // these handy matchers come from the kotest-assertions-ktor module
         resp.shouldHaveStatus(HttpStatusCode.Accepted)
         resp.shouldHaveHeader("X-Test", "foo")
      }
  }
}

上の例ではもちろんモックテスト自体だけをテストしているが、実際のテストをどのように構成できるかを示している。たとえば、テストしたいAPIクライアントがある場合、モックサーバーを使ってAPIパスを構成し、その後APIクライアントのメソッドを呼び出してレスポンスが正しく処理されるか確認できる。

参考

MockServer | Kotest

Kotest シード(Seeds)

kc@example.com (kc kim) — Sun, 31 Mar 2024 13:18:00 +0900

プロパティテストのシード

プロパティテストが実行されると、値はシード(Seed)値から作成されたランダムソースを使用して生成される。デフォルトでは、このシード値はデフォルトの kotlin.random.Random インスタンスを使用してランダムに選択される。ただし、この値を固定したり再利用したりしたい場合がある。

以下に挙げるオプションで上書きしない限り、すべてのテストで使用されるデフォルト値を変更するには、構成値 PropertyTesting.defaultSeed を変更する。

手動でシードを指定する

シードを手動で設定するには、PropTestConfig のインスタンスをプロパティテストメソッドに渡す。テスト失敗を発見し、その値を今後も回帰テストとして実行し続けたい場合にこれを行うことができる。

例:

import io.kotest.core.spec.style.StringSpec
import io.kotest.property.PropTestConfig
import io.kotest.property.forAll

class PropertyExample : StringSpec({
    "String size" {
        forAll<String, String>(PropTestConfig(seed = 127305235)) { a, b ->
            (a + b).length == a.length + b.length
        }
    }
})

TIP

プロパティテストが失敗するたびに、Kotest は使用されたシードを出力する。テストを複製してこのシードを使用するように設定すれば、その値に対する永続的な回帰テストを作成できる。

失敗したシードを再実行する

デフォルトでは、プロパティテストが失敗すると、そのテストで使用されたシードは ~/.kotest/seeds/<spec>/<testname> にあるファイルに記録される。プロパティテストが実行されるたびに、このファイルが存在するかを検出し、ランダムシードの代わりにこのシードを使用する。次にテストが成功すると、シードファイルは削除される。

NOTE

手動で指定したシードは、常に失敗したシードより優先される。

TIP

この機能は `PropertyTesting.writeFailedSeed = false` に設定すると無効にできる。

シード設定時に失敗させる

一部のユーザーは、手動でシードを指定したくない場合がある。開発時にローカルでのみ使用し、チェックインしたくないことがある。その場合、サーバーで PropertyTesting.failOnSeed = false を設定するか、環境変数 kotest.proptest.seed.fail-if-set を false に設定する。

すると、シードが検出された場合にテストスイートが失敗する。

参照

Property Test Seeds | Kotest

Kotest ソフトアサーション(Soft Assertions)

kc@example.com (kc kim) — Sat, 16 Mar 2024 14:25:00 +0900

ソフトアサーション

ソフトアサーションを使うと、複数のアサーションをまとめて実行し、失敗を一度に報告できる。最初の失敗で止めるのではなく、失敗した条件をすべて確認したい場合に便利である。

assertSoftly {
    foo shouldBe bar
    foo should contain(baz)
}

これは JUnit の assertAll と似ている。

assertSoftly に対象を渡すこともできる。ブロック内では、その対象に対してアサーションを実行する。

assertSoftly(foo) {
    shouldNotEndWith("b")
    length shouldBe 3
}

例:

import io.kotest.assertions.assertSoftly
import io.kotest.core.spec.style.FunSpec
import io.kotest.matchers.shouldBe

class SoftAssertionTest : FunSpec({
    test("soft assertions") {
        val person = Person("devkuma", 30)

        assertSoftly(person) {
            name shouldBe "devkuma"
            age shouldBe 30
        }
    }
})

data class Person(val name: String, val age: Int)

プロジェクト設定を通じて、すべてのテストにソフトアサーションを暗黙的に適用するようにも構成できる。

参照

Soft Assertions | Kotest

Kotest 構成(Configuration)

kc@example.com (kc kim) — Thu, 04 Apr 2024 22:53:00 +0900

構成(Configuration)

Kotest は、プロパティテストを実行するときにいくつかの構成オプションを指定する機能を提供する。これは、テストメソッドに PropTestConfig インスタンスを渡すことで行う。

例:

class PropertyExample: StringSpec({
   "String size" {
      forAll<String, String>(PropTestConfig(options here...)) { a,b ->
         (a + b).length == a.length + b.length
      }
   }
})

シード(Seed)

一般的に使用される構成オプションは、ランダムソースに使用される seed を指定することである。このオプションは、テストが実行されるたびに同じ値を繰り返したい場合に使用する。テスト失敗を発見し、その特定の値集合を今後も回帰テストとして実行し続けたい場合に、このオプションを使用できる。

シードの使い方について詳しく見るには、こちらをクリックする。

最小失敗(Min Failure)

デフォルトでは、Kotest は失敗を許可しない。非決定的なテストを複数回実行し、少数の失敗を許容したい場合がある。これは構成で指定できる。

class PropertyExample: StringSpec({
   "some flakey test" {
      forAll<String, String>(PropTestConfig(maxFailure = 3)) { a,b ->
         // max of 3 inputs can fail
      }
   }
})

PropTestListener

プロパティテストでは、各テスト反復ごとにセットアップと破棄を実行する必要がある場合がある。そのために、PropTestConfig に PropTestListener を登録できる。

class PropertyExample: StringSpec({
   "some property test which require setup and tear down in each iteration" {
      forAll<String, String>(PropTestConfig(listeners = listOf(MyPropTestListener))) { a,b ->
         // some assertion
      }
   }
})

参照

Configuration | Kotest

Kotest JUnit XML Format Reporter

kc@example.com (kc kim) — Sun, 31 Mar 2024 16:47:00 +0900

JUnitにはレガシーXMLレポートと呼ばれるXMLレポート生成器が含まれている。多くのツールがこの形式と統合されているため、非常に便利である。しかし、このレポートにはネストされたテスト(nesting tests)という概念がない。そのため、Kotestでネストされたテストスタイルと一緒に使用すると、親テストが孤立した形で含まれる。

この問題を解決するために、Kotestには同じ形式の独自実装があり、親テストを含めるか、名前を折りたたむかを構成できる。

NOTE

ビルドには`io.kotest:kotest-extensions-junitxml`モジュールが必要である。最新バージョンは[Maven Central](https://central.sonatype.com/artifact/io.kotest/kotest-extensions-junitxml)で検索する。

プロジェクトで構成するには、プロジェクト構成を使用してJunitXmlReporterを追加する必要がある。

class MyConfig : AbstractProjectConfig() {
  override fun extensions(): List<Extension> = listOf(
    JunitXmlReporter(
      includeContainers = false, // don't write out status for all tests
      useTestPathAsName = true, // use the full test path (ie, includes parent test names)
      outputDir = "../target/junit-xml" // include to set output dir for maven
    )
  )
}

また、レポーターはシステムプロパティを設定してビルド出力フォルダがどこにあるかを知る必要がある。さらにGradleは、自身でJUnit XMLレポートを生成してはならないことを知る必要がある。Gradleのtestブロックでこれを構成する。

tasks.named<Test>("test") {
  useJUnitPlatform()
  reports {
    junitXml.required.set(false)
  }
  systemProperty("gradle.build.dir", project.buildDir)
}

パラメータ

レポーターには3つのパラメータがある。

includeContainersがtrueの場合、すべての中間テストがレポートに独自のテストとして含まれる。デフォルトはfalseである。
useTestPathAsNameがtrueの場合、完全なテストパスが名前として使用される。つまり、すべての親テスト名が単一文字列として名前に含まれる。
outputDirを設定すると、そのフォルダにレポートが生成される。デフォルトはtest-results/testである。

参考

JUnit XML Format Reporter | Kotest

Kotest インスペクター(Inspectors)

kc@example.com (kc kim) — Mon, 18 Mar 2024 22:15:00 +0900

インスペクター

インスペクターは、コレクションや配列に対する拡張関数である。指定したアサーションが、特定の数またはグループの要素に対して真であるかを検証する。

たとえば、次のコードは xs のうち少なくとも 2 つの値が 0 より大きいことを検証する。

xs.forAtLeast(2) {
    it shouldBeGreaterThan 0
}

次のコードは、xs のどの要素も 0 より大きくないことを検証する。

xs.forNone {
    it shouldBeGreaterThan 0
}

Kotest には次のインスペクターが用意されている。

Inspector	説明
`forAll`	すべての要素でアサーションが成功する必要がある。
`forNone`	すべての要素でアサーションが失敗する必要がある。
`forOne`	ちょうど 1 つの要素でアサーションが成功する必要がある。
`forAtMostOne`	最大 1 つの要素でアサーションが成功する必要がある。
`forAtLeastOne`	少なくとも 1 つの要素でアサーションが成功する必要がある。
`forAtLeast(k)`	少なくとも `k` 個の要素でアサーションが成功する必要がある。
`forAtMost(k)`	最大 `k` 個の要素でアサーションが成功する必要がある。
`forAny`	`forAtLeastOne` の別名。
`forSome`	少なくとも 1 つの要素で成功し、すべての要素では成功しない必要がある。
`forExactly(k)`	ちょうど `k` 個の要素でアサーションが成功する必要がある。

例:

import io.kotest.core.spec.style.FunSpec
import io.kotest.inspectors.forAll
import io.kotest.inspectors.forAtLeast
import io.kotest.inspectors.forNone
import io.kotest.matchers.ints.shouldBeGreaterThan

class NumbersTestWithInspectors : FunSpec({
    test("inspectors") {
        val numbers = listOf(1, 2, 3, 4, 5)

        numbers.forAll {
            it shouldBeGreaterThan 0
        }

        numbers.forAtLeast(2) {
            it shouldBeGreaterThan 3
        }

        numbers.forNone {
            it shouldBeGreaterThan 10
        }
    }
})

参照

Inspectors | Kotest

Kotest基本拡張(Extensions)

kc@example.com (kc kim) — Mon, 12 Feb 2024 01:47:00 +0900

拡張機能

拡張(Extensions)は、再利用可能なライフサイクルフックである。実際、ライフサイクルフック自体も内部的には拡張のインスタンスとして表現される。以前は単純なインターフェースにはリスナーという用語を、高度なインターフェースには拡張という用語を使っていたが、現在は両者を区別せず、2つの用語を混用できる。

拡張を活用すると、テスト実行中に追加の動作を行ったり、ユーザー定義の機能を統合したりできる。拡張を使うことで、テストをより柔軟に制御し拡張できる。

一般にExtensionsは、テスト前後に実行される作業を定義したり、特定の条件でテストを無効化したり、特定の方法でロギングを行ったりできる。Extensionsはリスナー、インターセプター、インターフェースなどの形で提供され、さまざまなシナリオに対応できる。

拡張の基本的な使い方

基本的な使い方は、必要な拡張インターフェースの実装を作成し、それをテスト、Spec、またはプロジェクト全体のProjectConfigに登録することである。

たとえば、以下の例ではSpec前後のリスナーを作成し、それをSpecに登録している。

package com.devkuma.kotest.tutorial.extensions.ex1

import io.kotest.core.listeners.AfterSpecListener
import io.kotest.core.listeners.BeforeSpecListener
import io.kotest.core.spec.Spec

class MyTestListener : BeforeSpecListener, AfterSpecListener {
    override suspend fun beforeSpec(spec: Spec) {
        println("beforeSpec")
    }
    override suspend fun afterSpec(spec: Spec) {
        println("afterSpec")
    }
}

この拡張機能を適用するには、extension関数で次のようにリスナーを指定する。

package com.devkuma.kotest.tutorial.extensions.ex1

import io.kotest.core.spec.style.WordSpec

class TestSpec : WordSpec({
    extension(MyTestListener())
    
    "testSpec" should {
        println("testSpec")
    }
})

次は例を実行した結果である。

beforeSpec
testSpec
afterSpec

Spec内に登録されたすべての拡張は、そのSpecのすべてのテスト、つまりテストファクトリやネストされたテストを含むすべてに使用される。

プロジェクト全体のすべてのSpecに拡張機能を適用するには、@AutoScanアノテーションを指定して登録できる。

以下の例では前後リスナーを作成し、@AutoScanを指定することで全Specに適用している。

package com.devkuma.kotest.tutorial.extensions.ex2

import io.kotest.core.listeners.AfterProjectListener
import io.kotest.core.listeners.BeforeProjectListener

@AutoScan
class ProjectListener : BeforeProjectListener, AfterProjectListener {
    override suspend fun beforeProject() {
        println("beforeProject")
    }

    override suspend fun afterProject() {
        println("afterProject")
    }
}

以下のサンプルコードでは、前の例とは異なり拡張を個別に指定していない。

package com.devkuma.kotest.tutorial.extensions.ex2

import io.kotest.core.spec.style.FunSpec

class ProjectTest1 : FunSpec({
    test("test1") {
        println("test1")
    }
})

class ProjectTest2 : FunSpec({
    test("test2") {
        println("test2")
    }
})

次は例を実行した結果である。

beforeProject
test1
test2
afterProject

CAUTION

一部の拡張はプロジェクトレベルでのみ登録できる。たとえば、Spec内に`BeforeProjectListener`を登録しても、その拡張が発見される時点ではすでにプロジェクトが開始されているため、効果はない。

シンプルな拡張

シンプルな拡張(Simple Extensions)は、Kotestが提供するさまざまなリスナーを使って、テスト実行前後にユーザーが必要な作業を行えるようにする。

以下の表では、テストおよびSpecのライフサイクルイベントを扱う最も基本的な拡張を示しており、その多くはライフサイクルフックと同じである。エンジンの実行方式を変更できる高度な拡張については、高度な拡張を参照すること。

各リスナーの役割と使い方は次のとおりである。

拡張	説明
`BeforeContainerListener`	コンテナ、つまりテストグループが実行される前に呼び出される。主にコンテナ全体を設定する作業に使用される。たとえば、特定のデータベースを初期化したり、外部リソースを設定したりできる。
`AfterContainerListener`	コンテナ、つまりテストグループが実行された後に呼び出される。主にコンテナ後に必要な後処理に使用される。たとえば、データベース接続を閉じたり、外部リソースを解放したりできる。
`BeforeEachListener`	各テストが実行される前に呼び出される。各テスト実行前に共通して必要な設定作業を行える。たとえば、テストデータを初期化したり、特定の状態を設定したりできる。
`AfterEachListener`	各テストが実行された後に呼び出される。各テスト実行後に共通して必要な後処理を行える。たとえば、テスト後に使用したリソースを解放したり、状態を初期化したりできる。
`BeforeTestListener`	各テスト関数が実行される前に呼び出される。各テスト関数実行前に特定の設定作業を行える。たとえば、特定のテストデータを初期化したり、テスト環境を設定したりできる。
`AfterTestListener`	各テスト関数が実行された後に呼び出される。各テスト関数実行後に後処理を行える。たとえば、テスト後に使用したリソースを解放したり、状態を初期化したりできる。
`BeforeInvocationListener`	各パラメータ化テストが実行される前に呼び出される。
`AfterInvocationListener`	各パラメータ化テストが実行された後に呼び出される。
`BeforeSpecListener`	テストSpecが実行される前に呼び出される。
`AfterSpecListener`	テストSpecが実行された後に呼び出される。
`PrepareSpecListener`	テストSpecが実行される前に呼び出され、主に特定の作業を行うための準備を担当する。
`FinalizeSpecListener`	テストSpecが実行された後に呼び出され、主に特定の作業後にリソースを解放するなどの仕上げ作業を担当する。
`BeforeProjectListener`	プロジェクト内のすべてのテストが実行される前に呼び出される。
`AfterProjectListener`	プロジェクト内のすべてのテストが実行された後に呼び出される。

これらのリスナーは、ユーザーがテストの実行前後に必要な作業を行えるようにし、それぞれの役割に応じたタイミングで呼び出される。これにより、テストの柔軟性と再利用性を高められる。

高度な拡張

高度な拡張(Advanced Extensions)は、Kotestが提供するテスト実行過程を細かく制御し、ユーザー定義ロジックを適用できる強力な機能である。

各高度な拡張の役割と機能は次のとおりである。

拡張	説明
`ConstructorExtension`	テストクラスのコンストラクタを変更し、コンストラクタインジェクションを使ってテストを拡張する。
`TestCaseExtension`	各テストケースの実行をカスタマイズし、変更する。
`SpecExtension`	テストSpecの動作を変更し、拡張する。
`SpecRefExtension`	特定のテストSpec参照に対する拡張を行う。
`DisplayNameFormatterExtension`	テストの表示名をフォーマットし、変更する。
`EnabledExtension`	テストを有効化または無効化する。
`ProjectExtension`	プロジェクトレベルの拡張を行い、グローバル設定を制御する。
`SpecExecutionOrderExtension`	テストSpecの実行順序を調整し、制御する。
`TagExtension`	テストにタグを追加し、管理する。
`InstantiationErrorListener`	テストクラスのインスタンス化中に発生したエラーを処理する。
`InstantiationListener`	テストクラスのインスタンス化イベントを処理する。
`PostInstantiationExtension`	インスタンス化後に追加作業を行う。
`IgnoredSpecListener`	無視されたテストSpecを処理する。
`SpecFilter`	特定の条件に従ってテストSpecをフィルタリングする。
`TestFilter`	特定の条件に従ってテストをフィルタリングする。

これらの高度な拡張を使うことで、テスト実行を細かく制御し、望む形にカスタマイズできる。

拡張の活用

System Out Listener

拡張機能の実例として、Kotestが提供するNoSystemOutListenerがある。この拡張機能は、標準出力に出力が書き込まれるとエラーを発生させる。

package com.devkuma.kotest.tutorial.extensions.ex3

import io.kotest.core.spec.style.DescribeSpec
import io.kotest.extensions.system.NoSystemOutListener

class MyTestSpec : DescribeSpec({

    listener(NoSystemOutListener)

    describe("すべてのテストは標準出力に書き込んではならない。") {
        it("標準出力") {
            println("boom") // 失敗
        }
    }
})

次は例を実行した結果である。

io.kotest.extensions.system.SystemOutWriteException
	at io.kotest.extensions.system.NoSystemOutListener$setup$1.error(NoSystemOutExtensions.kt:18)
	at io.kotest.extensions.system.NoSystemOutListener$setup$1.print(NoSystemOutExtensions.kt:23)
	at io.kotest.extensions.system.NoSystemOutListener$setup$1.print(NoSystemOutExtensions.kt:17)
	at java.base/java.io.PrintStream.println(PrintStream.java:1054)

... 以下省略 ...

テストコードにprintln関数が含まれているため標準出力が発生し、エラーになった。

Timer Listener

別の例として、各テストケースにかかった時間を記録する。

次のようにbeforeTestおよびafterTest関数を使って実現できる。

package com.devkuma.kotest.tutorial.extensions.ex4

import io.kotest.core.listeners.AfterTestListener
import io.kotest.core.listeners.BeforeTestListener
import io.kotest.core.test.TestCase
import io.kotest.core.test.TestResult

object TimerListener : BeforeTestListener, AfterTestListener {

    private var started = 0L

    override suspend fun beforeTest(testCase: TestCase) {
        started = System.currentTimeMillis()
    }

    override suspend fun afterTest(testCase: TestCase, result: TestResult) {
        println("Duration of ${testCase.descriptor.parent.id} = " + (System.currentTimeMillis() - started))
    }
}

テストコードでは次のように登録できる。

package com.devkuma.kotest.tutorial.extensions.ex4

import io.kotest.core.spec.style.FunSpec

class TimeTest : FunSpec({
    extensions(TimerListener)

    // tests here
    test("TimeTest") {
        println("TimeTest")
    }
})

次は例を実行した結果である。

TimeTest
Duration of DescriptorId(value=com.devkuma.kotest.tutorial.extensions.exam4.TimeTest) = 8

また、プロジェクト全体に登録することもできる。

object MyConfig : AbstractProjectConfig() {
    override fun extensions(): List<Extension> = listOf(TimerListener)
}

参考

Kotest HTMLレポート(Reporter)

kc@example.com (kc kim) — Sun, 31 Mar 2024 17:03:00 +0900

JUnit XMLを使用するとき、ネストされたテストを通じて出力を生成できるテストでXML結果を生成できる。残念ながら、Gradleはネストされたテストをサポートしないインメモリ結果を使ってHTMLレポートを生成し、別のXMLから結果を取り込むことはできないようである。

この問題を解決するために、KotestにはJUnit XMLで生成されたXMLレポートを基にHTMLレポートを生成できるリスナーがある。

NOTE

次のモジュールが必要である: ビルドに`io.kotest:kotest-extensions-htmlreporter`。最新バージョンは[Maven Central](https://central.sonatype.com/artifact/io.kotest/kotest-extensions-htmlreporter)で検索する。

これを使用するには、プロジェクト構成を通じてリスナーとして追加するだけでよい。

class ProjectConfig : AbstractProjectConfig() {

   override val specExecutionOrder = SpecExecutionOrder.Annotated

    override fun extensions(): List<Extension> = listOf(
        JunitXmlReporter(
            includeContainers = false,
            useTestPathAsName = true,
        ),
        HtmlReporter()
    )
}

そして、テストタスクにhtml.required.set(false)を追加し、Gradleが独自のHTMLレポートを生成しないようにする。

tasks.test {
  useJUnitPlatform()
  reports {
    html.required.set(false)
    junitXml.required.set(false)
  }
  systemProperty("gradle.build.dir", project.buildDir)
}

JunitXmlReporterも追加する。これにより、HTMLレポート生成に必要なXMLレポートが生成される。追加構成は不要で、HTMLレポート生成を開始するだけでよい。

デフォルトでは/to/buildDir/reports/tests/testにレポートを保存するが、outputDirパラメータを変更して修正できる。

参考

HTML Reporter | Kotest

Kotestコルーチン(Coroutines)

kc@example.com (kc kim) — Sun, 31 Mar 2024 13:05:00 +0900

コルーチンディスパッチャのテスト

TestDispatcherは、開発者が仮想クロックを制御し、遅延をスキップできるようにするkotlinx-coroutines-testモジュールが提供する特別なCoroutineDispatcherである。

TestDispatcherは、開発者が仮想クロックを制御し、遅延をスキップできるようにするkotlinx-coroutines-testモジュールが提供する特別なCoroutineDispatcherである。

TestDispatcherは次の操作をサポートする。

currentTimeは現在の仮想時刻を取得する。
runCurrent()はこの仮想時刻に予約されたタスクを実行する。
advanceUntilIdle()は保留中のタスクがなくなるまで、キュー内のすべてのタスクを実行する。
advanceTimeBy(timeDelta)は現在の仮想時刻がtimeDeltaだけ進むまで、キュー内のタスクを実行する。

テストでTestDispatcherを使用するには、テスト設定でcoroutineTestScopeを有効にする。

package com.devkuma.kotest.tutorial.coroutines.ex1

import io.kotest.core.spec.style.FunSpec

class TestDispatcherTest : FunSpec() {
    init {
        test("foo").config(coroutineTestScope = true) {
            // this test will run with a test dispatcher
        }
    }
}

このテスト内では、testCoroutineSchedulerというExtensionを通じてスケジューラへのハンドルを取得できる。このスケジューラを使って時間を操作できる。

import io.kotest.core.test.testCoroutineScheduler

class TestDispatcherTest : FunSpec() {
   init {
      test("advance time").config(coroutineTestScope = true) {
        val duration = 1.days
        // launch a coroutine that would normally sleep for 1 day
        launch {
          delay(duration.inWholeMilliseconds)
        }
        // move the clock on and the delay in the above coroutine will finish immediately.
        testCoroutineScheduler.advanceTimeBy(duration.inWholeMilliseconds)
        val currentTime = testCoroutineScheduler.currentTime
      }
   }
}

SpecレベルでcoroutineTestScopeをtrueに設定すると、Spec内のすべてのテストに対してテストディスパッチャを有効にできる。

class TestDispatcherTest : FunSpec() {
   init {
      coroutineTestScope = true
      test("this test uses a test dispatcher") {
      }
      test("and so does this test!") {
      }
   }
}

最後に、ProjectConfigを使用してモジュール内のすべてのテストに対してテストディスパッチャを有効にできる。

class ProjectConfig : AbstractProjectConfig() {
  override var coroutineTestScope = true
}

コルーチンデバッグ

kotlinx-coroutines-debugは、JVM上のコルーチンに対するデバッグ機能を提供するモジュールである。有効にすると、デバッグエージェントがByteBuddyによってインストールされ、コルーチンが生成、開始、一時停止、再開されるときの情報を取得する。

Kotestはテストごとにデバッグを有効にする機能を提供している。テスト設定でcoroutineDebugProbeを有効にすると、この機能を使用できる。

この機能を有効にすると、テスト内で開始されたすべてのコルーチンは、テスト完了後または例外発生直後にcoroutine dumpへ含まれる。

class CoroutineDebugging : FunSpec() {
   init {
      test("foo").config(coroutineDebugProbes = true) {
         someMethodThatLaunchesACoroutine() // launches a new coroutine
      }
   }
}

coroutine dumpは次のようになる。

Coroutines dump 2021/11/27 22:17:43

Coroutine DeferredCoroutine{Active}@71f1906, state: CREATED
    (Coroutine creation stacktrace)
    at kotlin.coroutines.intrinsics.IntrinsicsKt__IntrinsicsJvmKt.createCoroutineUnintercepted(IntrinsicsJvm.kt:122)
    at kotlinx.coroutines.intrinsics.CancellableKt.startCoroutineCancellable(Cancellable.kt:30)
    at kotlinx.coroutines.BuildersKt__Builders_commonKt.async$default(Builders.common.kt:82)
    at kotlinx.coroutines.BuildersKt.async$default(Unknown Source)
    at com.sksamuel.kotest.engine.coroutines.Wibble$1.invokeSuspend(CoroutineDebugTest.kt:37)
    at com.sksamuel.kotest.engine.coroutines.Wibble$1.invoke(CoroutineDebugTest.kt)

Specレベル構成

Spec内でcoroutineDebugProbes設定を再定義すると、Spec内のすべてのテストに対してコルーチンデバッグを有効にできる。

class CoroutineDebugging : FunSpec() {
  init {

    coroutineDebugProbes = true

    test("foo") {
      // debugging enabled here
    }

    test("bar") {
      // debugging enabled here
    }

  }
}

プロジェクト全体構成

ProjectConfigを使用して、プロジェクト内のすべてのテストに対してコルーチンデバッグを有効にできる。

class ProjectConfig : AbstractProjectConfig() {
  override val coroutineDebugProbes = true
}

参照

Kotest アサーションモード(Assertion Mode)

kc@example.com (kc kim) — Sat, 16 Mar 2024 22:22:00 +0900

Assertion Mode

Kotest フレームワークと Kotest アサーションを使用している場合、アサーションを実行しないテストが実行されたときに、ビルドを失敗させたり stderr に警告を出力したりできる。

これを行うには、スペック内で assertionMode を AssertionMode.Error または AssertionMode.Warn に設定する。

例:

import io.kotest.core.spec.style.FunSpec
import io.kotest.core.test.AssertionMode

class MySpec : FunSpec() {
    init {
        assertions = AssertionMode.Error
        test("this test has no assertions") {
            val name = "devkuma"
            name.length == 7 // this isn't actually testing anything
        }
    }
}

このテストを実行すると、次のような結果が出力される。

Test 'this test has no assertions' did not invoke any assertions

グローバルに設定する場合は、プロジェクト設定またはシステムプロパティ kotest.framework.assertion.mode から設定できる。

NOTE

Assertion Mode は Kotest アサーションにのみ機能し、他のアサーションライブラリには機能しない。

参照

Assertion Mode | Kotest

Kotest Allure拡張

kc@example.com (kc kim) — Sun, 14 Apr 2024 00:32:00 +0900

Allureは、詳細なインタラクティブテストレポートのために設計されたオープンソースフレームワークである。レポートファイルを生成し、それを使用して最終HTMLレポートを作成する方式で動作する。従来のJUnitレポートに似ているが、より高度で詳細なものと考えられる。

TIP

文書を読むより例を見たい場合は、[こちら](https://github.com/kotest/kotest-examples-allure)にサンプルプロジェクトがある。

2つのステップがある。最初のステップはテスト実行時に生データを生成することで、2つ目のステップはそのデータをインタラクティブHTMLレポートへコンパイルすることである。

このモジュールはKotestと一緒にAllureを使用するための統合機能を提供する。開始するには、Gradleビルドファイルに以下の依存関係を追加する。

io.kotest.extensions:kotest-extensions-allure:${kotest.version}

Note: グループIDは基本Kotest依存関係(io.kotest)とは異なるID(io.kotest.extensions)である。

データ収集

Allureにはほとんどのテストフレームワーク向けのデータ収集器があり、このモジュールはKotest向けの統合機能を提供する。モジュールがビルドに追加されたら、プロジェクト構成を使用してグローバルにAllureTestReporterクラスを接続する。

class MyConfig : AbstractProjectConfig {
    override fun listeners() = listOf(AllureTestReporter())
}

これでテストが実行されるたびに、KotestはテストデータをAllure JSON形式で書き出す。

Gradleプラグイン

テストが完了したので、最終レポートへコンパイルできる。

この作業はAllureバイナリを使って手動で行うことも、Allure Gradleプラグインを使用することもできる。Gradleプラグインを使用するには、まずビルドのpluginsブロックにプラグインを追加する。

plugins {
  ...
  id("io.qameta.allure") version "2.8.1"
}

次に、バージョンを設定し自動構成を無効化するため、Allure構成セクションを追加する。AllureはJUnitだけを自動構成でき、Kotestはこの作業を自身で処理するためである。

allure {
  autoconfigure = false
  version = "2.13.1"
}

最後にGradleタスクallureReportを実行すると、./build/reports/allure-reportにレポートが生成され、その中にレポートのindex.htmlエントリポイントを見つけられる。

ビルドディレクトリ設定

Gradleプラグインを使用しない場合、テスト構成でallure.results.directoryシステムプロパティを設定し、ビルドディレクトリがどこにあるかを知らせる必要がある。Gradleプラグインを使用する場合、Gradleプラグインがこの作業を自動で行うため、このステップはスキップできる。

例:

tasks.named<Test>("test") { // or "jvmTest" etc
   useJUnitPlatform()
   systemProperty("allure.results.directory", project.buildDir.toString() + "/allure-results")
}

最終レポート

すべてが正常に完了すると、テスト実行およびレポート生成後に次のような内容が表示される。

参考

Allure | Kotest

Kotest 縮小(Shrinking)

kc@example.com (kc kim) — Sat, 06 Apr 2024 18:59:00 +0900

縮小(Shrinking)

プロパティベーステストで最初に見つかった失敗ケースには、実際にテストを失敗させる原因ではない多くの複雑さが含まれていることがある。縮小とは、プロパティベーステストフレームワークが失敗ケースを単純化し、再現可能な最小ケースを見つける仕組みである。Kotest でジェネレーターが失敗ケースを縮小する方法は、shrinking interface の実装によって定義される。組み込みジェネレーターには通常、フレームワークによって定義されたデフォルト shrinker があり、カスタムジェネレーターにはカスタム shrinker 実装を指定できる。

組み込みジェネレーターの縮小

組み込みジェネレーター(ジェネレーター一覧を参照)には、フレームワークで定義されたデフォルトの縮小関数がある。縮小関数は、テストに失敗した値を入力として受け取り、Kotest がテストに適用できる新しい値のリストを返す。正確な動作はデータ型によって異なる。たとえば文字列の場合、最初または最後の文字を削除して縮小でき、整数の場合は値を小さくしたり半分にしたりできる。また、空文字列や整数 0 のようなエッジケースに対しても縮小動作が定義されている。これらのジェネレーターを使用するテストが失敗すると、縮小が実行される。

Arb.positiveInt().checkAll { i ->
    calculateProperty(i) shouldBe true
}

生成された入力の 1 つでテストが失敗すると、縮小結果が表示される。

Property test failed for inputs

0) 1792716902

Caused by io.kotest.assertions.AssertionFailedError: expected:<1792716902> but was:<0> at
    PropertyBasedTest$1$1$3$1.invokeSuspend(PropertyBasedTest.kt:54)
    PropertyBasedTest$1$1$3$1.invoke(PropertyBasedTest.kt)
    PropertyBasedTest$1$1$3$1.invoke(PropertyBasedTest.kt)
    io.kotest.property.internal.ProptestKt$proptest$3$2.invokeSuspend(proptest.kt:45)

Attempting to shrink arg 1792716902
Shrink #1: 1 pass
Shrink #2: 597572300 fail
Shrink #3: 199190766 fail
Shrink #4: 66396922 fail
Shrink #5: 22132307 fail
Shrink #6: 7377435 fail
Shrink #7: 2459145 fail

[...]

Shrink #999: 29948 pass
Shrink #1000: 44922 pass
Shrink #1001: 59896 pass
Shrink #1002: 89839 fail
Shrink result (after 1002 shrinks) => 89839

Caused by io.kotest.assertions.AssertionFailedError: expected:<89839> but was:<0> at
    PropertyBasedTest$1$1$3$1.invokeSuspend(PropertyBasedTest.kt:54)
    PropertyBasedTest$1$1$3$1.invoke(PropertyBasedTest.kt)
    PropertyBasedTest$1$1$3$1.invoke(PropertyBasedTest.kt)
    io.kotest.property.internal.ShrinkfnsKt$shrinkfn$1$1$smallestA$1.invokeSuspend(shrinkfns.kt:19)

デフォルトでは、Kotest は 1000 回縮小する。この動作は構成できる。たとえば、制限なく縮小を続けたい場合は次のようにする。

Arb.positiveInt().checkAll(PropTestConfig(shrinkingMode = ShrinkingMode.Unbounded)) { i ->
    calculateProperty(i) shouldBe true
}

カスタムジェネレーターの縮小

カスタムジェネレーターには、Kotest で定義された shrinker がない。代わりに、カスタム shrinker を実装できる。以下は、shrinker が値自体の隣にある座標を返す例である。

data class Coordinate(val x: Int, val y: Int)

class CoordinateTest : FunSpec({
    context("Coordinate Transformations") {
        // Shrinker takes the four neighbouring coordinates
        val coordinateShrinker = Shrinker<Coordinate> { c ->
            listOf(
                Coordinate(c.x - 1, c.y),
                Coordinate(c.x, c.y - 1),
                Coordinate(c.x + 1, c.y),
                Coordinate(c.x, c.y + 1),
            )
        }
        val coordinateArb = arbitrary(coordinateShrinker) {
            Coordinate(Arb.nonNegativeInt().bind(), Arb.nonNegativeInt().bind())
        }

        test("Coordinates are always positive after transformation") {
            coordinateArb.checkAll {
                transform(it).x shouldBeGreaterThanOrEqualTo 0
                transform(it).y shouldBeGreaterThanOrEqualTo 0
            }
        }
    }
})

参照

Shrinking | Kotest

Kotest コアマッチャー(Core Matchers)

kc@example.com (kc kim) — Thu, 28 Mar 2024 00:46:00 +0900

kotest-assertions-core モジュールで提供されるマッチャーである。

General
`obj.shouldBe(other)`	指定した `obj` と `other` が等しいことを確認する。
`expr.shouldBeTrue()`	式が true であることを確認する。`expr.shouldBe(true)` と同じである。
`expr.shouldBeFalse()`	式が false であることを確認する。`expr.shouldBe(false)` と同じである。
`shouldThrow<T> { block }`	ブロックが `T` または `T` のサブタイプをスローすることを確認する。
`shouldThrowExactly<T> { block }`	ブロックが正確に `T` をスローすることを確認する。
`shouldThrowAny { block }`	ブロックが任意の `Throwable` をスローすることを確認する。
`shouldThrowMessage(message) { block }`	コードブロックが指定したメッセージを持つ `Throwable` を発生させることを確認する。

Types
`obj.shouldBeSameInstanceAs(other)`	オブジェクトを同一参照で比較する。
`obj.shouldBeTypeOf<T>()`	参照が正確に型 `T` であることを確認する。サブクラスは失敗する。
`obj.shouldBeInstanceOf<T>()`	参照が型 `T` または `T` のサブクラスであることを確認する。
`obj.shouldHaveAnnotation(annotationClass)`	オブジェクトに指定した型のアノテーションがあることを確認する。
`obj.shouldBeNull()`	参照が null であることを確認する。

Comparables
`comp.shouldBeLessThan(other)`	`compareTo` を使って `comp` が `other` より小さいことを確認する。
`comp.shouldBeLessThanOrEqualTo(other)`	`compareTo` を使って `comp` が `other` 以下であることを確認する。
`comp.shouldBeEqualComparingTo(other)`	`compareTo` を使って `comp` が `other` と等しいことを確認する。
`comp.shouldBeEqualComparingTo(other, comparator)`	`comparator.compare` を使って `comp` が `other` と等しいことを確認する。
`comp.shouldBeGreaterThan(other)`	`compareTo` を使って `comp` が `other` より大きいことを確認する。
`comp.shouldBeGreaterThanOrEqualTo(other)`	`compareTo` を使って `comp` が `other` 以上であることを確認する。

Iterator
`iterator.shouldBeEmpty()`	イテレーターに次の値がないことを確認する。
`iterator.shouldHaveNext()`	イテレーターに次の値があることを確認する。

Maps
`map.shouldContain("key", "value")`	マップに `"key"` から `"value"` へのマッピングが含まれることを確認する。
`map.shouldContainAll(other)`	マップが指定したマップのすべてのペアを含むことを確認する。
`map.shouldContainExactly(other)`	マップが指定したマップのペアだけを正確に含み、余分な項目がないことを確認する。
`map.shouldContainKey(key)`	マップに任意の値を持つ指定キーが含まれることを確認する。
`map.shouldContainKeys(keys)`	マップに指定したすべてのキーのマッピングが含まれることを確認する。
`map.shouldContainValue(value)`	マップに指定した値のマッピングが少なくとも 1 つ含まれることを確認する。
`map.shouldContainValues(values)`	マップに指定した値がすべて含まれることを確認する。
`map.shouldBeEmpty()`	マップが空であることを確認する。
`map.shouldMatchAll("k1" to {it shouldBe "v1"}, "k2" to {it shouldBe "v2"}, ...)`	マップのすべての項目が指定したマッチャーに一致できることを検証する。余分なキーは無視される。
`map.shouldMatchExactly("k1" to {it shouldBe "v1"}, "k2" to {it shouldBe "v2"}, ...)`	マップの項目が指定したマッチャーと正確に一致できることを確認する。

Strings
`str.shouldBeBlank()`	文字列が空、または空白のみであることを確認する。
`str.shouldBeEmpty()`	文字列の長さが 0 であることを確認する。
`str.shouldBeLowerCase()`	文字列がすべて小文字であることを確認する。
`str.shouldBeUpperCase()`	文字列がすべて大文字であることを確認する。
`str.shouldContain("substr")`	文字列に指定した部分文字列が含まれることを確認する。このマッチャーは大文字小文字を区別する。
`str.shouldContain(regex)`	文字列に指定した正規表現が含まれることを確認する。
`str.shouldContainADigit()`	文字列に少なくとも 1 つの数字が含まれることを確認する。
`str.shouldContainIgnoringCase(substring)`	大文字小文字を無視して、文字列に部分文字列が含まれることを確認する。
`str.shouldContainOnlyDigits()`	文字列が数字のみ、または空であることを確認する。
`str.shouldBeInteger([radix])`	文字列に int が含まれることを確認し、それを返す。
`str.shouldContainOnlyOnce(substring)`	文字列に部分文字列がちょうど 1 回だけ含まれることを確認する。
`str.shouldEndWith(suffix)`	文字列が指定した接尾辞で終わることを確認する。
`str.shouldHaveLength(length)`	文字列が指定した長さであることを確認する。
`str.shouldHaveLineCount(count)`	文字列が指定した行数を持つことを確認する。
`str.shouldHaveMaxLength(max)`	文字列が指定した最大長より長くないことを確認する。
`str.shouldHaveMinLength(min)`	文字列が指定した最小長より短くないことを確認する。
`str.shouldHaveSameLengthAs(anotherString)`	文字列が別の文字列と同じ長さであることを確認する。
`str.shouldMatch(regex)`	文字列が指定した正規表現と完全に一致することを確認する。
`str.shouldStartWith("prefix")`	文字列が指定した接頭辞で始まることを確認する。
`str.shouldBeEqualIgnoringCase(other)`	大文字小文字を無視して、文字列が別の文字列と等しいことを確認する。
`str.shouldBeTruthy()`	文字列が truthy であることを確認する: `true`, `yes`, `y`, `1` のいずれか。
`str.shouldBeFalsy()`	文字列が falsy であることを確認する: `false`, `no`, `n`, `0` のいずれか。

Numbers
`number.shouldBeBetween(x, y)`	数値が `x` と `y` の間にあり、両端を含むことを確認する。
`number.shouldBeLessThan(n)`	数値が `n` より小さいことを確認する。
`number.shouldBeLessThanOrEqual(n)`	数値が `n` 以下であることを確認する。
`number.shouldBeGreaterThan(n)`	数値が `n` より大きいことを確認する。
`number.shouldBeGreaterThanOrEqual(n)`	数値が `n` 以上であることを確認する。
`number.shouldBeInRange(range)`	数値が指定した範囲に含まれることを確認する。
`number.shouldBeEven()`	数値が偶数であることを確認する。
`number.shouldBeOdd()`	数値が奇数であることを確認する。
`number.shouldBeZero()`	数値が 0 であることを確認する。
`double.shouldBe(value plusOrMinus(tolerance))`	double が許容誤差の範囲内で指定した値と等しいことを確認する。
`double.shouldBePositive()`	double が正数であることを確認する。
`double.shouldBeNegative()`	double が負数であることを確認する。
`double.shouldBePositiveInfinity()`	double が正の無限大であることを確認する。
`double.shouldBeNegativeInfinity()`	double が負の無限大であることを確認する。
`double.shouldBeNaN()`	double が NaN であることを確認する。

Files, URIs, and other modules
`file.shouldBeAbsolute()`	ファイルが絶対パスを表すことを確認する。
`file.shouldBeADirectory()`	ファイルがディレクトリを表すことを確認する。
`file.shouldBeAFile()`	ファイルが通常ファイルを表すことを確認する。
`file.shouldExist()`	ファイルがディスク上にディレクトリまたはファイルとして存在することを確認する。
`file.shouldHaveExtension(ext)`	ファイルが指定した拡張子で終わることを確認する。
`file.shouldHaveFileSize(size)`	ファイルが指定したサイズであることを確認する。
`uri.shouldHaveAuthority(fragment)`	URI に指定した authority があることを確認する。
`uri.shouldHaveFragment(fragment)`	URI に指定した fragment があることを確認する。
`uri.shouldHaveHost(scheme)`	URI に指定した host があることを確認する。
`uri.shouldHaveParameter(scheme)`	URI のクエリ文字列に指定したパラメータが含まれることを確認する。
`uri.shouldHavePath(scheme)`	URI に指定した path があることを確認する。
`uri.shouldHavePort(scheme)`	URI に指定した port があることを確認する。
`uri.shouldHaveQuery(fragment)`	URI に指定した query があることを確認する。
`uri.shouldHaveScheme(scheme)`	URI に指定した scheme があることを確認する。

Date and time
`date.shouldHaveSameYearAs(otherDate)`	日付が指定した日付と同じ年であることを確認する。
`date.shouldHaveSameMonthAs(otherDate)`	日付が指定した日付と同じ月であることを確認する。
`date.shouldBeBefore(otherDate)`	日付が指定した日付より前であることを確認する。
`date.shouldBeAfter(otherDate)`	日付が指定した日付より後であることを確認する。
`date.shouldBeWithin(duration, otherDate)`	日付が指定した日付から指定期間内にあることを確認する。
`date.shouldBetween(firstDate, secondDate)`	日付が 2 つの日付の間にあることを確認する。
`zonedDateTime.shouldBeToday()`	`ZonedDateTime` が今日と同じ日であることを確認する。
`offsetDateTime.shouldBeToday()`	`OffsetDateTime` が今日と同じ日であることを確認する。
`time.shouldBeBefore(otherTime)`	時刻が指定した時刻より前であることを確認する。
`time.shouldBeAfter(otherTime)`	時刻が指定した時刻より後であることを確認する。
`time.shouldBeBetween(firstTime, secondTime)`	時刻が 2 つの時刻の間にあることを確認する。
`instant.shouldBeAfter(anotherInstant)`	インスタントが別のインスタントより後に発生することを確認する。
`instant.shouldBeBefore(anotherInstant)`	インスタントが別のインスタントより前に発生することを確認する。
`instant.shouldBeBetween(fromInstant, toInstant)`	インスタントが 2 つのインスタントの間にあることを確認する。

Concurrent, futures, and threads
`shouldCompleteWithin(timeout, unit, function)`	指定した関数が指定期間内に完了することを確認する。
`shouldTimeout(timeout, unit, function)`	指定した関数が指定期間内に完了しないことを確認する。
`future.shouldBeCancelled()`	future がキャンセルされたことを確認する。
`future.shouldBeCompleted()`	future が完了したことを確認する。
`future.shouldBeCompletedExceptionally()`	future が例外で完了したことを確認する。
`thread.shouldBeBlocked()`	スレッドが現在ブロックされていることを確認する。
`thread.shouldBeDaemon()`	スレッドがデーモンスレッドであることを確認する。
`thread.shouldBeAlive()`	スレッドが生存していることを確認する。
`thread.shouldBeTerminating()`	スレッドが終了していることを確認する。

Throwables / Exceptions
`throwable.shouldHaveMessage(message)`	Throwable のメッセージが指定したメッセージと等しいことを確認する。
`throwable.shouldHaveCause()`	Throwable に原因があることを確認する。
`throwable.shouldHaveCause { block }`	Throwable に原因があることを確認し、それをブロックに渡す。
`throwable.shouldHaveCauseInstanceOf<T>()`	Throwable に原因があり、それが型 `T` またはそのサブタイプであることを確認する。
`throwable.shouldHaveCauseOfType<T>()`	Throwable に原因があり、それが正確に型 `T` であることを確認する。

Result and Optional
`result.shouldBeSuccess()`	結果が成功であることを確認する。
`result.shouldBeSuccess(value)`	結果が成功で、値が指定したものと等しいことを確認する。
`result.shouldBeSuccess(block)`	結果が成功であると仮定し、結果値でブロックを実行する。
`result.shouldBeFailure()`	結果が失敗であることを確認する。
`result.shouldBeFailureOfType<Type : Throwable>()`	結果が失敗で、例外クラスが指定したものと同じであることを確認する。
`result.shouldBeFailure(block)`	結果が失敗であると仮定し、例外でブロックを実行する。
`optional.shouldBePresent()`	`Optional` が存在することを確認する。
`optional.shouldBePresent { value -> .. }`	`Optional` が存在することを確認し、その値でブロックを実行する。
`optional.shouldBeEmpty()`	`Optional` が空であることを確認する。

Reflection, statistics, and resources
`kclass.shouldHaveAnnotations()`	クラスにアノテーションがあることを確認する。
`kclass.shouldBeAnnotatedWith<T>()`	クラスが指定した型でアノテーションされていることを確認する。
`kclass.shouldHaveFunction(name)`	クラスに指定した名前の関数があることを確認する。
`kclass.shouldHaveMemberProperty(name)`	クラスに指定した名前のメンバープロパティがあることを確認する。
`kclass.shouldBeData()`	クラスがデータクラスであることを確認する。
`kclass.shouldBeSealed()`	クラスが sealed クラスであることを確認する。
`kfunction.shouldHaveReturnType<T>()`	関数が指定した型を返すことを確認する。
`kproperty.shouldBeOfType<T>()`	プロパティが指定した型であることを確認する。
`collection.shouldHaveMean(mean)`	コレクションが指定した平均を持つことを確認する。
`collection.shouldHaveVariance(mean)`	コレクションが指定した分散を持つことを確認する。
`collection.shouldHaveStandardDeviation(mean)`	コレクションが指定した標準偏差を持つことを確認する。
`regex.shouldBeRegex(anotherRegex)`	パターンとオプションを比較し、正規表現が別の正規表現と等しいことを確認する。
`regex.shouldHavePattern(regexPattern)`	正規表現が指定したパターンを持つことを確認する。
`any.shouldBeEqualToUsingFields(other: T, vararg properties: KProperty<*>)`	指定したプロパティのみを考慮して `other` と等しいことを確認する。
`any.shouldBeEqualToIgnoringFields(other: T, vararg properties: KProperty<*>)`	指定したプロパティを無視して `other` と等しいことを確認する。
`str shouldMatchResource "/path/to/test_resource.txt"`	文字列が指定したリソースと等しいことを確認する。行区切りの違いは無視される。
`byteArray shouldMatchResource "/path/to/test_resource.bin"`	byteArray が指定したリソースと等しいことを確認する。

参照

Core Matchers | Kotest

Kotest例外テスト(Testing Exceptions)

kc@example.com (kc kim) — Mon, 04 Mar 2024 01:11:00 +0900

Kotest例外テスト

Kotestを使うと、例外を簡単にテストできる。

package com.devkuma.kotest.tutorial.exceptions

import io.kotest.assertions.throwables.shouldNotThrow
import io.kotest.assertions.throwables.shouldThrow
import io.kotest.core.spec.style.FreeSpec
import io.kotest.matchers.shouldBe

class ExceptionTest : FreeSpec({

    "例外発生テスト" - {
        "例外が発生する場合" {
            // 例外が発生するコードを実行し、その例外を捕捉する。
            val errorProneFunction: () -> Unit = {
                throw IllegalArgumentException("例外発生!")
            }
            val exception = shouldThrow<IllegalArgumentException> {
                errorProneFunction()
            }

            // 期待した例外が発生した場合、テストを通過する。
            exception.message shouldBe "例外発生!"
        }

        "例外が発生しない場合" {
            // 例外が発生しないコードを実行し、例外が発生しないことを確認する。
            val safeFunction: () -> Unit = {}
            val exception = shouldNotThrow<IllegalArgumentException> {
                safeFunction()
            }

            // 例外が発生しない場合、テストを通過する。
            exception shouldBe null
        }
    }
})

参照

Testing Exceptions | Kotest

Kotest現在時刻インスタントリスナー(Current Instant Listeners)拡張

kc@example.com (kc kim) — Sat, 13 Apr 2024 23:34:00 +0900

TIP

Kotest 5.6.0から、現在インスタントリスナーは`io.kotest:kotest-extensions-now:${kotest-version}`アーティファクトにある。以下で説明する機能を使用するには、依存関係として追加する必要がある。

現在時刻インスタントリスナー

エンティティの作成日時設定など、さまざまな理由でjava.timeクラスにあるnow静的関数を使用する必要がある場合がある。

data class MyEntity(
    creationDate: LocalDateTime = LocalDateTime.now()
)

しかし、その値をテストしたい場合はどうすればよいだろうか。nowを呼び出すたびに値が変わってしまう。

そのため、KotestはConstantNowListenerとwithConstantNow関数を提供している。

コードを実行している間、テストしたい値は常にnowになる。

val foreverNow = LocalDateTime.now()

withConstantNow(foreverNow) {
    LocalDateTime.now() shouldBe foreverNow
    delay(10) // Code is taking a small amount of time to execute, but `now` changed!
    LocalDateTime.now() shouldBe foreverNow
}

または、すべてのテストに対してリスナーを使用することもできる。

override fun listeners() = listOf(
    ConstantNowTestListener(foreverNow)
)

CAUTION

`withContantNow`と`ConstantNowTestListener`は競合状態に非常に敏感である。これらを使用すると、JVMインスタンス全体に対してグローバルな静的`now`メソッドをモックすることになるため、テストを並列実行している間に使用すると結果が一貫しない可能性がある。

参照

Current Instant Listeners | Kotest

Kotest 統計(Statistics)

kc@example.com (kc kim) — Sat, 06 Apr 2024 19:00:00 +0900

統計(Statistics)

ジェネレーターが望んだ方法で構成されているかを確認するために、Kotest で生成される値の種類を知りたい場合がある。プロパティテスト統計は、このような要求を満たすために設計されている。

collect 関数は統計の開始点であり、値のカテゴリを数えるために使用される。この関数は、プロパティテスト内で増やしたいカテゴリを指定して呼び出す。

たとえば、BigDecimal が使用する RoundingMode 値の統計を収集したいとする。通常どおり checkAll を呼び出し、丸めモードを collect 関数に渡す。

checkAll(Arb.enum<RoundingMode>(), Arb.bigDecimal()) { mode, decimal ->
  collect(mode)
  // test here
}

テストが完了すると、Kotest はテスト名と各カテゴリの件数/割合を出力する。

Statistics: [collecting stats] (1000 iterations, 1 args)

HALF_DOWN                                                     142 (14%)
HALF_UP                                                       141 (14%)
CEILING                                                       132 (13%)
FLOOR                                                         122 (12%)
UP                                                            119 (12%)
UNNECESSARY                                                   119 (12%)
HALF_EVEN                                                     118 (12%)
DOWN                                                          107 (11%)

使用するカテゴリは enum である必要はない。任意のオブジェクトにでき、より細かく制御したい場合は条件付きでラップできる。

checkAll(Arb.int()) { k ->
  when {
    k % 2 == 0 -> collect("EVEN")
    else -> collect("ODD")
  }
  // test here
}

ラベル(Labels)

直交する統計セットが必要になることがある。たとえば簡単な数値テストでは、特定の割合が偶数であり、特定の割合が負数であることを確認したい場合がある。1 つの方法は EVEN_POS、EVEN_NEG、ODD_POS、ODD_NEG を使うことである。

checkAll(Arb.int()) { k ->
  when {
    k > 0 && k % 2 == 0 -> collect("EVEN_POS")
    k % 2 == 0 -> collect("EVEN_NEG")
    k > 0 -> collect("ODD_POS")
    else -> collect("ODD_NEG")
  }
  // test here
}

これにより、1 つの出力セットが得られる。

EVEN_POS                                                       142 (27%)
EVEN_NEG                                                       141 (23%)
ODD_POS                                                        132 (24%)
ODD_NEG                                                        122 (26%)

しかし、組み合わせが増えると扱いにくくなるため、Kotest はラベル付き統計をサポートする。これは別々の統計セットと考えられる。ラベルを使用するには、collect メソッドの最初の引数にラベル名を渡すだけでよい。

checkAll(Arb.int()) { k ->
  when {
    k % 2 == 0 -> collect("even_odd", "EVEN")
    else -> collect("even_odd", "ODD")
  }
  when {
    k > 0 -> collect("pos_neg", "POS")
    else -> collect("pos_neg", "NEG")
  }
  // test here
}

これで Kotest は、タイトルにラベル名を含む複数の統計セットを出力する。

Statistics: [collecting labelled stats] (1000 iterations, 1 args) [even_odd]

ODD                                                           520 (52%)
EVEN                                                          480 (48%)


Statistics: [collecting labelled stats] (1000 iterations, 1 args) [pos_neg]

NEG                                                           527 (53%)
POS                                                           473 (47%)

レポートモード

デフォルトでは、すべてのプロパティテストの統計が出力される。グローバル構成オブジェクト PropertyTesting で構成できる 4 つのモードがある。

可能なオプションは次のとおりである。

Mode	Function
`PropertyTesting.statisticsReportMode = StatisticsReportMode.OFF`	すべての統計レポートを無効にする。
`PropertyTesting.statisticsReportMode = StatisticsReportMode.ALL`	すべての統計レポートを有効にする。
`PropertyTesting.statisticsReportMode = StatisticsReportMode.SUCCESS`	成功したテストでのみ統計を出力する。
`PropertyTesting.statisticsReportMode = StatisticsReportMode.FAILED`	失敗したテストでのみ統計を出力する。

統計のカバレッジ確認

特定の値が生成されていることをプログラムで主張するには、満たす必要がある制約を指定できる。

たとえば、前の丸めの例で withCoveragePercentages を使用し、少なくとも 10% の入力が HALF_DOWN をカバーし、10% が FLOOR をカバーすることを確認できる。

withCoveragePercentages(mapOf(RoundingMode.HALF_DOWN to 10.0, RoundingMode.FLOOR to 10.0)) {
  checkAll(Arb.enum<RoundingMode>(), Arb.bigDecimal()) { mode, decimal ->
    collect(mode)
    // use the mode / decimal
  }
}

割合ではなく絶対数で確認するには、withCoverageCounts を使用する。

withCoverageCounts(mapOf(RoundingMode.HALF_DOWN to 75, RoundingMode.FLOOR to 75)) {
  checkAll(Arb.enum<RoundingMode>(), Arb.bigDecimal()) { mode, decimal ->
    collect(mode)
    // use the mode / decimal
  }
}

カスタムレポート

統計レポーターの独自インスタンスを使用して、レポート形式をカスタマイズしたり、生データからレポートを生成したりできる。これはグローバル構成オブジェクト PropertyTesting を通じて構成される。

例:

object MyStatisticsReporter : object : StatisticsReporter { ... }
PropertyTesting.statisticsReporter = MyStatisticsReporter

参照

Statistics | Kotest

Kotest コレクションマッチャー(Collection Matchers)

kc@example.com (kc kim) — Thu, 28 Mar 2024 01:03:00 +0900

コレクションの複数要素をテストする便利な方法として、インスペクターも参照する。

Collections
`collection.shouldBeEmpty()`	コレクションの要素数が 0 であることを確認する。
`collection.shouldBeUnique()`	コレクション内のすべての要素が自然な等価性で一意であることを確認する。
`collection.shouldBeUnique(comparator)`	指定した `comparator` で比較し、すべての要素が一意であることを確認する。
`collection.shouldContain(element)`	コレクションに指定した要素が含まれることを確認する。
`collection.shouldContainAll(e1, e2, ..., en)`	順序に関係なく、列挙したすべての要素がコレクションに含まれることを確認する。
`collection.shouldContainDuplicates()`	コレクションに少なくとも 1 つの重複要素が含まれることを確認する。
`collection.shouldContainExactly()`	コレクションが指定した値だけを順序どおりに含み、他の値を含まないことを確認する。
`collection.shouldContainExactlyInAnyOrder()`	コレクションが指定した値だけを任意の順序で正確に含み、それ以外を含まないことを確認する。
`collection.shouldContainAllInAnyOrder()`	コレクションが指定したすべての値を任意の順序で含み、他の値を含まないことを確認する。
`collection.shouldContainNoNulls()`	コレクションに null 要素がない、または空であることを確認する。
`collection.shouldContainNull()`	コレクションに少なくとも 1 つの null 要素が含まれることを確認する。
`collection.shouldContainOnlyNulls()`	コレクションに null 要素だけが含まれる、または空であることを確認する。
`collection.shouldContainAllIgnoringFields()`	1 つ以上のフィールドを無視して、列挙したすべての要素がコレクションに含まれることを確認する。
`collection.shouldHaveSingleElement(element)`	コレクションに単一の要素だけが含まれ、それが指定した要素であることを確認する。
`collection.shouldHaveSingleElement { block }`	指定した述語に一致する単一の要素がコレクションに含まれることを確認する。
`collection.shouldHaveSize(length)`	コレクションの長さが指定した値と正確に一致することを確認する。
`collection.shouldBeSingleton()`	コレクションに要素が 1 つだけ含まれることを確認する。
`collection.shouldBeSingleton { block }`	コレクションに要素が 1 つだけ含まれることを確認し、その要素でブロックを実行する。
`collection.shouldHaveLowerBound(element)`	指定した要素がコレクション内のすべての要素以下であることを確認する。`Comparable` を実装する要素にのみ機能する。
`collection.shouldHaveUpperBound(element)`	指定した要素がコレクション内のすべての要素以上であることを確認する。`Comparable` を実装する要素にのみ機能する。
`collection.shouldBeSmallerThan(col)`	コレクションが別のコレクションより小さいことを確認する。
`collection.shouldBeLargerThan(col)`	コレクションが別のコレクションより大きいことを確認する。
`collection.shouldBeSameSizeAs(col)`	コレクションのサイズが別のコレクションと同じであることを確認する。
`collection.shouldHaveAtLeastSize(n)`	コレクションのサイズが `n` 以上であることを確認する。
`collection.shouldHaveAtMostSize(n)`	コレクションのサイズが `n` 以下であることを確認する。
`list.shouldBeSorted()`	リストがソートされていることを確認する。
`list.shouldBeSortedBy { transform }`	変換を適用した後の値を基準にリストがソートされていることを確認する。
`list.shouldContainInOrder(other)`	このリストが指定したリストを順序どおりに含むことを確認する。指定したリストの前後に他の要素があってもよい。
`list.shouldExistInOrder({ element }, ...)`	述語に一致する要素が順序どおりに含まれることを確認する。一致要素の周囲や間に他の要素があってもよい。
`list.shouldHaveElementAt(index, element)`	このリストの指定位置に指定要素が含まれることを確認する。
`list.shouldStartWith(lst)`	このリストが指定したリストの要素で順序どおりに始まることを確認する。
`list.shouldEndWith(lst)`	このリストが指定したリストの要素で順序どおりに終わることを確認する。
`iterable.shouldMatchEach(assertions)`	このリストとアサーションを反復し、各要素が対応するアサーションに成功することを確認する。コレクションサイズが一致しない場合は失敗する。
`iterable.shouldMatchInOrder(assertions)`	この iterable に、隙間なしで順序どおりにアサーションと一致する部分列があることを確認する。
`iterable.shouldMatchInOrderSubset(assertions)`	この iterable に、隙間を許可して順序どおりにアサーションと一致する部分列があることを確認する。
`value.shouldBeOneOf(collection)`	特定のインスタンスがコレクションに含まれることを確認する。
`collection.shouldContainAnyOf(collection)`	コレクションに、指定したコレクションの要素が少なくとも 1 つ含まれることを確認する。
`value.shouldBeIn(collection)`	オブジェクトが参照ではなく値としてコレクションに含まれることを確認する。

参照

Collection Matchers | Kotest

Kotestデータ駆動テスト(Data-Driven Testing)

kc@example.com (kc kim) — Mon, 04 Mar 2024 01:11:00 +0900

データ駆動テスト

データ駆動テスト(Data-Driven Testing)は、同じテストコードを複数のデータセットに対して繰り返し実行する方法で、JUnit 5のパラメータ化(Parameterized)テストに似ている。異なる入力データごとに複数のテストを書く代わりに、1つのテストケースへ複数の入力を渡して複数のケースを検証できる。

必須モジュール

データ駆動テストを使用するには、まずビルドに`kotest-framework-datatest`モジュールを追加する必要がある。 **依存関係の追加** Data-Driven Testingを使用するには、まず関連する依存関係を追加する。 ```kotlin dependencies { testImplementation("io.kotest:kotest-framework-datatest:") } ``` > このモジュールは4.6.0以降でサポートされているため、バージョンを確認してほしい。

ロジックベースのテストを書く場合、特定のシナリオで動作する1つか2つの特定コードパスで十分なことがある。一方で、例ベースのテストが多く、さまざまなパラメータの組み合わせをテストすると役立つ場合もある。

このような状況で、データ駆動テスト、つまりテーブル駆動テストは、退屈な定型コードを避けるための簡単な手法である。

Kotestは、フレームワークに組み込まれたデータ中心テストを第一級の機能として提供している。これはユーザーが提供した入力値をもとに、テストケース項目を自動生成する。

データ駆動テストを始める

簡単な例を通じてデータ駆動テストを見てみよう。

ピタゴラスの三角形テスト

入力値が有効な三角形、つまりaの2乗 + bの2乗 = cの2乗である場合にtrueを返すピタゴラスの三角形関数のテストを書く。

fun isPythagTriple(a: Int, b: Int, c: Int): Boolean = a * a + b * b == c * c

1行(Row)には1つ以上の要素が必要であり、ここでは3つ必要なので、まず1行分の値、この場合は2つの入力と期待結果を保持するデータクラスを定義する。

data class PythagTriple(val a: Int, val b: Int, val c: Int)

このデータクラスのインスタンスを使ってテストを生成し、各行のテストロジックを実行するラムダを受け取るwithData関数に渡す。

例:

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.FunSpec
import io.kotest.datatest.withData
import io.kotest.matchers.shouldBe

class PythagTripleTest : FunSpec({
    context("Pythag triples tests") {
        withData(
            PythagTriple(3, 4, 5),
            PythagTriple(6, 8, 10),
            PythagTriple(8, 15, 17),
            PythagTriple(7, 24, 25)
        ) { (a, b, c) ->
            isPythagTriple(a, b, c) shouldBe true
        }
    }
})

データクラスを使用しているため、入力rowをメンバー属性として分解できる。これを実行すると、入力行ごとに1つ、合計4つのテストケースが生成される。

Kotestは、各入力行に対して個別のテストケースを手動で作成したかのように、各入力行に対するテストケースを自動生成する。

テスト名はデータクラス自体から生成されるが、カスタマイズもできる。

特定の入力行にエラーがある場合、テストは失敗し、Kotestは失敗した値を出力する。たとえば、前の例にPythagTriple(5, 4, 3)行を含めるよう変更すると、そのテストは失敗として表示される。

エラーメッセージにはエラーと入力行の詳細が含まれる。

expected:<true> but was:<false>
Expected :true
Actual   :false

詳しく見ると、a=5, b=4, c=3のとき、5 * 5 + 4 * 4 = 41と3 * 3 = 9は等しくないため、falseが返されて失敗する。

前の例では、親テストでwithData呼び出しをラップしているため、テスト結果が表示されるときに追加コンテキスト(context("Pythag triples tests"))がある。構文は使用するSpecスタイルによって異なる。ここではコンテナにcontextブロックを使うFunSpecを使用した。実際には、データテストはいくらでもコンテナ内にネストできる。

ただし、これは任意であり、ルートレベルでもデータテストを定義できる。

例:

class PythagTripleTest : FunSpec({
    withData(
        PythagTriple(3, 4, 5),
        PythagTriple(6, 8, 10),
        //PythagTriple(5, 4, 3),
        PythagTriple(8, 15, 17),
        PythagTriple(7, 24, 25)
    ) { (a, b, c) ->
        isPythagTriple(a, b, c) shouldBe true
    }
})

CAUTION

データテストはルートまたはコンテナスコープでのみ定義できる。リーフスコープ(leaf scopes)内では定義できない。

さまざまな値に対するテスト

別の例として、さまざまな型のデータをテストする例を以下に示す。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.FunSpec
import io.kotest.datatest.withData
import io.kotest.matchers.shouldBe

class WithDataTest : FunSpec({

    context("文字列長の検証") {
        withData(
            ValueExpected("Hello", 5), // 1つ目のデータセット: 文字列 "Hello"
            ValueExpected("World", 5)  // 2つ目のデータセット: 文字列 "World"
        ) { (str, expected) ->
            str.length shouldBe expected // 各データセットについて文字列の長さが期待値か確認
        }
    }

    context("集合サイズの検証") {
        withData(
            ValueExpected(setOf(1, 2, 3), 3),   // 1つ目のデータセット: 整数集合 {1, 2, 3}
            ValueExpected(setOf(4, 5, 6, 7), 4) // 2つ目のデータセット: 整数集合 {4, 5, 6, 7}
        ) { (set, expected) ->
            set.size shouldBe expected // 各データセットについて集合のサイズが期待値か確認
        }
    }

    context("マップサイズの検証") {
        withData(
            ValueExpected(mapOf("a" to 1, "b" to 2), 2),             // 1つ目のデータセット: マップ {"a" -> 1, "b" -> 2}
            ValueExpected(mapOf("x" to 10, "y" to 20, "z" to 30), 3) // 2つ目のデータセット: マップ {"x" -> 10, "y" -> 20, "z" -> 30}
        ) { (map, expected) ->
            map.size shouldBe expected // 各データセットについてマップのサイズが期待値か確認
        }
    }
})

data class ValueExpected<T>(
    val value: T,
    val expected: Int,
)

forAll関数の使用

データ検証のためにforAll関数を使用し、データ駆動テストを行うこともできる。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.StringSpec
import io.kotest.data.forAll
import io.kotest.data.row
import io.kotest.matchers.shouldBe

class ForAllTest : StringSpec({

    "文字列長の検証" {
        forAll(
            row("Hello", 5),
            row("World", 5)
        ) { str, expected ->
            str.length shouldBe expected
        }
    }

    "集合サイズの検証" {
        forAll(
            row(setOf(1, 2, 3), 3),
            row(setOf(4, 5, 6, 7), 4)
        ) { set, expected ->
            set.size shouldBe expected
        }
    }

    "マップサイズの検証" {
        forAll(
            row(mapOf("a" to 1, "b" to 2), 2),
            row(mapOf("x" to 10, "y" to 20, "z" to 30), 3)
        ) { map, expected ->
            map.size shouldBe expected
        }
    }
})

上の例では、forAll関数を使って整数データを生成し、そのデータでテストを繰り返し実行している。

Callbacks

データ駆動テストで前後のコールバックを使うには、標準のbeforeTest / afterTestを使用できる。データ駆動テストで作成されたすべてのテストは通常のテストと同じように動作するため、標準コールバックはすべて、各テストを直接書いた場合と同じように動作する。

例:

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.FunSpec
import io.kotest.datatest.withData

class CallbackTest : FunSpec({

    beforeTest {
        println("beforeTest")
    }

    context("callback test") {
        withData("X", "Y", "Z") { a ->
            println(a)
        }
    }
})

次は例を実行した結果である。

beforeTest
beforeTest
X
beforeTest
Y
beforeTest
Z

データテスト名

デフォルトでは、各テストの名前は単に入力行のtoString()である。これは通常JVMのデータクラスではうまく機能するが、入力行は安定している必要がある。

しかし、安定したデータクラスを使わない場合、JVM以外のターゲットで実行する場合、または単にカスタマイズしたい場合は、テスト名を生成する方法を指定できる。

安定した名前

テストを生成するとき、Kotestはテストスイートの実行中に安定したテスト名を必要とする。テスト名は、GradleまたはIntelliJにテスト状態を通知するとき、テストを指す識別子の基礎として使われる。名前が安定していないとIDが変わり、テストが表示されなかったり完了していないように見えたりするエラーが起きる可能性がある。

Kotestは、入力クラスのtoString()値が安定していると判断される場合にのみ入力クラスのtoString()を使用し、そうでない場合はクラス名を使用する。

@IsStableTypeで型にアノテーションを追加すると、Kotestにテスト名としてtoString()を使うよう強制できる。この場合、条件に関係なくtoString()が使用される。

または、テストの表示名を完全にカスタマイズできる。

mapOfの使用

Kotestでは、キーがテスト名、値がその行の入力値であるマップをwithData関数に渡すことで、テスト名を指定できる。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.FunSpec
import io.kotest.datatest.withData
import io.kotest.matchers.shouldBe

class PythagTripleMapOfTest : FunSpec({
    
    context("Pythag triples tests") {
        withData(
            mapOf(
                "3, 4, 5" to PythagTriple(3, 4, 5),
                "6, 8, 10" to PythagTriple(6, 8, 10),
                "8, 15, 17" to PythagTriple(8, 15, 17),
                "7, 24, 25" to PythagTriple(7, 24, 25)
            )
        ) { (a, b, c) ->
            a * a + b * b shouldBe c * c
        }
    }
})

テスト名関数

または、行を入力として受け取りテスト名を返す関数をwithDataに渡すこともできる。Kotlinの型推論がどの程度うまく働くかによって、withData関数に型パラメータを指定する必要がある場合もある。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.FunSpec
import io.kotest.datatest.withData
import io.kotest.matchers.shouldBe

class PythagTripleNameTest : FunSpec({

    context("Pythag triples tests") {
        withData<PythagTriple>(
            nameFn = { "${it.a}, ${it.b}, ${it.c}" },
            PythagTriple(3, 4, 5),
            PythagTriple(6, 8, 10),
            PythagTriple(8, 15, 17),
            PythagTriple(7, 24, 25)
        ) { (a, b, c) ->
            a * a + b * b shouldBe c * c
        }
    }
})

この例の出力は少し分かりやすくなる。

WithDataTestName

もう1つの方法は、WithDataTestNameインターフェースを実装することである。このインターフェースを提供するとtoString()は使用されず、代わりに各行に対してそのインターフェースのdataTestName()関数が呼び出される。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.datatest.WithDataTestName

data class PythagTriple(val a: Int, val b: Int, val c: Int) : WithDataTestName {
    override fun dataTestName() = "wibble $a, $b, $c wobble"
}

この例の出力はより簡単になる。

ネストされたデータテスト

Kotestのデータテストは非常に柔軟で、データテスト構成を無制限にネストできる。追加のネストごとにテスト出力に別のネスト層が生成され、すべての入力のCartesian joinを提供する。

Cartesian joinとは?

リレーショナルデータベースで使われる用語である。2つ以上のテーブルを結合するとき、各テーブルのすべての行を他のテーブルのすべての行と結合することを意味する。

たとえば、次のコードスニペットには2つのネスト層がある。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.FunSpec
import io.kotest.datatest.withData

class NestedDataTest : FunSpec({

    context("each service should support all http methods") {
        val services = listOf(
            "http://internal.foo",
            "http://internal.bar",
            "http://public.baz",
        )

        val methods = listOf("GET", "POST", "PUT")

        withData(services) { service ->
            withData(methods) { method ->
                // test service against method
            }
        }
    }
})

次は同じ例だが、今回は2番目のレベルにカスタムテスト名を追加した例である。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.FunSpec
import io.kotest.datatest.withData

class NestedDataTest2 : FunSpec({

    context("each service should support all http methods") {

        val services = listOf(
            "http://internal.foo",
            "http://internal.bar",
            "http://public.baz",
        )

        val methods = listOf("GET", "POST", "PUT")

        withData(services) { service ->
            withData<String>({ "should support HTTP $it" }, methods) { method ->
                // test service against method
            }
        }
    }
})

その他のデータテスト

前ではwithData関数を使ったテストを説明した。ここではKotestでの基本的なデータ活用方法を説明する。

テストデータの生成

テストデータを生成することは、テストの信頼性と完全性を保証するうえで重要な役割を果たす。Kotestではさまざまな方法でテストデータを生成できる。たとえば、テスト関数内で直接データを定義したり、テストケースクラス内のメンバー変数としてデータを定義したりできる。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.StringSpec
import io.kotest.matchers.shouldBe

class DataTest : StringSpec({

    val testData = listOf(1, 2, 3, 4, 5)

    "事前定義されたテストデータを使用してテスト" {
        testData.size shouldBe 5
    }

    "範囲内でテストデータを使用してテスト" {
        val generatedData = (1..10).toList()
        generatedData.size shouldBe 10
    }
})

上の例では、testDataというメンバー変数を使ってテストデータを定義している。また、generatedDataを使って範囲内のデータを生成している。

テストデータの設定と整理

テストが実行される前に必要なデータを設定し、テスト完了後にデータを整理することは、テストの安定性を保証するうえで重要である。KotestではbeforeTestとafterTestブロックを使って、テストデータの設定と整理を行える。

package com.devkuma.kotest.tutorial.datadriven

import io.kotest.core.spec.style.StringSpec

class DataSetupAndCleanupTest : StringSpec({

    val database = setupDatabase()

    beforeTest {
        database.connect()
    }

    afterTest {
        database.disconnect()
    }

    "Test with database connection" {
        // データベース接続を使用したテストロジック
    }
})

fun setupDatabase(): Database {
    // Setup database and return
}

上の例では、beforeTestブロックでデータベースに接続し、afterTestブロックで接続を解除している。

テストデータの生成、管理、整理は、テストの信頼性を確保するための重要な要素である。Kotestを使ってテストデータを効果的に管理すれば、安定した堅牢なテストを実行でき、ソフトウェアの品質を向上させることができる。

参考

Kotest Koin拡張

kc@example.com (kc kim) — Sat, 13 Apr 2024 10:33:00 +0900

Koin DI Frameworkは、KoinExtension拡張を通じてKotestと一緒に使用できる。

プロジェクトで拡張を使用するには、プロジェクトに依存関係を追加する。

io.kotest.extensions:kotest-extensions-koin:${version}

依存関係が追加されると、テストでKoinを簡単に使用できる。

class KotestAndKoin : FunSpec(), KoinTest {

    override fun extensions() = listOf(KoinExtension(myKoinModule))

    val userService by inject<UserService>()

    init {
        test("use userService") {
            userService.getUser().username shouldBe "LeoColman"
        }
    }
}

デフォルトでは、拡張はリーフテスト(leaf test)間でKoinコンテキストを開始/停止する。DescribeSpecのようなネストされたSpecスタイルを使用し、ルートテストのすべてのリーフにわたってKoinコンテキストを維持したい場合、たとえばテスト間でモック宣言を共有するためには、KoinExtensionコンストラクタでライフサイクルモードをKoinLifecycleMode.Rootに指定できる。

class KotestAndKoin : DescribeSpec(), KoinTest {

    override fun extensions() = listOf(KoinExtension(module = myKoinModule, mode = KoinLifecycleMode.Root))

    val userService by inject<UserService>()

    init {
        describe("use userService") {
            it("inside a leaf test") {
                userService.getUser().username shouldBe "LeoColman"
            }
            it("this shares the same context") {
                userService.getUser().username shouldBe "LeoColman"
            }
        }
    }
}

参照

Koin | Kotest

Kotest JSON マッチャー(JSON Matchers)

kc@example.com (kc kim) — Wed, 10 Apr 2024 18:26:00 +0900

概要

JSON マッチャーを使用するには、ビルドに testImplementation("io.kotest.extensions:kotest-assertions-json:<version>") を追加する必要がある。

基本マッチャー

マッチャー	説明	対象
`shouldBeValidJson`	指定した文字列が有効な JSON としてパースできることを確認する。	Multiplatform
`shouldBeJsonObject`	文字列が有効な JSON オブジェクトであることを確認する。	Multiplatform
`shouldBeJsonArray`	文字列が有効な JSON 配列であることを確認する。	Multiplatform

コンテンツベースのマッチング

詳しくは JSON コンテンツマッチングを参照する。

マッチャー	説明	対象
`shouldEqualJson`	文字列が指定した JSON 構造と一致することを確認する。	Multiplatform
`shouldEqualSpecifiedJson`	文字列が指定した JSON 構造と一致することを確認するが、指定されていない追加プロパティを許可する。	Multiplatform
`shouldContainJsonKey`	文字列が JSON であり、指定した JSON パスを含むことを確認する。	JVM
`shouldContainJsonKeyValue`	文字列が JSON であり、指定した値を持つ指定 JSON パスを含むことを確認する。	JVM
`shouldMatchJsonResource`	文字列が指定したテストリソースの JSON コンテンツと一致することを確認する。	JVM

スキーマ検証

マッチャー	説明	対象
`shouldMatchSchema`	`String` または `kotlinx.serialization.JsonElement` が `JsonSchema` と一致することを確認する。スキーマ構成の詳細は以下を参照する。	Multiplatform

JSON コンテンツマッチング

このモジュールは JVM および JS ターゲットで使用できる。

shouldEqualJson

json.shouldEqualJson(other) は、左側が右側と同じ JSON 構造であることを確認する。

このマッチャーは、異なるフォーマットや異なるキー順序を許可する。

たとえば、次の 2 つの JSON 文字列は同じものと見なされる。

{
   "name": "sam",
   "location": "chicago",
   "age" : 41
}

そして

{ "age" : 41, "name": "sam", "location": "chicago" }

このマッチャーの反対は shouldNotEqualJson であり、2 つの JSON 文字列が同じものと見なされる場合にエラーになる。

compareJsonOptions

shouldEqualJson は、JSON 比較の動作を切り替えるためのフラグを持つ CompareJsonOptions 型の追加パラメータをサポートする。

使用法:
オプションは次のようにインラインで指定できる。

a.shouldEqualJson(b, compareJsonOptions { arrayOrder = ArrayOrder.Strict })

もう 1 つの方法は、必要な比較動作を定義することである。

val myOptions = compareJsonOptions {
   typeCoercion = TypeCoercion.Enabled
   arrayOrder = ArrayOrder.Lenient
}

infix fun String.lenientShouldEqualJson(other: String) = this.shouldEqualJson(other, myOptions)

"[1, 2]" lenientShouldEqualJson "[2, 1]" // This will pass

Parameters

名前	目的	可能な値	デフォルト
`PropertyOrder`	比較時に JSON オブジェクトのプロパティ順序を考慮するかを決定する。	`PropertyOrder.Strict`, `PropertyOrder.Lenient`	`PropertyOrder.Lenient`; プロパティ順序は重要ではない。
`ArrayOrder`	比較時に JSON 配列の要素順序を考慮するかを決定する。	`ArrayOrder.Strict`, `ArrayOrder.Lenient`	`ArrayOrder.Strict`; 要素順序は重要である。
`FieldComparison`	`actualJSON` が `expected` と比較して追加プロパティを含む場合に比較を失敗させるかを決定する。	`FieldComparison.Strict`, `FieldComparison.Lenient`	`FieldComparison.Strict`; 追加プロパティによって不一致になる。
`NumberFormat`	数値形式について厳密に比較するかを決定する。たとえば `100.0` と `100` を同じと見なすかどうかである。	`NumberFormat.Strict`, `NumberFormat.Lenient`	`NumberFormat.Lenient`; 数値形式は重要ではない。
`TypeCoercion`	文字列に数値やブール値が含まれる場合などに、型を強制変換するかを決定する。	`TypeCoercion.Enabled`, `TypeCoercion.Disabled`	`TypeCoercion.Disabled`; 型は強制変換されない。

対象: Multiplatform

shouldEqualSpecifiedJson

shouldEqualJson の別名で、デフォルトオプションは FieldComparison だけが異なり、FieldComparison.Lenient に設定される。

val a = """ { "a": true, "date": "2019-11-03" } """
val b = """ { "a": true } """

// this would pass
a shouldEqualSpecifiedJson b

// this would fail
a shouldEqualJson b

対象: Multiplatform

shouldContainJsonKey

json.shouldContainJsonKey("$.json.path") は、JSON 文字列に指定した JSON パスが含まれることを確認する。

反対のマッチャーは shouldNotContainJsonKey で、JSON 文字列に指定した JSON パスが含まれる場合にエラーになる。

対象: JVM

shouldContainJsonKeyValue

str.shouldContainJsonKeyValue("$.json.path", value) は、JSON 文字列に特定の値を持つ JSON パスが含まれることを確認する。

反対のマッチャーは shouldNotContainJsonKeyValue で、指定した JSON パスに指定した値が含まれる場合にエラーになる。

対象: JVM

shouldMatchJsonResource

json.shouldMatchJsonResource("/file.json") は、プロパティ順序とフォーマットを無視して、JSON が既存のテストリソース /file.json と同じであることを確認する。

対象: JVM

JSON スキーママッチャー

マッチャー	説明	対象
`shouldMatchSchema`	`String` または `kotlinx.serialization.JsonElement` が `JsonSchema` と一致することを確認する。スキーマ構成の詳細は以下を参照する。	Multiplatform

JSON Schema のサブセットは、テキストスキーマをパースして定義できる。

例:

val parsedSchema = parseSchema(
  """
  {
  "$id": "https://example.com/geographical-location.schema.json",  // will  be ignored
  "$schema": "https://json-schema.org/draft/2020-12/schema",       // will be ignored
  "title": "Longitude and Latitude Values",                        // will be ignored
  "description": "A geographical coordinate.",                     // will be ignored
  "required": [ "latitude", "longitude" ],
  "type": "object",
  "properties": {
    "latitude": {
      "type": "number",
      "minimum": -90,
      "maximum": 90
    },
    "longitude": {
      "type": "number",
      "minimum": -180,
      "maximum": 180
    }
  }
}
  """
)

または Kotest の組み込み DSL を使用する。

val addressSchema = jsonSchema {
  obj {   // object is reserved, obj was chosen over jsonObject for brevity but could be changed ofc, or jsonObject could be added as alternative.
    withProperty("street", required = true) { string() }
    withProperty("zipCode", required = true) {
      integer {
        beEven() and beInRange(10000..99999)   // supports constructing a matcher that will be used to test values
      }
    }
    additionalProperties = false   // triggers failure if other properties are defined in actual
  }
}

val personSchema = jsonSchema {
  obj {
    withProperty("name", required = true) { string() }
    withProperty("address") { addressSchema() } // Schemas can re-use other schemas 🎉
  }
}

スキーマ構築

配列

配列は順序付きの要素に使用される。JSON では、配列の各要素が異なる型を持つことができる。

Length (minItems and maxItems)

配列の長さは minItems と maxItems キーワードで指定できる。各キーワードの値は非負の数でなければならず、デフォルトは 0 と Int.MAX_VALUE である。

val lengthBoundedSchema = jsonSchema {
  array(minItems = 0, maxItems = 1) { number() }
}

Uniqueness

スキーマは、配列の各項目が一意であることを確認できる。uniqueItems キーワードを true に設定するだけでよい。

val uniqueArray = jsonSchema {
  array(uniqueItems = true) { number() }
}

⚠️ Kotest は現在、JSON Schema のサブセットのみをサポートしている。現在サポートされていない項目は次のとおりである。

$defs and $refs
Recursive schemas
Parsing of schema composition
string.format
array.prefixItems,
array.contains,
array.items = false
array.maxContains
array.minContains
array.uniqueItems
enum

検証

スキーマが定義されると、それを基準に String と kotlinx.serialization.JsonElement を検証できる。

"{}" shouldMatchSchema personSchema

// fails with:
// $.name => Expected string, but was undefined

""" { "name": "Emil", "age": 34 } """
// Passes, since address isn't required and `additionalProperties` are allowed