.NET Core用のテストランナーを作る

C# F#

[2017/02/18追記].NET Core SDK RC以降で実装方法が変わったのでこの記事を読むべきではありません

これは.NET Core Advent Calendar 4日目の記事です。

qiita.com

.NET Coreに対応したユニットテスト

さて、世の中にはすでに.NET Coreに対応済みのテスティングフレームワークがいくつか存在します。

ここで、.NET Core CLI用のランナーを提供しているプロジェクトをみてみましょう。

主要フレームワークはすでにpreviewやbeta版がリリースされているようですね。 Visual Studioにべったり（？）だったMSTestも次のバージョンからNuGetで取得できるようになったのが見所かもしれません。

ちなみに、私もF#向けテスティングフレームワーク開発に携わっている一人としてrunnerを作っていたりします。

今回はこういったランナーを実装するにはどうすれば良いか、という話を雑に書いていきます。

注意事項

  • 結局個人メモみたいな形になってしまったのでわかりづらいかも…
  • 2016/12/04時点での情報なので、正式リリースの際には仕様が変わっているかもしれないことに注意してください。
  • コンソールのみで動くランナーを作る場合にはここまでの知識は必要ありません
    • 逆を言えば、Visual Studio上でテストを動かしたいなら対応必須です

test communication protocol

.NET Core CLIにはtest communication protocolというテスト用のプロトコルが定められています。 Visual Studio 2017以降のテストエクスローラーはこのプロトコルを使って.NET Coreなテストを実行しているようですね。

.NET Core CLI test communication protocol | Microsoft Docs

機械翻訳？もあるみたいです。

.NET Core CLI テスト通信プロトコル | Microsoft Docs

必要になる知識はこれを読めば全部手に入るのですが、これを読んだだけで実装できたら苦労はしない…。

というわけで、以降では実装に必要なものなどをあげていきます。

パッケージ名

パッケージ名に関してはproject.json時代の話を書くので、状況次第では役に立たなくなるかもしれません。

パッケージ名はdotnet-test-fooのfoo部分にプロジェクト名をつけます。 これはproject.jsonに"testRunner": "foo"と記述すると、.NET CLIが依存関係の中からdotnet-test-fooパッケージを探索するという決まり事があるためです。 先に紹介したドキュメントのシーケンス図内ではdotnet-test-runnerという表現がなされています。

Microsoft.Extensions.Testing.Abstractions

作成したプロジェクトの依存関係に次のパッケージを追加します。

www.nuget.org

このパッケージにはAdapterやdotnet testとの通信で使う型やインターフェースが定義されています。

コマンドラインオプション

ここに列挙するオプションはAdapter, dotnet test, ランナーが連携する際に必要となります。

Test discovery（テスト探索）とTest execution（テスト実行）に共通するオプションとそうでないオプションがあります。

共通

designtimeオプション

design modeを示すオプションです。 このオプションがついている場合はコンソール実行ではないと考えたほうが良いでしょう。

--designtime

portオプション

Adapterとランナー、あるいはdotnet testとランナー間でTCP通信するためのポート番号がオプションで渡されます。

--port ポート番号

テスト対象のアセンブリ一覧

テスト対象のアセンブリはオプション名なしのスペース区切りで渡されます。

testAssembly1 testAssembly2

Test discoveryで必要になるオプション

listオプション

テストのリストアップを要求するオプションです。 このオプションが渡された場合、ランナーはテストを実行する必要はありません。

--list

Test executionで必要になるオプション

wait-commandオプション

実行するテスト一覧を取得するために待機する必要があることを示すオプションです。

--wait-command

実装面

探索したテストの送信やテスト結果の送信はITestDiscoverySinkもしくはITestExecutionSinkを実装したクラスを使って行います。 この2つのインターフェースはMicrosoft.Extensions.Testing.Abstractionsにあります。

ポートが指定されていない場合

Microsoft.Extensions.Testing.Abstractionsに用意されているStreamingTestDiscoverySinkとStreamingTestExecutionSinkを使うのが手っ取り早いです。 おそらくコンソール上で実行しているはずなので、Console.OpenStandardOutputを渡せばよいと思います。

ポートが指定されている場合

