The biocroxytest package is a novel tool that enhances the efficiency of test writing in R, particularly for Bioconductor software packages. It leverages the structure of roxygen2 for test writing, which improves readability, code organization, and integrates seamlessly with package documentation.
In Bioconductor, daily tests are run as part of the nightly builds, with a maximum limit of 40 minutes per package. For tests that exceed this limit, developers can set up “long tests” and add their package to the Bioconductor Long Tests builds. However, traditionally separating tests and long tests can be cumbersome.
biocroxytest
addresses this issue by introducing a new roclet,
@longtests, inspired by roxytest. This allows
developers to document and store long tests directly within their roxygen2 comments. By
using the @longtests roclet, extensive tests are run and
checked regularly without impacting the efficiency of the daily build
process.
The @longtests roclet provides a dedicated space for
extensive tests, ensuring they are easily accessible and
well-documented. This not only improves the package’s reliability but
also its maintainability. Thus, biocroxytest
contributes to the creation of robust, reliable, and efficient
Bioconductor packages.
Once the biocroxytest package is installed, you need to carry out two steps to correctly set up long tests in your package:
1 - Add the new roclet to your Description file:
You need to add biocroxytest::longtests_roclet to the
Roxygen section of your Description file. This will enable
roxygen2::roxygenize() to generate long tests from the
@longtest tag. Your Description file should have a line
similar to this:
Roxygen: list(roclets = c("namespace", "rd", "biocroxytest::longtests_roclet"))2 - Run the biocroxytest::use_longtests()
function:
This function sets up the overall infrastructure for long tests. When
run, it creates the longtests/testthat directory and the
longtests/testthat.R file, which are necessary for storing
and running your long tests. Additionally, it generates a file named
.BBSoptions that contains the
RunLongTests: TRUE parameter, indicating that long tests
should be run on the Bioconductor server.
With these two steps, your package will be set up to write, document, and store long tests directly in your roxygen2 comments, improving the efficiency and organization of your test code.
The biocroxytest
package allows you to add extensive tests to your functions using the
@longtests tag in your roxygen comments. Here’s a more
detailed explanation of how to use it:
1 - Add the @longtests tag to your function
documentation:
In your roxygen comments for each function, you can add a
@longtests tag followed by the tests you want to run. These
tests should be written as if they were in a
testthat::test_that() call. For example:
#' A function to do x
#'
#' @param x A number
#'
#' @longtests
#' expect_equal(foo(2), sqrt(2))
#' expect_error(foo("a string"))
#'
#' @return something
foo <- function(x) {
return(sqrt(x))
}In this example, the function foo() has two long tests
associated with it: expect_equal(foo(2), sqrt(2)) and
expect_error(foo("a string")).
2 - Run roxygen2::roxygenise():
After adding the @longtests tags to your functions, you
need to run roxygen2::roxygenise(). This will generate a
new file in the longtests/testthat directory for each R
script that contains functions with @longtests tags. The
generated files will contain testthat::test_that() calls
for each set of long tests.
For instance, if you have the foo() function in a file
named R/functions.R, roxygen2::roxygenise()
will generate a file named
longtests/test-biocroxytest-tests-functions.R with the
following content:
# Generated by biocroxytest: do not edit by hand!
# File R/functions.R: @longtests
testthat::test_that("Function foo() @ L11", {
testthat::expect_equal(foo(2), sqrt(2))
testthat::expect_error(foo("a string"))
})This file contains the long tests for the foo()
function, ready to be run by testthat.
utils::sessionInfo()
#> R version 4.4.1 (2024-06-14)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 24.04.1 LTS
#>
#> Matrix products: default
#> BLAS: /usr/lib/x86_64-linux-gnu/openblas-pthread/libblas.so.3
#> LAPACK: /usr/lib/x86_64-linux-gnu/openblas-pthread/libopenblasp-r0.3.26.so; LAPACK version 3.12.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_US.UTF-8 LC_COLLATE=C
#> [5] LC_MONETARY=en_US.UTF-8 LC_MESSAGES=en_US.UTF-8
#> [7] LC_PAPER=en_US.UTF-8 LC_NAME=C
#> [9] LC_ADDRESS=C LC_TELEPHONE=C
#> [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C
#>
#> time zone: Etc/UTC
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> other attached packages:
#> [1] rmarkdown_2.28
#>
#> loaded via a namespace (and not attached):
#> [1] BiocStyle_2.33.1 jsonlite_1.8.9 compiler_4.4.1
#> [4] BiocManager_1.30.25 brio_1.1.5 xml2_1.3.6
#> [7] stringr_1.5.1 jquerylib_0.1.4 yaml_2.3.10
#> [10] fastmap_1.2.0 R6_2.5.1 knitr_1.48
#> [13] desc_1.4.3 maketools_1.3.1 rprojroot_2.0.4
#> [16] bslib_0.8.0 pillar_1.9.0 rlang_1.1.4
#> [19] utf8_1.2.4 testthat_3.2.1.1 biocroxytest_1.3.0
#> [22] cachem_1.1.0 stringi_1.8.4 roxygen2_7.3.2
#> [25] xfun_0.48 sass_0.4.9 sys_3.4.3
#> [28] pkgload_1.4.0 cli_3.6.3 withr_3.0.2
#> [31] magrittr_2.0.3 digest_0.6.37 lifecycle_1.0.4
#> [34] waldo_0.5.3 vctrs_0.6.5 evaluate_1.0.1
#> [37] glue_1.8.0 buildtools_1.0.0 fansi_1.0.6
#> [40] purrr_1.0.2 tools_4.4.1 htmltools_0.5.8.1