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 コマンドラインフラグを渡せます。

source

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 と評価されるか、例外を発生させることをテストします。そうなる場合は Broken Result を返し、式が true と評価される場合は Error Result を返します。通常の @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 Passed
Julia 1.7

broken および skip キーワード引数を使用するには、Julia 1.7 以降が必要です。

source
Test.@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 は、末尾にキーワードを付ける形式をサポートしていないことに注意してください。

Julia 1.8

exception に型または値以外を指定するには、Julia v1.8 以降が必要です。

Julia 1.13

3引数形式の @test_throws extype pattern expr には、Julia v1.12 以降が必要です。

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: ErrorException

3つ目の例では、単一の文字列との照合の代わりに、次の方法も使用できます。

  • ["Try", "Complex"](文字列のリスト)
  • r"Try sqrt\([Cc]omplex"(正規表現)
  • str -> occursin("complex", str)(照合関数)

最後の例では、例外の型(ErrorException)とメッセージパターン("error foo")の両方をテストします。

source

たとえば、新しい関数 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: MethodError

Working with Test Sets

通常、さまざまな入力に対して関数が正しく動作することを確認するため、多数のテストを実行します。テストが失敗した場合、デフォルトでは直ちに例外がスローされます。しかし、テスト対象のコードにどれほどのエラーがあるかを把握するには、残りのテストも実行してから結果を確認するほうが望ましい場合がほとんどです。

Note

@testset は、その中のテストを実行する際に独自のローカルスコープを作成します。

@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; end

With 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 の状態にのみ依存する確率的なテスト失敗を、その場で再現するのに役立ちます。
Julia 1.8

@testset test_func() には Julia 1.8 以降が必要です。

Julia 1.9

failfast には Julia 1.9 以降が必要です。

Julia 1.12

rng オプションには Julia 1.12 以降が必要です。

説明文字列では、ループのインデックスを補間できます。説明が指定されていない場合は、変数に基づいて説明が自動的に作成されます。関数呼び出しが指定されている場合は、その関数名が使われます。明示的に指定した説明文字列は、これらの動作より優先されます。

デフォルトでは、@testset マクロはテストセットオブジェクト自体を返しますが、この動作は他のテストセット型で変更できます。for ループを使用すると、マクロは finish メソッドの戻り値を集めてリストとして返します。このメソッドはデフォルトで、各反復で使用されたテストセットオブジェクトのリストを返します。

@testset の本体を実行する前に、copy!(Random.default_rng(), rng) が暗黙的に呼び出されます。ここで、rng は現在のタスクの RNG、または rng オプションで渡された RNG です。また、本体の実行後には、グローバル RNG の状態が @testset の実行前の状態に復元されます。これは、失敗時の再現性を高めるとともに、グローバル RNG の状態に対する副作用にかかわらず、@testset を自由に並べ替えられるようにするためです。

ネストされたテストセットの RNG

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 を使用すると、指定したオブジェクトをコンテキストオブジェクトとして追加する、透過的なテストセットが開始されます。このテストセット内で失敗またはエラーになったテストには、そのオブジェクトが付加されます。これは、より大きなオブジェクトに関連する一連のテストを実行し、個々のテストが失敗したときにその大きなオブジェクトも表示したい場合に便利です。透過的なテストセットは、テストセット階層に新たなネストレベルを追加せず、コンテキストオブジェクトを失敗したテストに付加したうえで、親テストセットにそのまま渡されます。

Julia 1.9

@testset let には Julia 1.9 以降が必要です。

Julia 1.10

複数の let の割り当ては、Julia 1.10 以降でサポートされています。

Julia 1.13

Julia 1.13 以降では、テストがエラーになった場合にもコンテキストが表示されます。

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 testing
source
Test.TestSetException — Type
TestSetException

テストセットが終了したとき、すべてのテストに合格していない場合にスローされます。

source

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.0s

Environment 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] expression

expressionが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") # fails

stderr内で、@warnが生成したものではない警告(またはエラーメッセージ)が出ないことをテストする方法については、@test_nowarnを参照してください。

source
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 Passed
source
Test.LogRecord — Type
LogRecord

単一のログイベントの結果を格納します。フィールド:

  • level: ログメッセージのLogLevel
  • message: ログメッセージのテキスト内容
  • _module: ログイベントのモジュール
  • group: ロググループ(デフォルトでは、ログイベントを含むファイルの名前)
  • id: ログイベントのID
  • file: ログイベントを含むファイル
  • line: ログイベントが記録されたファイル内の行
  • kwargs: ログイベントに渡されたキーワード引数
source

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 testing

isapprox のキーワード引数 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}
[...]
source
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"
source
Test.@test_warn — Macro
@test_warn msg expr

expr を評価した結果、stderr の出力に msg という文字列が含まれるか、msg 正規表現に一致するかをテストします。msg がブール関数の場合は、msg(output) が true を返すかをテストします。msg がタプルまたは配列の場合は、エラー出力に msg の各要素が含まれるか、または一致するかを確認します。expr を評価した結果を返します。

エラー出力がないことを確認するには、@test_nowarn も参照してください。

注: @warn が生成する警告は、このマクロではテストできません。代わりに @test_logs を使用してください。

source
Test.@test_nowarn — Macro
@test_nowarn expr

expr を評価したときに、stderr への出力が空であること(警告やその他のメッセージが出力されないこと)をテストします。expr の評価結果を返します。

