Test

Base.runtests(tests=["all"]; ncores=ceil(Int, Sys.CPU_THREADS / 2),
              exit_on_error=false, revise=false, [seed])

ncores 個のプロセッサを使って tests が指定する Julia のユニットテストを実行します。tests は文字列または文字列の配列です。exit_on_error が false だといずれかのテストが失敗した場合でも他のファイルのテストは実行され、true だとテストが一つ失敗した時点で全ての実行が終了します。revise が true だと、テストを実行する前に Base および標準ライブラリに対する変更が Revise パッケージを使って読み込まれます。キーワード引数 seed が与えられると、テストを実行するコンテキストにおけるグローバルの RNG がその値でシードされます。seed が与えなければシードはランダムに選ばれます。

@test ex
@test f(args...) key=val ...

式 ex が true に評価されることをテストします。ex の評価結果が true なら Pass 型の値、false なら Fail 型の値、評価できなかったときは Error 型の値を返します (Pass, Fail, Error は Result の部分型です)。

例

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) でない式を渡すとエラーになります。

@test_throws exception expr

式 expr が例外 exception を送出することをテストします。例外は型もしくは値で指定でき、値で指定するとフィールドの比較で等価性が判定されます。@test_throws は末尾にキーワード引数を取る形式をサポートしないことに注意してください。

例

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

@testset [CustomTestSet] [option=val  ...] ["description"] begin ... end
@testset [CustomTestSet] [option=val  ...] ["description $v"] for v in (...) ... end
@testset [CustomTestSet] [option=val  ...] ["description $v, $w"] for v in (...), w in (...) ... end

新しいテストセットを開始します。for ループが与えられた場合は反復ごとに新しいテストセットを開始します。

独自のテストセット型が CustomTestSet に与えられなければデフォルトの DefaultTestSet が使われます。DefaultTestSet は全てのテスト結果を記録してテストセットの終了時にテスト結果を出力し、もし Fail や Error があればトップレベルの (入れ子になっていない) テストセットが終わるときに例外を送出します。

CustomTestSet には独自のテストセット型 (AbstractTestSet の部分型) を指定でき、指定すると入れ子になった @testset の呼び出しでも同じ CustomTestSet が使われます。独自のテストセット型が使われるのはそれが指定されたテストセットでのみです。省略するとデフォルトのテストセット型が使われます。

テストセットを説明する文字列ではループ変数の補間が可能です。説明文字列を与えないと、ループ変数を使って自動的に構築されます。

デフォルトで @testset マクロはテストセットを表すオブジェクトをそのまま返しますが、この振る舞いは独自のテストセット型を使ってカスタマイズできます。for ループを与えると、@testset マクロは各反復に対応するテストセットに対する finish メソッドの返り値を収集してそれを返します。デフォルトの finish は受け取ったテストセットオブジェクトをそのまま返すので、for ループではテストセットオブジェクトの配列が返ります。

@testset の本体を実行する前に Random.seed!(seed) が自動的に呼ばれます。ここで seed は現在のグローバル RNG の現在のシードです。さらに本体の実行が終わるとグローバル RNG の状態は @testset の前の状態に復元されます。これはテストが失敗した場合にも容易に再現性が得られるようにするためであり、グローバル RNG の状態に対する副作用を持つ @testset であっても自由な並べ替えが可能になります。

例

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
trigonometric identities |    4      4

@inferred [AllowedType] f(x)

関数呼び出しの式 f(x) がコンパイラが推論するのと同じ型の値を返すことをテストします。型安全性を確認するときに有用です。

f(x) には任意の関数呼び出し式を指定できます。型が一致するなら f(x) の評価結果を返し、一致しないなら Error 型の値を返します (Error は Result の部分型です)。

省略可能な引数 AllowedType を渡すとテストの条件が緩和されます。具体的には、推論された型の AllowedType を法としたモジュロと f(x) の返り値の型が一致するとき¹、および返り値の型が 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)
Variables
  #self#::Core.Compiler.Const(f, false)
  a::Int64

Body::UNION{FLOAT64, INT64}
1 ─ %1 = (a > 1)::Bool
└──      goto #3 if not %1
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_logs [log_patterns...] [keywords] expression

expression を実行し、生成されるログレコードを collect_test_logs で収集し、それが log_patterns とマッチすることを確認し、expression の評価結果を返します。keywords はログレコードの簡単なフィルタリングを提供します: キーワード引数 min_level は収集/テストが行われる最小ログレベルを制御し、キーワード引数 match_mode はログレコードと log_pattern のマッチを判定する方法を定義します。match_mode がデフォルトの :all だとログレコードの各要素と log_pattern の各要素に対して組ごとにマッチすることが確認され、:any だとログレコードのどれか一つと log_pattern がマッチすることが確認されます。

