API

The TestTools package provides support for testing and code quality CLIs.

TestTools.install(; kwargs...)

Install all of the CLI utilities.

Keyword arguments

• julia::AbstractString: path to julia executable. Default: path of the current running julia

• bin_dir::AbstractString: directory to install CLI utilities into. Default: ~/.julia/bin

• force::Bool: flag used to indicate that existing CLI executables should be overwritten. Default: false

TestTools.uninstall(; kwargs...)

Unnstall all of the CLI utilities.

Keyword arguments

• bin_dir::AbstractString: directory containing CLI executables to uninstall. Default: ~/.julia/bin

The jltest module provides support for running unit tests.

find_tests(dir::AbstractString), kwargs...) -> Vector{String}

Construct a list of absolute paths to Julia test files contained in dir.

Keyword Arguments

• recursive::Bool: flag indicating whether or not tests found in subdirectories of dir should be included in results. Default: true

• exclude_runtests::Bool: flag indicating whether or not to exclude files named runtests.jl from the list of test files. Default: true

Return Values

• list of paths to Julia test files

run_tests(tests::Vector; kwargs...) -> Dict

run_tests(tests::AbstractString; kwargs...) -> Dict

Run tests in the list of files or modules provided in tests. If tests is an empty list or an empty string, an ArgumentError is thrown. File names in tests may be specified with or without the .jl extension.

Keyword Arguments

• desc::AbstractString: description to use for test set used to group tests. Default: the default description set by @testset

• test_set_type::Type: type of test set to use to group tests. When test_set_type is set to nothing, the tests are run individually. Default: EnhancedTestSet{DefaultTestSet}

  Note

  When the JLTEST_FAIL_FAST environment variable is set to "true", the test_set_type argument is overridden and set to EnhancedTestSet{FallbackTestSet} so that tests are run in fail-fast mode.

• test_set_options::Dict: options to pass to @testset macro

• recursive::Bool: flag indicating whether or not to run tests found in subdirectories of directories in tests. Default: true

• exclude_runtests::Bool: flag indicating whether or not to exclude files named runtests.jl from the list of test files that are run. Default: true

Return Values

• test statistics, such as total number of passed tests, failed tests, errors, and broken tests.

cli.jl defines the jltest.cli module containing functions for the jltest CLI.

Notes

• CLI functions are defined in a .jl file so that testing and code quality tools can by applied to the CLI source code.

run(tests::Vector; kwargs...) -> Bool

Run unit tests defined in the list of files or modules provided in tests.

Keyword Arguments

• fail_fast::Bool: flag indicating whether or not to stop testing at first failure. Default: false

• use_wrapper::Bool: flag indicating whether or not to run tests without first wrapping them in an EnhancedTestSet. Default: true

  Note

  Ignored if fail_fast is set to true.

  Note

  Setting use_wrapper to false will disable EnhancedTestSet functionality within each test files unless the test file

  • explicitly sets the test set when using the @testset macro or

  • calls jltest.run_tests() (without setting the test_set_type keyword argument to nothing).

• recursive::Bool: flag indicating whether or not to run tests found in subdirectories of directories in tests. Default: true

• verbose::Bool: print more output to the console. Default: false

Return Values

true if all tests passed; false otherwise

parse_args(; raw_args::Vector{<:AbstractString}=ARGS) -> Dict

Parse and return CLI arguments contained in raw_args. By default, raw_args is set to ARGS, the command-line arguments provided to the executable that called parse_args().

Return Values

• parsed CLI arguments converted to Julia types

get_wrapped_test_set_type(ts::EnhancedTestSet{T}

Return type of test set wrapped by ts.

The jlcoverage module provides support for analyzing code coverage of unit tests.

display_coverage(coverage_data::Vector; startpath::AbstractString)

Display coverage results provided in coverage_data. File names are displayed relative to startpath. To display absolute paths, set startpath to an empty string. By default, startpath is set to the current working directory.

cli.jl defines the jlcoverage.cli module containing functions for the jlcoverage CLI.

Notes

• CLI functions are defined in a .jl file so that testing and code quality tools can by applied to the CLI source code.

run(paths::Vector; kwargs...)

Run code coverage analysis for files and directories in paths.

Keyword Arguments

• verbose::Bool: print more output to the console. Default: false

parse_args(; raw_args::Vector{<:AbstractString}=ARGS) -> Dict

Parse and return CLI arguments contained in raw_args. By default, raw_args is set to ARGS, the command-line arguments provided to the executable that called parse_args().

Return Values

• parsed CLI arguments converted to Julia types

The jlcodestyle module provides support for checking and enforcing code style.

cli.jl defines the jlcodestyle.cli module containing functions for the jlcodestyle CLI.

Notes

• CLI functions are defined in a .jl file so that testing and code quality tools can by applied to the CLI source code.

run(paths::Vector; kwargs...) -> Bool

Run code style checks for files contained in paths.

Keyword Arguments

• style::JuliaFormatter.AbstractStyle: code style to apply. Default: BlueStyle()

• overwrite::Bool: overwrite existing files with style-corrected versions. Default: false

• verbose::Bool: print more output to the console. Default: false

Return Values

true if style checks pass; false otherwise

parse_args(; raw_args::Vector{<:AbstractString}=ARGS) -> Dict

Parse and return CLI arguments contained in raw_args. By default, raw_args is set to ARGS, the command-line arguments provided to the executable that called parse_args().

Return Values

• parsed CLI arguments converted to Julia types

struct EnhancedTestSet{T<:AbstractTestSet} <: AbstractTestSet

Extension of the AbstracctTestSet type that provides the following functionality:

• display diffs (when available) for comparison test failures;

• support fail-fast (i.e., stop testing at first failure).

EnhancedTestSet(description::AbstractString; kwargs...)

Construct an EnhancedTestSet with the specified description.

Keyword Arguments

• wrap::Type{<:AbstractTestSet}: test set type to wrap. Default: DefaultTestSet