注:このマクロでは、@warn による警告が発生しないことはテストできません。代わりに @test_logs を使用してください。

source

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)
source

@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)
source

Test result types

Test.Result — Type
Test.Result

すべてのテストは結果オブジェクトを生成します。このオブジェクトが保存されるかどうかは、そのテストがテストセットの一部かどうかによって異なります。

source
Test.Pass — Type
Test.Pass <: Test.Result

テスト条件は真でした。つまり、式の評価結果が真であったか、正しい例外がスローされました。

source
Test.Fail — Type
Test.Fail <: Test.Result

テスト条件が偽でした。つまり、式の評価結果が偽だったか、正しい例外がスローされませんでした。

source
Test.Error — Type
Test.Error <: Test.Result

例外が発生したためテスト条件を評価できなかったか、評価結果がBool以外でした。@test_brokenの場合は、予期しないPass Resultが発生したことを示します。

source
Test.Broken — Type
Test.Broken <: Test.Result

テスト条件は、壊れたテストで予期される(失敗した)結果であるか、@test_skipを指定して明示的にスキップされています。

source

Creating Custom AbstractTestSet Types

パッケージでは、record メソッドと finish メソッドを実装することで、独自の AbstractTestSet サブタイプを作成できます。このサブタイプには、説明文字列を受け取る1引数コンストラクターを用意し、オプションはキーワード引数として渡します。

Test.record — Function
record(ts::AbstractTestSet, res::Result)

テストセットに結果を記録します。この関数は、@testset インフラストラクチャによって、内部に含まれる @test マクロが完了するたびに呼び出され、テスト結果(Error の場合もあります)を受け取ります。また、テストブロック内で @test コンテキストの外側に例外がスローされた場合は、Error を指定して呼び出されます。

source
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
end
source

Test は、テストセットの実行中に入れ子になったテストセットのスタックを管理します。一方、結果の蓄積は AbstractTestSet サブタイプ側で行う必要があります。get_testset メソッドと get_testset_depth メソッドを使うと、このスタックにアクセスできます。これらの関数はエクスポートされていないことに注意してください。

Test.get_testset — Function
get_testset()

タスクのローカルストレージからアクティブなテストセットを取得します。アクティブなテストセットがない場合は、フォールバックのデフォルトテストセットを使用します。

source
Test.get_testset_depth — Function
get_testset_depth()

デフォルトのテストセットを除いた、アクティブなテストセットの数を返します。

source

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)
end
Test.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 として表したもの。
source
Test.get_test_counts — Function

" gettestcounts(::AbstractTestSet)::TestCounts

テストセット内に直接含まれる各種類のテスト結果の数と、子テストセット全体の合計を再帰的に数える関数です。

カスタム AbstractTestSet では、この関数を実装することで、合計が DefaultTestSet にも表示されるようになります。

カスタム TestSet でこの関数が実装されていない場合、失敗数は x、所要時間は ?s として報告されます。

source
Test.format_duration — Function
format_duration(::AbstractTestSet)

テストセットの実行時間を表示するためのフォーマット済み文字列を返します。

定義されていない場合は、"?s" にフォールバックします。

source
Test.print_test_results — Function
print_test_results([io::IO], ts::AbstractTestSet, depth_pad=0)

AbstractTestSetの結果を、整形された表として出力します。

depth_padは、すべての出力の先頭に追加するパディングの量を指します。ioが指定されていない場合、デフォルトはstdoutです。

Test.finish内で呼び出された場合、finishされたテストセットが最上位のテストセットであるとき。

source

Test utilities

Test.GenericArray — Type

GenericArrayは、AbstractArrayインターフェースに準拠する汎用配列APIのテストに使用できます。これにより、関数が標準のArray型以外の配列型でも動作することを確認できます。

source
Test.GenericDict — Type

GenericDictは、AbstractDictインターフェースに準拠する汎用的なdict APIのテストに使用できます。これにより、標準のDict型以外の連想型でも関数が動作することを確認できます。

source
Test.GenericOrder — Type

GenericOrderを使うと、APIが汎用の順序付き型をサポートしているかテストできます。

source
Test.GenericSet — Type

GenericSetは、AbstractSetインターフェースを対象とする汎用的な集合APIをテストするために使用できます。これにより、標準のSet型やBitSet型以外の集合型でも関数が動作することを確認できます。

source
Test.GenericString — Type

GenericStringは、AbstractStringインターフェースに準拠する汎用文字列APIをテストし、関数が標準のString型以外の文字列型でも動作することを確認するために使用できます。

source
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を参照してください。

Julia 1.8

allowed_undefinedsにはJulia 1.8以降が必要です。

source
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に関する警告が抑制されます。

Julia 1.8

allowed_undefinedsにはJulia 1.8以降が必要です。

source

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

end

Creating a Test Environment

Example パッケージのルートディレクトリから test ディレクトリに移動し、そこで新しい環境を有効化して、Test パッケージを環境に追加します。

shell> cd test
pkg> activate .
(test) pkg> add Test

Testing 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)
end

Writing Tests for greeting_tests.jl

Test.jl の知識を使って、greeting_tests.jl に追加できるテストの例を示します。

@testset "Testset 3" begin
    @test "Hello world!" == greet()
    @test_throws MethodError greet("Antonia")
end

Testing 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 アクションを使います。

Julia 1.11

Julia 1.11 以降、パッケージのプリコンパイル中にはカバレッジが収集されません。