独自にITestDiscoverySink, ITestExecutionSinkを実装したクラスを用意します……といっても基本はdotnet-test-nunitのやつをライセンスつけて持って来ればよいと思います。 NUnitのやつはSocket, NetworkStream, BinaryWriterを使って通信するようになっています。 IPアドレスは自分のPCがターゲットなのでIPAddress.Loopback固定で大丈夫なはずです。

Adapterやdotnet testとの通信はMessage型を使ってやりとりされます。 そして、このMessage型のPayloadはNewtonsoft.Jsonを使っているので、送信時は必然的にNewtonsoft.Jsonを使ってシリアライズしてから送信します。

wait-commandが指定された場合

  1. ITestExecutionSink#SendWaitingCommandで待機中であることを送信する
  2. Message#MessageTypeに指定する文字列はTestRunner.WaitingCommand
  3. BinaryReader等で送られてきたJSONをMessageとしてデシリアライズ
  4. ここで送られてくるMessage#Payloadの型はRunTestsMessageなので、message.Payload.ToObject<RunTestsMessage>().Testsなどとすれば実行すべきテスト一覧が取得できる

ここで取得できるテスト一覧はFullyQualifiedNameとなっています。 これを用いてテスト実行前にフィルタリングしていくことになります。

回りくどいなーという気持ちになるかもしれませんが、FullyQualifiedName自体が長かったりそもそもテスト数が多かったりしてコマンドラインのサイズ上限を容易に超えてしまうので仕方がないですね。

メッセージの送信

Adapterやdotnet testに情報を送信する際にもMessage型を使います。

MessageはMessageTypeというstringのプロパティを持ちます。 で、このMessageTypeに指定する文字列は決まっているわけですが、定数として定義されているわけではないのでランナー側で各自定義するしかないようです。 シリアライズ/デシリアライズのことを考えてstringなのはまぁ許せるとして、どうして定数をパッケージ側で用意しなかったのでしょうね…。

TestFound

--listオプションが指定されている時にテストを発見した場合はITestDiscoverySink#SendTestFoundを使ってテストを送信します。 Message#MessageTypeに指定する文字列はTestDiscovery.TestFoundです。

SendTestFoundや後述するSendTestStartedではTest型のオブジェクトを送信する必要があるのですが、Test#Propertiesのvalueにシリアライズできないような値を突っ込むと落ちるので気をつけましょう。

TestStarted

--designtimeオプションが指定されている時、テスト実行前にITestExecutionSink#SendTestStartedを使ってテスト開始を通知します。 Message#MessageTypeに指定する文字列はTestExecution.TestStartedです。

TestResult

--designtimeオプションが指定されている時、テスト実行後にITestExecutionSink#SendTestResultを使ってテスト結果を報告します。 Message#MessageTypeに指定する文字列はTestExecution.TestResultです。

なお、F#のAsyncを使ってParallelに実行しつつITestExecutionSink#SendTestResultを呼び出したところ、テストを2つ以上実行しようとした際にSocketExceptionが投げられました。 同期的な通知に修正したらこの例外は発生しなくなったので、もしかしたら2016/12/04時点ではITestExecutionSink#SendTestResultを同期的に呼び出す必要があるかもしれません（イマイチ確証が持てないですが…）。

後片付け

--designtimeが指定されている場合は、ITestDiscoverySink#SendTestCompletedかITestExecutionSink#SendTestComletedを使って完了を通知します。 Message#MessageTypeに指定する文字列はTestRunner.TestCompletedです。

コンソールで実行している場合は別途コンソール用の出力を実装したり、XMLレポートをちゅつ力してあげれば良いでしょう。

おわりに

テストランナーを実装するには色々とお作法に従う必要があることが理解できたかと思います。

しかし、Visual Studioのテストエクスプローラー用拡張を実装するよりは格段に楽になっています。 VS拡張ではドキュメントがほとんどなく、Microsoft.VisualStudio.TestPlatform.ObjectModelというNuGetにpublishされていないdllと格闘する必要があったためです。

今回言及していない点としては、AppDomainどうするの問題があります。 現行の.NET CoreにはAppDomainに相当する機能がないため、どうすれば良いのかよくわからないというのが正直なところです。 xUnit.NETではAppDomainがある環境とない環境でifdefを駆使してるみたいですが、果たしてこれが正解なのか…？

とまぁ、長くなりましたが、実装するかどうかはともかく自分たちが使っているプロトコルの仕様を読んでみるのも一興かと思います。