API

@Test [io=stderr] [set_failed_values=nothing] test_expr

Evaluates test_expr in the context of the Test module (i.e., runs the equivalent to @test $test_expr).

If test_expr does not pass, either due to an exception or the test itself runs but does not return the expected value, an error message is printed to io with the values of the top-level expressions and any bare symbols extracted from test_expr

When executed from an interactive Julia session and

• _GLOBAL_DEFINE_VARS_IN_FAILED_TESTS[] == true and set_failed_values != false

or

• set_failed_values == true

the names + values of the bare symbols in test_expr are set in the Main module to simplify debugging the failing test case.

@test_cases [io=stderr] begin 
    [test cases] 

    [test expressions]
end

Create a set of test data and, for each test data point, evaluates one or more test expressions on them. The values in each test case that cause the test to fail or for an exception to be thrown will be written to io.

Test Case Expressions

[test cases] must be a series of expressions of the form

    variable₁ | variable₂ | ... | variableₙ 
    value₁₁   | value₁₂   | ... | value₁ₙ
    value₂₁   | value₂₂   | ... | value₂ₙ
    ...
    valueₘ₁   | valueₘ₂   | ... | valueₘₙ

Equivalent forms of value₁ | value₂ | ... | valueₙ are

(variable₁ = value₁, variable₂ = value₂, ..., variableₙ = valueₙ)

or

variable₁ => value₁, variable₂ => value₂, ..., variableₙ => valueₙ

Note: The variableᵢ can involve expressions that refer to variableⱼ for any j < i. E.g., the following is a valid [test_case] expression:

    x  | y   | z
    1  | x^2 | y-x

[test cases] may also be a generator expression of the form

(value₁ | value₂ | ... | valueₙ for [valueᵢ₁ in Vᵢ₁, ..., valueᵢⱼ in Vᵢⱼ])

Test Expressions

[test expressions] must be a series of one or more test evaluation expressions

e.g.,

    @test cond₁
    @test cond₂ 
    ...
    @test condₖ

or a single begin ... end expression containing one or more test evaluation expressions, as well as other expressions that will be evaluated for each input data value

e.g.,

begin 
    expr₁ 
    @test cond₁ 
    expr₂
    @test cond₂
    ...
end

Note, each test condition expression condᵢ must evaluate to a Bool and contains zero or more values from variable₁, variable₂, ..., variableₙ.

@test_eventually [io=stderr] [timeout=duration] [sleep=duration] [repeat=false] test_expr

Evalutes test_expr in the context of the Test module (i.e., runs the equivalent to @test $test_expr), and ensures that it passes within a given time frame.

If test_expr does not return a value within the specified timeout, the test fails with a TestTimedOutException. This macro checks sleep amount of time for the test expression to return a value, until timeout is reached.

If repeat == true and the first invocation of test_expr returns false, repeats the call to test_expr until it returns true or it times out.

Duration Types

If key = value is given for key = sleep or key = timeout, then

• if value::Int - the corrresponding duration is converted to a Millisecond(value)
• if value is an expression of the form num*unit for num::Int and unit is one of the shorthand durations (ms, s, m, h, d, w, month, y), the resulting duration will be converted to its equivalent unit from the Dates module e.g., value = 1m => Dates.Minute(1) value = 2s => Dates.Second(2)
• otherwise, value must be a valid Dates.Period expression

TaskTimedOutException(timer)

Exception thrown when the callback function attached to timer took longer than timer.max_time to return a value

TestTimedOutException(max_time, original_ex)

Exception thrown when the test given by original_ex took longer than max_time to return a value

define_vars_in_failed_tests(value::Bool)

If value is true, variables that cause a @Test expression to fail will be defined in Main when Julia is run in interactive mode.

Defaults to true if unset.

set_show_diff_styles(; matching=show_diff_matching_style, differing=show_diff_differing_style)

Sets the local style information for the show_diff method, which is invoked when displaying two differing String values.

Both matching and differing must each be a Pair whose keys and values correspond to the keyword arguments of the Base.printstyled function, or a Vector of such Pairs.

set_show_df_opts(; [max_num_rows::Int=0], [max_num_cols::Int=0], [save_preference::Bool=true])

Sets the local maximum # of rows + columns to show when printing DataFrame values.

If non-positive values for max_num_rows or max_num_cols are provided, these will be set to max_num_of_rows = 5 and max_num_cols = 10, respectively.

If save_preference == true, will save this local preference with keys show_df.max_num_rows, show_df.max_num_cols.

set_show_diff_df_opts(; [max_num_rows::Int = 0], [max_num_cols::Int = 0], [save_preference::Bool = true])

Sets the local maximum # of rows + columns to show when printing differences of DataFrame values.

If either max_num_rows or max_num_cols are non-positive, they will be set to max_num_rows = 10 and max_num_cols = 10, respectively.

If save_preference == true, will save this local preference with keys show_diff_df.max_num_rows, show_diff_df.max_num_cols.

set_max_print_length(; [max_print_length::Int=0], [save_preference::Bool=true])

Sets the local maximum # characters to print for each displayed value in, e.g., a failing test

If max_print_length is not provided or if non-positive values are provided, will be set to max_print_length = 300

If save_preference == true, will save this local preference with key max_print_length