API reference

trixi_include_kwargs(args; reserved = ())

Turn the arguments args of a testing macro (a tuple of :(key = value) expressions, as they are received by a macro) into a vector of Expr(:kw, ...) expressions that can be spliced into a trixi_include (from TrixiBase.jl) call inside the expression the macro returns:

macro my_test_include(example, args...)    local kwargs = trixi_include_kwargs(args; reserved = (:l2, :linf))    quote        @trixi_test_nowarn trixi_include(@__MODULE__, $(esc(example)); $(kwargs...))        # Use the values passed to the `reserved` arguments `l2` and `linf`.    endend

Keys listed in reserved are consumed by the calling macro itself and are skipped, i.e., they are not forwarded to trixi_include.

This is used by @test_trixi_include_base and encapsulates how the unevaluated keyword arguments of a testing macro have to be passed on to trixi_include.

For bare-symbol values there are three cases:

1. Symbol is also a key in this kwarg list (e.g. seed=6, x=seed): pass an expression so that trixi_include resolves it inside the example after the other override (seed=6) has been applied.
2. Locally-defined values defined in the testset body: @isdefined returns true (same world age), so the actual value is passed.
3. Example-internal variable references (e.g. bare x=seed with no seed= key): on Julia >= 1.12, @isdefined returns false because bindings set inside Base.include have a newer world age; on older Julia the value is visible and also correct (same as the example default).

Example-internal bare symbols are wrapped in a block expression. This preserves example-scope evaluation without passing a Symbol value to trixi_include, which treats a Symbol as a literal value.

For non-Symbol expressions, there are two cases:

1. Literals (numbers, strings, quoted Symbols, ...): the value is the same regardless of the scope, so we can simply pass it on. Note that a quoted symbol literal such as x=:foo is parsed as a QuoteNode, not as a Symbol, and hence lands here and is passed on as the value :foo.
2. Compound expressions (calls, tuples, array/closure literals, e.g. surface_flux=FluxLaxFriedrichs(max_abs_speed)): these typically reference names that are only available inside the example's scope (e.g. brought in by the example's own using Trixi) and are not defined at the macro call site (the testset module). Hence, we must NOT evaluate them at the call site but pass the unevaluated expression through to trixi_include, which splices it into the example and evaluates it in the example's scope.

Both of the latter are achieved by passing the expression on unevaluated via a QuoteNode.

@test_allocations(rhs!, semi, sol, allocs)

Test that the memory allocations of rhs! are below allocs (e.g., from type instabilities), where rhs! is a function with a method rhs!(du, u, semi, t).

@test_trixi_include_base(elixir; additional_ignore_content = Any[],
                                 l2 = nothing, linf = nothing,
                                 RealT_for_test_tolerances = Float64,
                                 atol = 500 * eps(RealT_for_test_tolerances),
                                 rtol = sqrt(eps(RealT_for_test_tolerances)),
                                 parameters...)

Test an elixir file by calling trixi_include(elixir; parameters...).

The additional_ignore_content argument is passed to @trixi_test_nowarn and can be used to ignore additional patterns in the stderr output. By default, only the absence of error output is checked.

If l2 or linf are specified, in addition the resulting L2/Linf errors are compared approximately against these reference values, using atol, rtol as absolute/relative tolerance.

The keyword arguments additional_ignore_content, l2, linf, RealT_for_test_tolerances, atol, and rtol are not passed to trixi_include(elixir; parameters...).

@timed_testset "name of the testset" #= code to test #=

Similar to @testset, but prints the name of the testset and its runtime after execution.

@trixi_test_nowarn expr [additional_ignore_content]

Modified version of @test_nowarn expr that prints the content of stderr when it is not empty and ignores some common info statements. Additional patterns that should be ignored can be passed as a list of strings or regular expressions.

@trixi_testset "name of the testset" #= code to test #=

Similar to @testset, but wraps the code inside a temporary module to avoid namespace pollution. It also includes this file again to provide the definition of @test_trixi_include_base. Moreover, it records the execution time of the testset similarly to @timed_testset.