Unit Testing

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

testsにリストされたJuliaユニットテストを、ncoresプロセッサを使用して実行します。testsは文字列または文字列の配列のいずれかです。exit_on_errorがfalseの場合、1つのテストが失敗しても、他のファイルの残りのテストは引き続き実行されます。exit_on_error == trueの場合は、それ以外のテストは破棄されます。reviseがtrueの場合、テストを実行する前にBaseや標準ライブラリへの変更を読み込むためにReviseパッケージが使用されます。propagate_projectがtrueの場合、現在のプロジェクトがテスト環境に伝播されます。キーワード引数を介してシードが提供されると、それはテストが実行されるコンテキストでグローバルRNGのシードとして使用されます。そうでない場合、シードはランダムに選ばれます。引数julia_argsは、テストプロセスにカスタムjuliaコマンドラインフラグを渡すために使用できます。

@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 を返す代わりに例外をスローします。

例

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 は、実行されるべきではないが、cond==true のときにテストサマリー報告に Broken として含めるべきテストをマークします。これは、断続的に失敗するテストや、まだ実装されていない機能のテストに便利です。通常の @test ex は cond==false のときに評価されます。

例

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

@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

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))."

最後の例では、単一の文字列と一致させる代わりに、次のように行うことも可能でした：

• ["Try", "Complex"]（文字列のリスト）
• r"Try sqrt\([Cc]omplex"（正規表現）
• str -> occursin("complex", str)（マッチング関数）

@testset [CustomTestSet] [options...] ["説明"] begin test_ex end
@testset [CustomTestSet] [options...] ["説明 $v"] for v in itr test_ex end
@testset [CustomTestSet] [options...] ["説明 $v, $w"] for v in itrv, w in itrw test_ex end
@testset [CustomTestSet] [options...] ["説明"] test_func()
@testset let v = v, w = w; test_ex; end

begin/end または関数呼び出しを使用した場合

@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 のシームレスな再配置を可能にすることを目的としています。

例

julia> @testset "三角関数の恒等式" begin
           θ = 2/3*π
           @test sin(-θ) ≈ -sin(θ)
           @test cos(-θ) ≈ cos(θ)
           @test sin(2θ) ≈ 2*sin(θ)*cos(θ)
           @test cos(2θ) ≈ cos(θ)^2 - sin(θ)^2
       end;
テストの要約:            | 合格  合計  時間
三角関数の恒等式 |    4      4  0.2s

@testset for

@testset for が使用されると、マクロは提供されたループの各反復に対して新しいテストを開始します。各テストセットの意味は、begin/end の場合と同じです（各ループ反復に対して使用されるかのように）。

@testset let

@testset let が使用されると、マクロは与えられたオブジェクトをその中に含まれる失敗したテストにコンテキストオブジェクトとして追加した透明なテストセットを開始します。これは、1つの大きなオブジェクトに対して関連するテストのセットを実行する際に便利で、個々のテストのいずれかが失敗したときにこの大きなオブジェクトを印刷することが望ましい場合に役立ちます。透明なテストセットは、テストセット階層に追加のネストレベルを導入せず、親テストセットに直接渡されます（コンテキストオブジェクトは失敗したテストに追加されます）。

@testset begin の特別な暗黙のワールドエイジのインクリメント

@testset begin 内のワールドエイジは、各ステートメントの後に暗黙的にインクリメントされます。これは通常のトップレベルコードの動作と一致しますが、通常の begin/end ブロックの動作とは一致しません。すなわち、ワールドエイジに関しては、@testset begin は begin/end ブロックの本体がトップレベルで書かれているかのように振る舞います。

例

julia> @testset let logi = log(im)
           @test imag(logi) == π/2
           @test !iszero(real(logi))
       end
テスト失敗: none:3
  式: !(iszero(real(logi)))
     コンテキスト: logi = 0.0 + 1.5707963267948966im

ERROR: テスト中にエラーが発生しました

julia> @testset let logi = log(im), op = !iszero
           @test imag(logi) == π/2
           @test op(real(logi))
       end
テスト失敗: none:3
  式: op(real(logi))
     コンテキスト: logi = 0.0 + 1.5707963267948966im
              op = !iszero

ERROR: テスト中にエラーが発生しました

TestSetException

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

@test_logs [log_patterns...] [keywords] expression

expressionによって生成されたログレコードのリストをcollect_test_logsを使用して収集し、それらがlog_patternsのシーケンスと一致することを確認し、expressionの値を返します。keywordsはログレコードの簡単なフィルタリングを提供します：min_levelキーワードはテストのために収集される最小ログレベルを制御し、match_modeキーワードは一致の方法を定義します（デフォルトの:allはすべてのログとパターンがペアで一致することを確認します；:anyを使用すると、パターンがシーケンスのどこかで少なくとも1回一致することを確認します）。

最も便利なログパターンは、形式が(level,message)の単純なタプルです。異なる数のタプル要素を使用して、AbstractLoggerにhandle_message関数を介して渡される引数に対応する他のログメタデータと一致させることができます：(level,message,module,group,id,file,line)。存在する要素は、デフォルトで==を使用してログレコードフィールドとペアで一致します。特別なケースとして、Symbolは標準ログレベルに使用でき、パターン内のRegexは文字列またはSymbolフィールドに対してoccursinを使用して一致します。

例

警告をログに記録し、いくつかのデバッグメッセージを生成する関数を考えてみましょう：

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を適切に設定できます：