最も有用な log_patterns は (level,message) の形をした単純なタプルです。これよりも多い要素数のタプルを指定すると、handle_message 関数を通して AbstractLogger に渡されたログメタデータの引数 (level,message,module,group,id,file,line) と (タプルの長さだけ) マッチします。デフォルトではパターンを表すタプルに存在する要素とログフィールドは要素ごとに == で比較されます。ただし例外的に標準のログレベルとのマッチではパターンにシンボルが利用でき、文字列またはシンボルのフィールドと Regex のパターンは occursin で比較されます。

例

一つの @info といくつかの @debug をログとして発生させる関数を考えます:

function foo(n)
    @info "Doing foo with n=$n"
    for i=1:n
        @debug "Iteration $i"
    end
    42
end

@info によるログは次のコードでテストできます:

@test_logs (:info,"Doing foo with n=2") foo(2)

@debug によるログもテストしたい場合には、キーワード引数 min_level で @debug を有効化する必要があります:

@test_logs((:info,"Doing foo with n=2"),
           (:debug,"Iteration 1"),
           (:debug,"Iteration 2"),
           min_level=Debug,
           foo(2))

特定のログだけをテストして他は無視したい場合には、キーワード引数 match_mode=:any を使います:

@test_logs((:info,),
           (:debug,"Iteration 42"),
           min_level=Debug,
           match_mode=:any,
           foo(100))

@test_logs と @test を連鎖させて返り値をテストすることもできます:

@test (@test_logs (:info,"Doing foo with n=2") foo(2)) == 42

@test_deprecated [pattern] expression

コマンドライン引数で --depwarn=yes が指定されているなら、expression が非推奨警告を発生させることをテストし、expression の評価結果を返します。そのときログメッセージの文字列が pattern にマッチすることが確認されます。pattern のデフォルト値は r"deprecated"i です。

--depwarn=no のときは何もせずに expression の評価結果を返します。--depwarn=error なら ErrorExcaption が発生することが確認されます。

例

# Julia 0.7 で非推奨
@test_deprecated num2hex(1)

# @test を使うと返り値をテストできる。
@test (@test_deprecated num2hex(1)) == "0000000000000001"

@test_warn msg expr

expr を評価したときの stderr への出力が文字列もしくは正規表現 msg とマッチすることをテストします。msg が真偽値を返す関数なら、msg(output) が true を返すことがテストされます。msg がタプルまたは配列なら、エラー出力が msg の各要素とマッチすることがテストされます。expr の評価結果を返します。

エラー出力が存在しないことを確認するには @test_nowarn を使ってください。

注意: @warn が生成する警告はこのマクロでテストできません。@test_logs を使ってください。

@test_nowarn expr

expr を評価したときに stderr に何も出力されないこと (警告などのメッセージがないこと) をテストします。expr の評価結果を返します。

注意: @warn が生成する警告が存在しないことはこのマクロでテストできません。@test_logs を使ってください。

@test_broken ex
@test_broken f(args...) key=val ...

「このテストはパスするべきだが、現在は確実に失敗する」という印をテストに付けます。式 ex が false に評価されることをテストし、true に評価されたら例外を送出します。テストが失敗したら Broken 型の値を返し、成功したら Error 型の値を返します (Broken と Error は Result の部分型です)。

@test_broken f(args...) key=val... の意味は @test と同様です。

例

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 ex
@test_skip f(args...) key=val ...

「このテストを実行してはいけないが、テストセットの要約には Broken として含まれるべきである」という印をテストに付けます。断続的に失敗するテストや実装されていない機能のテストでこのマクロは有用です。

@test_skip f(args...) key=val... の意味は @test と同様です。

例

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)

record(ts::AbstractTestSet, res::Result)

テストセットに結果を記録します。この関数はテストセットに含まれる @test マクロが完了するたびに @testset 機構によって呼ばれ、そのときテストの結果が渡されます (結果は Error である可能性もあります)。またテストブロック内の @test コンテキストでない場所で例外が発生したときにも、record は Error と共に呼ばれます。

finish(ts::AbstractTestSet)

テストセットで必要な最終処理を行います。これは @testset 機構によってテストブロックの実行が終わったときに呼ばれます。この関数では get_testset を使ってテストセットを親の結果リストに追加する処理がよく行われます。

get_testset()

アクティブなテストセットをタスクローカルのストレージから取得します。アクティブなテストセットが存在しなければ、デフォルトの FallbackTestSet を返します。

get_testset_depth()

アクティブなテストセットの個数を返します。個数に FallbackTestSet は含みません。