Unit Testing
Testing Base Julia
Julia は現在も急速に開発が進められており、複数のプラットフォームで機能を検証するための広範なテストスイートを備えています。ソースから Julia をビルドした場合は、make test を使ってこのテストスイートを実行できます。バイナリ版をインストールした場合は、Base.runtests() を使って実行できます。
Base.runtests — Function
Base.runtests(tests=["all"]; ncores=ceil(Int, Sys.EFFECTIVE_CPU_THREADS / 2),
exit_on_error=false, revise=false, propagate_project=true, [seed], [julia_args::Cmd])tests(文字列または文字列の配列)で指定された Julia のユニットテストを、ncores プロセッサを使用して実行します。exit_on_error が false の場合、あるテストが失敗しても、ほかのファイルにある残りのテストはすべて実行されます。それ以外の場合は、exit_on_error == true の時点で残りのテストは実行されません。revise が true の場合、テストの実行前に Revise パッケージを使って、Base または標準ライブラリへの変更を読み込みます。propagate_project が true の場合、現在のプロジェクトがテスト環境に引き継がれます。キーワード引数でシードが指定されていれば、テストの実行環境でグローバル RNG のシードとして使用されます。指定されていない場合は、シードがランダムに選ばれます。引数 julia_args を使うと、テストプロセスにカスタムの julia コマンドラインフラグを渡せます。
Basic Unit Tests
Test モジュールは、シンプルなユニットテスト機能を提供します。ユニットテストとは、結果が期待どおりであることを確認して、コードが正しいかどうかを調べる方法です。変更後もコードが引き続き動作することを確認するのに役立ちます。また、開発時に、完成したコードが備えるべき動作を指定するためにも利用できます。adding tests to your Julia Package のドキュメントも参照してください。
@test マクロと @test_throws マクロを使うと、簡単なユニットテストを実行できます。
Test.@test — Macro
@test ex
@test f(args...) key=val ...
@test ex broken=true
@test ex skip=true式 ex が true と評価されることをテストします。@testset 内で実行された場合、評価結果が真なら Pass Result、false なら Fail Result、評価できなかった場合は Error Result を返します。@testset の外で実行された場合は、Fail や Error を返す代わりに例外をスローします。
Examples
julia> @test true
Test Passed
julia> @test [1, 2] + [2, 1] == [3, 3]
Test Passed@test f(args...) key=val... 形式は、@test f(args..., key=val...) と書くのと同等です。これは、近似比較のように中置記法を使った呼び出しで式を記述する場合に便利です。
julia> @test π ≈ 3.14 atol=0.01
Test Passedこれは、より冗長なテスト @test ≈(π, 3.14, atol=0.01) と同等です。最初の式が呼び出し式で、残りが代入式(k=v)である場合を除き、複数の式を指定するとエラーになります。
key=val 引数には任意のキーを使用できます。ただし、broken と skip は @test のコンテキストで特別な意味を持つため、使用できません。
broken=condは、成功するはずだが、cond==true時に一貫して失敗するテストを示します。式exがfalseと評価されるか、例外を発生させることをテストします。そうなる場合はBrokenResultを返し、式がtrueと評価される場合はErrorResultを返します。通常の@test exはcond==false時に評価されます。skip=condは、実行せずにテスト概要の報告にBrokenとして含めるテストを示します(cond==true時)。断続的に失敗するテストや、まだ実装されていない機能のテストに便利です。通常の@test exはcond==false時に評価されます。
Examples
julia> @test 2 + 2 ≈ 6 atol=1 broken=true
Test Broken
Expression: ≈(2 + 2, 6, atol = 1)
julia> @test 2 + 2 ≈ 5 atol=1 broken=false
Test Passed
julia> @test 2 + 2 == 5 skip=true
Test Broken
Skipped: 2 + 2 == 5
julia> @test 2 + 2 == 4 skip=false
Test PassedTest.@test_throws — Macro
@test_throws exception expr
@test_throws extype pattern expr式 expr が exception をスローすることをテストします。例外の指定には、型、文字列、正規表現、表示されたエラーメッセージに含まれる文字列のリスト、照合関数、または値(フィールドを比較して等しいかどうかをテストします)を使用できます。
2引数形式の @test_throws exception expr では、exception に型またはパターンを指定できます。
3引数形式の @test_throws extype pattern expr では、例外の型とメッセージパターンの両方をテストします。extype は型でなければなりません。pattern には、文字列、正規表現、表示されたエラーメッセージに含まれる文字列のリスト、照合関数、または値を指定できます。
@test_throws は、末尾にキーワードを付ける形式をサポートしていないことに注意してください。
Examples
julia> @test_throws BoundsError [1, 2, 3][4]
Test Passed
Thrown: BoundsError
julia> @test_throws DimensionMismatch [1, 2, 3] + [1, 2]
Test Passed
Thrown: DimensionMismatch
julia> @test_throws "Try sqrt(Complex" sqrt(-1)
Test Passed
Message: "DomainError with -1.0:\nsqrt was called with a negative real argument but will only return a complex result if called with a complex argument. Try sqrt(Complex(x))."
julia> @test_throws ErrorException "error foo" error("error foo 1")
Test Passed
Thrown: ErrorException3つ目の例では、単一の文字列との照合の代わりに、次の方法も使用できます。
["Try", "Complex"](文字列のリスト)r"Try sqrt\([Cc]omplex"(正規表現)str -> occursin("complex", str)(照合関数)
最後の例では、例外の型(ErrorException)とメッセージパターン("error foo")の両方をテストします。
たとえば、新しい関数 foo(x) が期待どおりに動作することを確認したいとします。
julia> using Test
julia> foo(x) = length(x)^2
foo (generic function with 1 method)条件が真の場合は、Pass が返されます。
julia> @test foo("bar") == 9
Test Passed
julia> @test foo("fizz") >= 10
Test Passed条件が偽の場合は、Fail が返され、例外がスローされます。
julia> @test foo("f") == 20
Test Failed at none:1
Expression: foo("f") == 20
Evaluated: 1 == 20
ERROR: There was an error during testingこの例では、length がシンボルに対して定義されていないために例外がスローされ、条件を評価できなかった場合、Error オブジェクトが返され、例外がスローされます。
julia> @test foo(:cat) == 1
Error During Test
Test threw an exception of type MethodError
Expression: foo(:cat) == 1
MethodError: no method matching length(::Symbol)
The function `length` exists, but no method is defined for this combination of argument types.
Closest candidates are:
length(::SimpleVector) at essentials.jl:256
length(::Base.MethodList) at reflection.jl:521
length(::MethodTable) at reflection.jl:597
...
Stacktrace:
[...]
ERROR: There was an error during testing式の評価で例外が発生するはずだと予想される場合は、@test_throws を使って、実際に例外が発生することを確認できます。
julia> @test_throws MethodError foo(:cat)
Test Passed
Thrown: MethodErrorWorking with Test Sets
通常、さまざまな入力に対して関数が正しく動作することを確認するため、多数のテストを実行します。テストが失敗した場合、デフォルトでは直ちに例外がスローされます。しかし、テスト対象のコードにどれほどのエラーがあるかを把握するには、残りのテストも実行してから結果を確認するほうが望ましい場合がほとんどです。
@testset マクロを使うと、テストをセットにまとめられます。テストセット内のテストはすべて実行され、セットの最後に概要が出力されます。テストが失敗した場合、またはエラーのために評価できなかった場合は、テストセットから TestSetException がスローされます。
Test.@testset — Macro
@testset [CustomTestSet] [options...] ["description"] begin test_ex end
@testset [CustomTestSet] [options...] ["description $v"] for v in itr test_ex end
@testset [CustomTestSet] [options...] ["description $v, $w"] for v in itrv, w in itrw test_ex end
@testset [CustomTestSet] [options...] ["description"] test_func()
@testset let v = v, w = w; test_ex; endWith begin/end or function call
@testset を begin/end または単一の関数呼び出しとともに使用すると、このマクロは新しいテストセットを開始し、指定された式を評価します。
カスタムのテストセット型を指定しない場合、デフォルトでは DefaultTestSet が作成されます。DefaultTestSet はすべての結果を記録し、Fail または Error がある場合は、最上位(ネストされていない)テストセットの終了時に、テスト結果の概要とともに例外をスローします。
任意のカスタムテストセット型(AbstractTestSet のサブタイプ)を指定できます。その型は、ネストされた @testset の呼び出しにも使用されます。指定したオプションが適用されるのは、そのオプションを指定したテストセットだけです。デフォルトのテストセット型では、次のオプションを指定できます。
verbose::Bool:trueの場合、ネストされたテストセットがすべて成功していても、その結果の概要を表示します(デフォルトはfalse)。showtiming::Bool:trueの場合、表示される各テストセットの実行時間を表示します(デフォルトはtrue)。failfast::Bool:trueの場合、テストの失敗またはエラーが発生すると、テストセットとその子テストセットは直ちに処理を終了します(デフォルトはfalse)。環境変数JULIA_TEST_FAILFASTを使って、これをグローバルに設定することもできます。rng::Random.AbstractRNG: 指定した乱数生成器(RNG)を、テストセットのグローバルな乱数生成器として使用します。rngはcopy!可能でなければなりません。このオプションは、グローバル RNG の状態にのみ依存する確率的なテスト失敗を、その場で再現するのに役立ちます。
説明文字列では、ループのインデックスを補間できます。説明が指定されていない場合は、変数に基づいて説明が自動的に作成されます。関数呼び出しが指定されている場合は、その関数名が使われます。明示的に指定した説明文字列は、これらの動作より優先されます。
デフォルトでは、@testset マクロはテストセットオブジェクト自体を返しますが、この動作は他のテストセット型で変更できます。for ループを使用すると、マクロは finish メソッドの戻り値を集めてリストとして返します。このメソッドはデフォルトで、各反復で使用されたテストセットオブジェクトのリストを返します。
@testset の本体を実行する前に、copy!(Random.default_rng(), rng) が暗黙的に呼び出されます。ここで、rng は現在のタスクの RNG、または rng オプションで渡された RNG です。また、本体の実行後には、グローバル RNG の状態が @testset の実行前の状態に復元されます。これは、失敗時の再現性を高めるとともに、グローバル RNG の状態に対する副作用にかかわらず、@testset を自由に並べ替えられるようにするためです。
rng オプションで変更しない限り、すべてのネストされたテストセットの開始時に同じ RNG が設定されます。テストセットで失敗が発生したときに画面に表示される RNG は、内側のテストセットにユーザーが異なる RNG を手動で設定していても、最外側のテストセットのグローバル RNG です。
Examples
julia> @testset "trigonometric identities" begin
θ = 2/3*π
@test sin(-θ) ≈ -sin(θ)
@test cos(-θ) ≈ cos(θ)
@test sin(2θ) ≈ 2*sin(θ)*cos(θ)
@test cos(2θ) ≈ cos(θ)^2 - sin(θ)^2
end;
Test Summary: | Pass Total Time
trigonometric identities | 4 4 0.2s@testset for
@testset for を使用すると、指定したループの反復ごとに新しいテストセットが開始されます。それ以外の各テストセットの意味は、begin/end の場合と同じです(各ループ反復で使用した場合と同様です)。
@testset let
@testset let を使用すると、指定したオブジェクトをコンテキストオブジェクトとして追加する、透過的なテストセットが開始されます。このテストセット内で失敗またはエラーになったテストには、そのオブジェクトが付加されます。これは、より大きなオブジェクトに関連する一連のテストを実行し、個々のテストが失敗したときにその大きなオブジェクトも表示したい場合に便利です。透過的なテストセットは、テストセット階層に新たなネストレベルを追加せず、コンテキストオブジェクトを失敗したテストに付加したうえで、親テストセットにそのまま渡されます。
Special implicit world age increment for @testset begin and @testset for
@testset begin 内、および @testset for のループ本体内では、各文の後にワールドエイジが暗黙的に進みます。これは通常のトップレベルコードの動作と一致しますが、通常の begin/end ブロックや for ループの動作とは異なります。つまり、ワールドエイジに関しては、@testset begin と @testset for は、本体がトップレベルに記述されたかのように動作します。
Examples
julia> @testset let logi = log(im)
@test imag(logi) == π/2
@test !iszero(real(logi))
end
Test Failed at none:3
Expression: !(iszero(real(logi)))
Evaluated: !(iszero(0.0))
Context: logi = 0.0 + 1.5707963267948966im
ERROR: There was an error during testing
julia> @testset let logi = log(im), op = !iszero
@test imag(logi) == π/2
@test op(real(logi))
end
Test Failed at none:3
Expression: op(real(logi))
Evaluated: op(0.0)
Context: logi = 0.0 + 1.5707963267948966im
op = !iszero
ERROR: There was an error during testingTest.TestSetException — Type
TestSetExceptionテストセットが終了したとき、すべてのテストに合格していない場合にスローされます。
foo(x) 関数のテストを、テストセットにまとめることができます。
julia> @testset "Foo Tests" begin
@test foo("a") == 1
@test foo("ab") == 4
@test foo("abc") == 9
end;
Test Summary: | Pass Total Time
Foo Tests | 3 3 0.0sテストセットは入れ子にすることもできます。
julia> @testset "Foo Tests" begin
@testset "Animals" begin
@test foo("cat") == 9
@test foo("dog") == foo("cat")
end
@testset "Arrays $i" for i in 1:3
@test foo(zeros(i)) == i^2
@test foo(fill(1.0, i)) == i^2
end
end;
Test Summary: | Pass Total Time
Foo Tests | 8 8 0.0s関数を呼び出すこともできます。
julia> f(x) = @test isone(x)
f (generic function with 1 method)
julia> @testset f(1);
Test Summary: | Pass Total Time
f | 1 1 0.0sこの方法を使うと、テストセットを関数に分割できるため、対応する関数を実行して個々のテストセットを実行しやすくなります。関数を呼び出した場合、テストセットには呼び出された関数の名前が付けられます。ここでの例のように、入れ子になったテストセットで失敗がなければ、概要には表示されません。表示するには、verbose=true オプションを渡します。
julia> @testset verbose = true "Foo Tests" begin
@testset "Animals" begin
@test foo("cat") == 9
@test foo("dog") == foo("cat")
end
@testset "Arrays $i" for i in 1:3
@test foo(zeros(i)) == i^2
@test foo(fill(1.0, i)) == i^2
end
end;
Test Summary: | Pass Total Time
Foo Tests | 8 8 0.0s
Animals | 2 2 0.0s
Arrays 1 | 2 2 0.0s
Arrays 2 | 2 2 0.0s
Arrays 3 | 2 2 0.0sEnvironment Variable Support
Test モジュールでは、JULIA_TEST_VERBOSE 環境変数を使って、詳細出力の動作を全体的に制御できます。
JULIA_TEST_VERBOSE=trueの場合、テストセットではデフォルトでverbose=trueが使われます。また、テストセットの開始時と終了時に、所要時間を含む「Starting testset」と「Finished testset」のメッセージが出力されます。JULIA_TEST_VERBOSE=falseの場合、または環境変数が設定されていない場合、テストセットではデフォルトでverbose=falseが使われ、開始・終了メッセージは出力されません。
この環境変数を使うと、テストコードを変更せずにテストスイートの詳細な出力を有効にできるため、デバッグに便利です。
$ JULIA_TEST_VERBOSE=true julia -e '
using Test
@testset "Example" begin
@test 1 + 1 == 2
@testset "Nested" begin
@test 2 * 2 == 4
end
end'
Starting testset: Example
Starting testset: Nested
Finished testset: Nested (0.0s)
Finished testset: Example (0.0s)
Test Summary: | Pass Total Time
Example | 2 2 0.0s
Nested | 1 1 0.0sテストが失敗した場合は、失敗したテストセットの詳細だけが表示されます。
julia> @testset "Foo Tests" begin
@testset "Animals" begin
@testset "Felines" begin
@test foo("cat") == 9
end
@testset "Canines" begin
@test foo("dog") == 9
end
end
@testset "Arrays" begin
@test foo(zeros(2)) == 4
@test foo(fill(1.0, 4)) == 15
end
end
Arrays: Test Failed
Expression: foo(fill(1.0, 4)) == 15
Evaluated: 16 == 15
[...]
Test Summary: | Pass Fail Total Time
Foo Tests | 3 1 4 0.0s
Animals | 2 2 0.0s
Arrays | 1 1 2 0.0s
ERROR: Some tests did not pass: 3 passed, 1 failed, 0 errored, 0 broken.Testing Log Statements
ログ出力をテストするには @test_logs マクロを使うか、TestLogger を使います。
Test.@test_logs — Macro
@test_logs [log_patterns...] [keywords] expressionexpressionがcollect_test_logsを使って生成したログレコードを収集し、それらがlog_patternsの並びと一致することを確認して、expressionの値を返します。keywordsでは、ログレコードを簡単にフィルタリングできます。min_levelキーワードは、テストで収集するログの最小レベルを指定します。match_modeキーワードは、一致判定の方法を指定します(デフォルトの:allでは、すべてのログとパターンがペアごとに一致することを確認します。パターンが並びのどこかで少なくとも一度一致することを確認するには、:anyを使います)。
最も便利なログパターンは、(level,message)の形式の単純なタプルです。タプル要素の数を変えることで、ほかのログメタデータにも一致させられます。これは、handle_message関数を介してAbstractLoggerに渡される引数に対応します。(level,message,module,group,id,file,line)。指定した要素は、デフォルトでは==を使ってログレコードのフィールドとペアごとに照合されます。ただし、標準のログレベルにはSymbolsを、文字列またはSymbol型のフィールドにはRegexsをパターン内で使うことができ、後者はoccursinを使って照合されます。
Examples
警告と複数のデバッグメッセージをログに記録する関数を考えてみましょう。
function foo(n)
@info "Doing foo with n=$n"
for i=1:n
@debug "Iteration $i"
end
42
end情報メッセージは、次のようにテストできます。
@test_logs (:info,"Doing foo with n=2") foo(2)デバッグメッセージもテストする場合は、min_levelキーワードを使って有効にする必要があります。
using Logging
@test_logs (:info,"Doing foo with n=2") (:debug,"Iteration 1") (:debug,"Iteration 2") min_level=Logging.Debug foo(2)ほかのメッセージは無視して特定のメッセージが生成されることだけをテストするには、match_mode=:anyキーワードを設定します。
using Logging
@test_logs (:info,) (:debug,"Iteration 42") min_level=Logging.Debug match_mode=:any foo(100)このマクロは@testと連結して、戻り値もテストできます。
@test (@test_logs (:info,"Doing foo with n=2") foo(2)) == 42警告が出ないことをテストするには、ログパターンを指定せず、min_levelを適切に設定します。
# test that the expression logs no messages when the logger level is warn:
@test_logs min_level=Logging.Warn @info("Some information") # passes
@test_logs min_level=Logging.Warn @warn("Some information") # failsstderr内で、@warnが生成したものではない警告(またはエラーメッセージ)が出ないことをテストする方法については、@test_nowarnを参照してください。
Test.TestLogger — Type
TestLogger(; min_level=Info, catch_exceptions=false)ログに記録されたメッセージをlogs::Vector{LogRecord}フィールドに格納するTestLoggerを作成します。
min_levelを設定すると、LogLevelを制御できます。catch_exceptionsは、ログイベントの生成中に発生した例外を捕捉するかどうかを指定します。また、respect_maxlogは、整数nについて、メッセージをmaxlog=nで最大n回記録する慣例に従うかどうかを指定します。
関連項目:LogRecord。
Examples
julia> using Test, Logging
julia> f() = @info "Hi" number=5;
julia> test_logger = TestLogger();
julia> with_logger(test_logger) do
f()
@info "Bye!"
end
julia> @test test_logger.logs[1].message == "Hi"
Test Passed
julia> @test test_logger.logs[1].kwargs[:number] == 5
Test Passed
julia> @test test_logger.logs[2].message == "Bye!"
Test PassedTest.LogRecord — Type
LogRecord単一のログイベントの結果を格納します。フィールド:
level: ログメッセージのLogLevelmessage: ログメッセージのテキスト内容_module: ログイベントのモジュールgroup: ロググループ(デフォルトでは、ログイベントを含むファイルの名前)id: ログイベントのIDfile: ログイベントを含むファイルline: ログイベントが記録されたファイル内の行kwargs: ログイベントに渡されたキーワード引数
Other Test Macros
浮動小数点値を使った計算には誤差が生じることがあるため、@test a ≈ b を使って近似的な等価性を確認できます。このとき、≈ は \approx のタブ補完で入力できる isapprox 関数です。または、isapprox を直接使うこともできます。
julia> @test 1 ≈ 0.999999999
Test Passed
julia> @test 1 ≈ 0.999999
Test Failed at none:1
Expression: 1 ≈ 0.999999
ERROR: There was an error during testingisapprox のキーワード引数 rtol と atol を設定すると、それぞれ相対許容誤差と絶対許容誤差を指定できます。比較演算子 ≈ の後に指定します。
julia> @test 1 ≈ 0.999999 rtol=1e-5
Test Passedこれは ≈ 固有の機能ではなく、@test マクロ全般の機能です。マクロによって @test a <op> b key=val は @test op(a, b, key=val) に変換されます。ただし、≈ のテストでは特に便利です。
Test.@inferred — Macro
@inferred [AllowedType] f(x)呼び出し式 f(x) が、コンパイラーによって推論された型と同じ型の値を返すかどうかをテストします。型安定性の確認に役立ちます。
f(x) には、任意の呼び出し式を指定できます。型が一致する場合は f(x) の結果を返し、異なる型が見つかった場合は Error Result を返します。
省略可能な AllowedType を指定すると、テストの条件が緩和されます。f(x) の型が AllowedType を法として推論型と一致する場合、または戻り値の型が AllowedType のサブタイプである場合に、テストが成功します。これは、Union{Nothing, T} や Union{Missing, T} のような小さなユニオン型を返す関数の型安定性をテストする際に便利です。
julia> f(a) = a > 1 ? 1 : 1.0
f (generic function with 1 method)
julia> typeof(f(2))
Int64
julia> @code_warntype f(2)
MethodInstance for f(::Int64)
from f(a) @ Main none:1
Arguments
#self#::Core.Const(f)
a::Int64
Body::UNION{FLOAT64, INT64}
1 ─ %1 = :>::Core.Const(>)
│ %2 = (%1)(a, 1)::Bool
└── goto #3 if not %2
2 ─ return 1
3 ─ return 1.0
julia> @inferred f(2)
ERROR: return type Int64 does not match inferred return type Union{Float64, Int64}
[...]
julia> @inferred max(1, 2)
2
julia> g(a) = a < 10 ? missing : 1.0
g (generic function with 1 method)
julia> @inferred g(20)
ERROR: return type Float64 does not match inferred return type Union{Missing, Float64}
[...]
julia> @inferred Missing g(20)
1.0
julia> h(a) = a < 10 ? missing : f(a)
h (generic function with 1 method)
julia> @inferred Missing h(20)
ERROR: return type Int64 does not match inferred return type Union{Missing, Float64, Int64}
[...]Test.@test_deprecated — Macro
@test_deprecated [pattern] expression--depwarn=yesの場合、expressionが非推奨警告を出力することをテストし、expressionの値を返します。ログメッセージ文字列はpatternと照合されます。デフォルト値はr"deprecated"iです。
--depwarn=noの場合は、expressionを実行した結果をそのまま返します。--depwarn=errorの場合は、ErrorExceptionがスローされることを確認します。
Examples
# Deprecated in julia 0.7
@test_deprecated num2hex(1)
# The returned value can be tested by chaining with @test:
@test (@test_deprecated num2hex(1)) == "0000000000000001"Test.@test_warn — Macro
@test_warn msg exprexpr を評価した結果、stderr の出力に msg という文字列が含まれるか、msg 正規表現に一致するかをテストします。msg がブール関数の場合は、msg(output) が true を返すかをテストします。msg がタプルまたは配列の場合は、エラー出力に msg の各要素が含まれるか、または一致するかを確認します。expr を評価した結果を返します。
エラー出力がないことを確認するには、@test_nowarn も参照してください。
注: @warn が生成する警告は、このマクロではテストできません。代わりに @test_logs を使用してください。
Test.@test_nowarn — Macro
@test_nowarn exprexpr を評価したときに、stderr への出力が空であること(警告やその他のメッセージが出力されないこと)をテストします。expr の評価結果を返します。
注:このマクロでは、@warn による警告が発生しないことはテストできません。代わりに @test_logs を使用してください。
Broken Tests
テストが一貫して失敗する場合は、@test_broken マクロを使うように変更できます。失敗が続く場合はテストを Broken として扱い、成功した場合は Error を通じてユーザーに通知します。
Test.@test_broken — Macro
@test_broken ex
@test_broken f(args...) key=val ...本来は成功するはずなのに、現在は常に失敗するテストを示します。式 ex が false と評価されるか、例外を発生させるかをテストします。そうなる場合は Broken Result を返し、式が true と評価される場合は Error Result を返します。これは @test ex broken=true と同等です。
@test_broken f(args...) key=val... 形式は、@test マクロと同様に動作します。
Examples
julia> @test_broken 1 == 2
Test Broken
Expression: 1 == 2
julia> @test_broken 1 == 2 atol=0.1
Test Broken
Expression: ==(1, 2, atol = 0.1)@test_skip を使うと、評価せずにテストをスキップできます。スキップしたテストもテストセットの集計には含まれます。テストは実行されませんが、Broken Result が表示されます。
Test.@test_skip — Macro
@test_skip ex
@test_skip f(args...) key=val ...実行はしないものの、テストのサマリーには含めるべきテストを示します。Brokenとして報告されます。断続的に失敗するテストや、まだ実装されていない機能のテストに便利です。これは@test ex skip=trueと同等です。
@test_skip f(args...) key=val...形式は、@testマクロと同様に機能します。
Examples
julia> @test_skip 1 == 2
Test Broken
Skipped: 1 == 2
julia> @test_skip 1 == 2 atol=0.1
Test Broken
Skipped: ==(1, 2, atol = 0.1)Test result types
Test.Result — Type
Test.Resultすべてのテストは結果オブジェクトを生成します。このオブジェクトが保存されるかどうかは、そのテストがテストセットの一部かどうかによって異なります。
Test.Error — Type
Test.Error <: Test.Result例外が発生したためテスト条件を評価できなかったか、評価結果がBool以外でした。@test_brokenの場合は、予期しないPass Resultが発生したことを示します。
Test.Broken — Type
Test.Broken <: Test.Resultテスト条件は、壊れたテストで予期される(失敗した)結果であるか、@test_skipを指定して明示的にスキップされています。
Creating Custom AbstractTestSet Types
パッケージでは、record メソッドと finish メソッドを実装することで、独自の AbstractTestSet サブタイプを作成できます。このサブタイプには、説明文字列を受け取る1引数コンストラクターを用意し、オプションはキーワード引数として渡します。
Test.record — Function
record(ts::AbstractTestSet, res::Result)テストセットに結果を記録します。この関数は、@testset インフラストラクチャによって、内部に含まれる @test マクロが完了するたびに呼び出され、テスト結果(Error の場合もあります)を受け取ります。また、テストブロック内で @test コンテキストの外側に例外がスローされた場合は、Error を指定して呼び出されます。
Test.finish — Function
finish(ts::AbstractTestSet)指定されたテストセットに必要な最終処理を行います。テストブロックの実行後、@testset インフラストラクチャによって呼び出されます。
カスタムの AbstractTestSet サブタイプは、テスト結果のツリーに自身を追加するため、親が存在する場合はその親に対して record を呼び出す必要があります。これは次のように実装できます。
if get_testset_depth() != 0
# Attach this test set to the parent test set
parent_ts = get_testset()
record(parent_ts, self)
return self
endTest は、テストセットの実行中に入れ子になったテストセットのスタックを管理します。一方、結果の蓄積は AbstractTestSet サブタイプ側で行う必要があります。get_testset メソッドと get_testset_depth メソッドを使うと、このスタックにアクセスできます。これらの関数はエクスポートされていないことに注意してください。
Test.get_testset — Function
get_testset()タスクのローカルストレージからアクティブなテストセットを取得します。アクティブなテストセットがない場合は、フォールバックのデフォルトテストセットを使用します。
Test.get_testset_depth — Function
get_testset_depth()デフォルトのテストセットを除いた、アクティブなテストセットの数を返します。
Test は、入れ子になった @testset の呼び出しで、明示的に指定されていない限り、親と同じ AbstractTestSet サブタイプが使われるようにします。ただし、テストセットのプロパティは引き継ぎません。オプションの継承動作は、Test が提供するスタック機構を使って、パッケージ側で実装できます。
基本的な AbstractTestSet サブタイプは、次のように定義できます。
import Test: Test, record, finish
using Test: AbstractTestSet, Result, Pass, Fail, Error
using Test: get_testset_depth, get_testset
struct CustomTestSet <: Test.AbstractTestSet
description::AbstractString
foo::Int
results::Vector
# constructor takes a description string and options keyword arguments
CustomTestSet(desc; foo=1) = new(desc, foo, [])
end
record(ts::CustomTestSet, child::AbstractTestSet) = push!(ts.results, child)
record(ts::CustomTestSet, res::Result) = push!(ts.results, res)
function finish(ts::CustomTestSet)
# just record if we're not the top-level parent
if get_testset_depth() > 0
record(get_testset(), ts)
return ts
end
# so the results are printed if we are at the top level
Test.print_test_results(ts)
return ts
endこのテストセットは、次のように使います。
@testset CustomTestSet foo=4 "custom testset inner 2" begin
# this testset should inherit the type, but not the argument.
@testset "custom testset inner" begin
@test true
end
endカスタムテストセットを使い、記録された結果を外側のデフォルトテストセットの一部として出力するには、Test.get_test_counts も定義します。たとえば、次のようになります。
using Test: AbstractTestSet, Pass, Fail, Error, Broken, get_test_counts, TestCounts, format_duration
function Test.get_test_counts(ts::CustomTestSet)
passes, fails, errors, broken = 0, 0, 0, 0
# cumulative results
c_passes, c_fails, c_errors, c_broken = 0, 0, 0, 0
for t in ts.results
# count up results
isa(t, Pass) && (passes += 1)
isa(t, Fail) && (fails += 1)
isa(t, Error) && (errors += 1)
isa(t, Broken) && (broken += 1)
# handle children
if isa(t, AbstractTestSet)
tc = get_test_counts(t)::TestCounts
c_passes += tc.passes + tc.cumulative_passes
c_fails += tc.fails + tc.cumulative_fails
c_errors += tc.errors + tc.cumulative_errors
c_broken += tc.broken + tc.cumulative_broken
end
end
# get a duration, if we have one
duration = format_duration(ts)
return TestCounts(true, passes, fails, errors, broken, c_passes, c_fails, c_errors, c_broken, duration)
endTest.TestCounts — Type
TestCountsテストセットの結果を表示するために、結果を再帰的に収集する際の状態を保持します。
フィールド:
customized: このカウント対象のAbstractTestSetに対して、関数get_test_countsがカスタマイズされているかどうか。カスタムメソッドを定義した場合は、必ずtrueをコンストラクターに渡してください。passes: 成功した@test呼び出しの数。fails: 失敗した@test呼び出しの数。errors: エラーが発生した@test呼び出しの数。broken: 破損した@test呼び出しの数。passes: 成功した@test呼び出しの累計数。fails: 失敗した@test呼び出しの累計数。errors: エラーが発生した@test呼び出しの累計数。broken: 破損した@test呼び出しの累計数。duration: 対象のAbstractTestSetの実行時間の合計を、書式化されたStringとして表したもの。
Test.get_test_counts — Function
" gettestcounts(::AbstractTestSet)::TestCounts
テストセット内に直接含まれる各種類のテスト結果の数と、子テストセット全体の合計を再帰的に数える関数です。
カスタム AbstractTestSet では、この関数を実装することで、合計が DefaultTestSet にも表示されるようになります。
カスタム TestSet でこの関数が実装されていない場合、失敗数は x、所要時間は ?s として報告されます。
Test.format_duration — Function
format_duration(::AbstractTestSet)テストセットの実行時間を表示するためのフォーマット済み文字列を返します。
定義されていない場合は、"?s" にフォールバックします。
Test.print_test_results — Function
print_test_results([io::IO], ts::AbstractTestSet, depth_pad=0)AbstractTestSetの結果を、整形された表として出力します。
depth_padは、すべての出力の先頭に追加するパディングの量を指します。ioが指定されていない場合、デフォルトはstdoutです。
Test.finish内で呼び出された場合、finishされたテストセットが最上位のテストセットであるとき。
Test utilities
Test.GenericArray — Type
GenericArrayは、AbstractArrayインターフェースに準拠する汎用配列APIのテストに使用できます。これにより、関数が標準のArray型以外の配列型でも動作することを確認できます。
Test.GenericDict — Type
GenericDictは、AbstractDictインターフェースに準拠する汎用的なdict APIのテストに使用できます。これにより、標準のDict型以外の連想型でも関数が動作することを確認できます。
Test.GenericOrder — Type
GenericOrderを使うと、APIが汎用の順序付き型をサポートしているかテストできます。
Test.GenericSet — Type
GenericSetは、AbstractSetインターフェースを対象とする汎用的な集合APIをテストするために使用できます。これにより、標準のSet型やBitSet型以外の集合型でも関数が動作することを確認できます。
Test.GenericString — Type
GenericStringは、AbstractStringインターフェースに準拠する汎用文字列APIをテストし、関数が標準のString型以外の文字列型でも動作することを確認するために使用できます。
Test.detect_ambiguities — Function
detect_ambiguities(mod1, mod2...; recursive=false,
ambiguous_bottom=false,
allowed_undefineds=nothing)指定したモジュールで定義されている、曖昧なメソッドの(Method,Method)ペアを返します。すべてのサブモジュールを対象にテストするには、recursive=trueを使用します。
ambiguous_bottomは、Union{}型パラメーターだけが原因で発生する曖昧さを含めるかどうかを制御します。ほとんどの場合、falseに設定するのがよいでしょう。Base.isambiguousを参照してください。
allowed_undefinedsの説明については、Test.detect_unbound_argsを参照してください。
Test.detect_unbound_args — Function
detect_unbound_args(mod1, mod2...; recursive=false, allowed_undefineds=nothing)型パラメーターが未束縛の可能性があるMethodのベクトルを返します。すべてのサブモジュールでテストするには、recursive=trueを使用します。
デフォルトでは、未定義のシンボルがあると警告が表示されます。警告を省略するシンボルのコレクションをGlobalRefとして指定すると、この警告を抑制できます。たとえば、次のように設定すると、
allowed_undefineds = Set([GlobalRef(Base, :active_repl),
GlobalRef(Base, :active_repl_backend)])Base.active_replおよびBase.active_repl_backendに関する警告が抑制されます。
Workflow for Testing Packages
前のセクションで紹介したツールを使って、パッケージを作成し、テストを追加する際のワークフローの例を見てみましょう。
Generating an Example Package
このワークフローでは、Example という名前のパッケージを作成します。
pkg> generate Example
shell> cd Example
shell> mkdir test
pkg> activate .Creating Sample Functions
パッケージをテストするには、まずテスト対象となる機能が必要です。そこで、テストできる簡単な関数を Example に追加します。次の内容を src/Example.jl に追加してください。
module Example
export greet, simple_add, type_multiply
function greet()
"Hello world!"
end
function simple_add(a, b)
a + b
end
function type_multiply(a::Float64, b::Float64)
a * b
end
endCreating a Test Environment
Example パッケージのルートディレクトリから test ディレクトリに移動し、そこで新しい環境を有効化して、Test パッケージを環境に追加します。
shell> cd test
pkg> activate .
(test) pkg> add TestTesting Our Package
これで、Example にテストを追加する準備ができました。実行するテストセットを記述した runtests.jl というファイルを test ディレクトリ内に作成するのが一般的です。test ディレクトリ内にこのファイルを作成し、次のコードを追加してください。
using Example
using Test
@testset "Example tests" begin
@testset "Math tests" begin
include("math_tests.jl")
end
@testset "Greeting tests" begin
include("greeting_tests.jl")
end
endインクルードする2つのファイル、math_tests.jl と greeting_tests.jl を作成し、それぞれにテストを追加します。
注:
test環境のProject.tomlにExampleを追加する必要がなかった点に注目してください。これは Julia のテストシステムの利点の一つであり、read about more here できます。
Writing Tests for math_tests.jl
Test.jl の知識を使って、math_tests.jl に追加できるテストの例を示します。
@testset "Testset 1" begin
@test 2 == simple_add(1, 1)
@test 3.5 == simple_add(1, 2.5)
@test_throws MethodError simple_add(1, "A")
@test_throws MethodError simple_add(1, 2, 3)
end
@testset "Testset 2" begin
@test 1.0 == type_multiply(1.0, 1.0)
@test isa(type_multiply(2.0, 2.0), Float64)
@test_throws MethodError type_multiply(1, 2.5)
endWriting Tests for greeting_tests.jl
Test.jl の知識を使って、greeting_tests.jl に追加できるテストの例を示します。
@testset "Testset 3" begin
@test "Hello world!" == greet()
@test_throws MethodError greet("Antonia")
endTesting Our Package
テストと test 内の runtests.jl スクリプトを追加したので、Example パッケージのルートに戻り、Example 環境を再度有効化すれば、Example パッケージをテストできます。
shell> cd ..
pkg> activate .その後、次のようにテストスイートを実行します。
(Example) pkg> test
Testing Example
Status `/tmp/jl_Yngpvy/Project.toml`
[fa318bd2] Example v0.1.0 `/home/src/Projects/tmp/errata/Example`
[8dfed614] Test `@stdlib/Test`
Status `/tmp/jl_Yngpvy/Manifest.toml`
[fa318bd2] Example v0.1.0 `/home/src/Projects/tmp/errata/Example`
[2a0f44e3] Base64 `@stdlib/Base64`
[b77e0a4c] InteractiveUtils `@stdlib/InteractiveUtils`
[56ddb016] Logging `@stdlib/Logging`
[d6f4376e] Markdown `@stdlib/Markdown`
[9a3f8284] Random `@stdlib/Random`
[ea8e919c] SHA `@stdlib/SHA`
[9e88b42a] Serialization `@stdlib/Serialization`
[8dfed614] Test `@stdlib/Test`
Testing Running tests...
Test Summary: | Pass Total
Example tests | 9 9
Testing Example tests passedすべて正しく実行できていれば、上記と同様の出力が表示されます。Test.jl を使えば、パッケージにさらに複雑なテストを追加できます。この例が、開発者が自作パッケージのテストを始める際の参考になれば幸いです。
Code Coverage
テスト中のコードカバレッジ追跡は、pkg> test --coverage フラグを使って有効にできます(より低いレベルでは、julia の引数 --code-coverage を使います)。julia-runtest GitHub アクションでは、デフォルトで有効になっています。
カバレッジを評価するには、ローカルではソースファイルの隣に生成される .cov ファイルを手動で確認するか、CI では julia-processcoverage GitHub アクションを使います。