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.0 RC (2024-04-16 r86468)
#> Platform: x86_64-pc-linux-gnu
#> Running under: Ubuntu 22.04.4 LTS
#>
#> Matrix products: default
#> BLAS: /home/biocbuild/bbs-3.20-bioc/R/lib/libRblas.so
#> LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
#>
#> locale:
#> [1] LC_CTYPE=en_US.UTF-8 LC_NUMERIC=C
#> [3] LC_TIME=en_GB 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: America/New_York
#> tzcode source: system (glibc)
#>
#> attached base packages:
#> [1] stats graphics grDevices utils datasets methods base
#>
#> loaded via a namespace (and not attached):
#> [1] vctrs_0.6.5 cli_3.6.2 knitr_1.46
#> [4] rlang_1.1.3 xfun_0.43 stringi_1.8.3
#> [7] pkgload_1.3.4 purrr_1.0.2 jsonlite_1.8.8
#> [10] biocroxytest_1.1.0 glue_1.7.0 BiocStyle_2.33.0
#> [13] rprojroot_2.0.4 htmltools_0.5.8.1 roxygen2_7.3.1
#> [16] sass_0.4.9 brio_1.1.5 rmarkdown_2.26
#> [19] evaluate_0.23 jquerylib_0.1.4 fastmap_1.1.1
#> [22] yaml_2.3.8 lifecycle_1.0.4 BiocManager_1.30.22
#> [25] stringr_1.5.1 compiler_4.4.0 waldo_0.5.2
#> [28] testthat_3.2.1.1 digest_0.6.35 R6_2.5.1
#> [31] magrittr_2.0.3 bslib_0.7.0 withr_3.0.0
#> [34] tools_4.4.0 desc_1.4.3 xml2_1.3.6
#> [37] cachem_1.0.8