Aqua.jl

Aqua.AquaModule

Aqua.jl: Auto QUality Assurance for Julia packages

Stable Dev GitHub Actions Build Status Codecov GitHub commits since tagged version Aqua QA

Aqua.jl provides functions to run a few automatable checks for Julia packages:

  • There are no method ambiguities.
  • There are no undefined exports.
  • There are no unbound type parameters.
  • There are no stale dependencies listed in Project.toml.
  • Check that test target of the root project Project.toml and test project (test/Project.toml) are consistent.
  • Check that all external packages listed in deps have corresponding compat entry.
  • Project.toml formatting is compatible with Pkg.jl output.

See more in the documentation.

Quick usage

Call Aqua.test_all(YourPackage) from test/runtests.jl, e.g.,

using YourPackage
using Aqua
Aqua.test_all(YourPackage)

Specifying Aqua version

To avoid breaking test when a new Aqua.jl version is released, it is recommended to add version bound for Aqua.jl in test/Project.toml:

[deps]
Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[compat]
Aqua = "0.5"
source
Aqua.test_allMethod
test_all(testtarget::Module)

Run following tests in isolated testset:

Aqua.jl 0.5

Since Aqua.jl 0.5:

  • test_all runs test_ambiguities with Core. This means method ambiguities of constructors can now be detected. In Aqua.jl 0.4, test_ambiguities was invoked with [testtarget, Base].

  • test_all runs test_stale_deps. In Aqua.jl 0.4, this check was opt-in.

The keyword argument $x (e.g., ambiguities) can be used to control whether or not to run test_$x (e.g., test_ambiguities). If test_$x supports keyword arguments, a NamedTuple can also be passed to $x to specify the keyword arguments for test_$x.

Keyword Arguments

  • ambiguities = true
  • unbound_args = true
  • undefined_exports = true
  • project_extras = true
  • stale_deps = true
  • deps_compat = true
  • project_toml_formatting = true
source
Aqua.test_ambiguitiesMethod
test_ambiguities(package::Union{Module, PkgId})
test_ambiguities(packages::Vector{Union{Module, PkgId}})

Test that there is no method ambiguities in given package(s). It calls Test.detect_ambiguities in a separated clean process to avoid false-positive.

Keyword Arguments

  • color::Union{Bool, Nothing} = nothing: Enable/disable colorful output if a Bool. nothing (default) means to inherit the setting in the current process.
  • exclude::AbstractArray = []: A vector of functions or types to be excluded from ambiguity testing. A function means to exclude all its methods. A type means to exclude all its methods of the callable (sometimes also called "functor"). That is to say, MyModule.MyType means to ignore ambiguities between (::MyType)(x, y::Int) and (::MyType)(x::Int, y). Note that there is no way to exclude the constructor of a specific type at the moment.
  • recursive::Bool = true: Passed to Test.detect_ambiguities. Note that the default here (true) is different from detect_ambiguities. This is for testing ambiguities in methods defined in all sub-modules.
  • Other keyword arguments such as imported and ambiguous_bottom are passed to Test.detect_ambiguities as-is.
source
Aqua.test_deps_compatFunction
Aqua.test_deps_compat(package)

Test that Project.toml of package list all compat for deps.

Arguments

  • packages: a top-level Module, a Base.PkgId, or a collection of them.
source
Aqua.test_project_extrasMethod
test_project_extras(package::Union{Module, PkgId})
test_project_extras(packages::Vector{Union{Module, PkgId}})

Check that test target of the root project and test project (test/Project.toml) are consistent. This is useful for supporting Julia < 1.2 while recording test-only dependency compatibility in test/Project.toml.

source
Aqua.test_stale_depsFunction
Aqua.test_stale_deps(package; [ignore])

Test that package loads all dependencies listed in Project.toml.

Known bug

Currently, Aqua.test_stale_deps does not detect stale dependencies when they are stdlib. This is considered a bug and may be fixed in the future. Such a release is considered non-breaking.

Arguments

  • packages: a top-level Module, a Base.PkgId, or a collection of them.

Keyword Arguments

  • ignore::Vector{Symbol}: names of dependent packages to be ignored.
source
Aqua.test_unbound_argsMethod
test_unbound_args(module::Module)

Test that all methods in module and its submodules do not have unbound type parameter.

source