# ロガーレベルがwarnのときにメッセージがログに記録されないことをテスト：
@test_logs min_level=Logging.Warn @info("Some information") # 成功
@test_logs min_level=Logging.Warn @warn("Some information") # 失敗

@warnによって生成されないstderrの警告（またはエラーメッセージ）の不在をテストしたい場合は、@test_nowarnを参照してください。

TestLogger(; min_level=Info, catch_exceptions=false)

logs::Vector{LogRecord} フィールドにログメッセージをキャプチャする TestLogger を作成します。

min_level を設定して LogLevel を制御し、catch_exceptions を設定してログイベント生成の一部としてスローされた例外をキャッチするかどうかを決定し、respect_maxlog を設定して、整数 n に対して maxlog=n でメッセージを最大 n 回ログするという慣習に従うかどうかを決定します。

参照: LogRecord。

例

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

LogRecord

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

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

@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_deprecated [pattern] expression

--depwarn=yes の場合、expression が非推奨警告を出力することをテストし、expression の値を返します。ログメッセージ文字列は、デフォルトで r"deprecated"i に対して一致します。

--depwarn=no の場合、単に expression を実行した結果を返します。--depwarn=error の場合、ErrorException がスローされることを確認します。

例

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

# 戻り値は @test でチェーンすることでテストできます:
@test (@test_deprecated num2hex(1)) == "0000000000000001"

@test_warn msg expr

exprを評価した結果がmsg文字列を含むか、msg正規表現に一致するstderr出力を生成するかどうかをテストします。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 に評価されるか、例外を引き起こすことをテストします。これが発生した場合は Broken Result を返し、式が true に評価される場合は Error Result を返します。これは @test ex broken=true と同等です。

@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 ex skip=true と同等です。

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

Test.Result

すべてのテストは結果オブジェクトを生成します。このオブジェクトは、テストがテストセットの一部であるかどうかに応じて、保存される場合とされない場合があります。

Test.Pass <: Test.Result

テスト条件は真でした。すなわち、式は真に評価されるか、正しい例外がスローされました。

Test.Fail <: Test.Result

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

Test.Error <: Test.Result

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

Test.Broken <: Test.Result

テスト条件は、壊れたテストの期待される（失敗した）結果であるか、または明示的に @test_skip でスキップされたものである。

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

テストセットに結果を記録します。この関数は、含まれている @test マクロが完了するたびに @testset インフラストラクチャによって呼び出され、テスト結果（Error である可能性があります）が渡されます。また、テストブロック内で例外がスローされたが @test コンテキストの外にある場合にも Error とともに呼び出されます。

finish(ts::AbstractTestSet)

与えられたテストセットに必要な最終処理を行います。これは、テストブロックが実行された後に @testset インフラストラクチャによって呼び出されます。

カスタム AbstractTestSet サブタイプは、テスト結果のツリーに自分自身を追加するために、親（もしあれば）の record を呼び出す必要があります。これは次のように実装されるかもしれません：

if get_testset_depth() != 0
    # このテストセットを親テストセットに添付する
    parent_ts = get_testset()
    record(parent_ts, self)
    return self
end

get_testset()

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

get_testset_depth()

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

TestCounts

テストセットの結果を再帰的に収集するための状態を保持します。

フィールド:

• customized: get_test_counts 関数がこのカウントオブジェクトのために AbstractTestSet に対してカスタマイズされたかどうか。カスタムメソッドが定義されている場合は、常にコンストラクタに true を渡してください。
• passes: 合格した @test の呼び出しの数。
• fails: 不合格の @test の呼び出しの数。
• errors: エラーのある @test の呼び出しの数。
• broken: 壊れた @test の呼び出しの数。
• passes: 合格した @test の呼び出しの累積数。
• fails: 不合格の @test の呼び出しの累積数。
• errors: エラーのある @test の呼び出しの累積数。
• broken: 壊れた @test の呼び出しの累積数。
• duration: 該当する AbstractTestSet が実行された合計時間をフォーマットされた String として。

" gettestcounts(::AbstractTestSet) -> TestCounts

テストセット内の各タイプのテスト結果の数を直接カウントし、子テストセット全体の合計を計算する再帰関数です。

カスタム AbstractTestSet は、この関数を実装して、合計をカウントし、DefaultTestSet とともに表示する必要があります。

カスタム TestSet に対してこれが実装されていない場合、印刷は失敗に対して x を報告し、所要時間に対して ?s にフォールバックします。

format_duration(::AbstractTestSet)

テストセットが実行された期間を印刷するためのフォーマットされた文字列を返します。

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

print_test_results(ts::AbstractTestSet, depth_pad=0)

AbstractTestSetの結果をフォーマットされたテーブルとして出力します。

depth_padは、すべての出力の前に追加されるパディングの量を指します。

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

GenericArrayは、AbstractArrayインターフェースにプログラムする汎用配列APIをテストするために使用でき、標準のArray型以外の配列型でも関数が機能することを保証します。

GenericDictは、標準のDict型以外の連想型で関数が動作することを確認するために、AbstractDictインターフェースにプログラムする一般的な辞書APIをテストするために使用できます。

GenericOrderは、APIが一般的な順序付き型をサポートしているかどうかをテストするために使用できます。

GenericSetは、標準のSetおよびBitSetタイプ以外のセットタイプで関数が動作することを確認するために、AbstractSetインターフェースにプログラムする一般的なセットAPIをテストするために使用できます。

GenericStringは、AbstractStringインターフェースにプログラムする一般的な文字列APIをテストするために使用でき、標準のString型以外の文字列型でも関数が機能することを保証します。

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

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