Skip to content

Commit

Permalink
update vignettes
Browse files Browse the repository at this point in the history
  • Loading branch information
@xec-cm
xec-cm committed Jan 17, 2024
1 parent f6831ea commit ebcb1ba
Show file tree
Hide file tree
Showing 2 changed files with 65 additions and 51 deletions.
27 changes: 4 additions & 23 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,26 +24,13 @@ knitr::opts_chunk$set(
[![GitHub pulls](https://img.shields.io/github/issues-pr/xec-cm/biocroxytest)](https://github.com/xec-cm/biocroxytest/pulls)
<!-- badges: end -->

<br>
The `r BiocStyle::Githubpkg("xec-cm/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 `r BiocStyle::Githubpkg("r-lib/roxygen2")` for test writing, which improves readability, code organization, and integrates seamlessly with package documentation.

`r BiocStyle::Githubpkg("xec-cm/biocroxytest")` is an R package inspired by
`r BiocStyle::Githubpkg("mikldk/roxytest")`. It is specifically designed for
the development of Bioconductor packages that require tests with high execution
times.
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.

This package extends the functionality of `roxytest` by introducing a new
roclet, `@longtests`. This innovative feature allows developers to document and
store these long tests directly in their `roxygen2` comments.
`r BiocStyle::Githubpkg("xec-cm/biocroxytest")` addresses this issue by introducing a new roclet, `@longtests`, inspired by `r BiocStyle::Githubpkg("mikldk/roxytest")`. This allows developers to document and store long tests directly within their `r BiocStyle::Githubpkg("r-lib/roxygen2")` comments. By using the `@longtests` roclet, extensive tests are run and checked regularly without impacting the efficiency of the daily build process.

With `r BiocStyle::Githubpkg("xec-cm/biocroxytest")`, developers can now write
comprehensive tests without worrying about slowing down the daily build process.
The `@longtests` roclet provides a dedicated space for these extensive tests,
ensuring they are easily accessible and well-documented. This approach not only
improves the reliability of the package but also enhances its maintainability.
Developers can easily locate, understand, and update these long tests as needed,
leading to more robust and efficient code.

<br>
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, `r BiocStyle::Githubpkg("xec-cm/biocroxytest")` contributes to the creation of robust, reliable, and efficient Bioconductor packages.

## Installation instructions

Expand All @@ -66,8 +53,6 @@ And the development version from [GitHub](https://github.com/xec-cm/biocroxytest
BiocManager::install("xec-cm/biocroxytest")
```

<br>

## Example

Here is how you can use `r BiocStyle::Githubpkg("xec-cm/biocroxytest")` to
Expand Down Expand Up @@ -131,8 +116,6 @@ test_that("Function bar() @ L27", {
})
```

<br>

## Contributing

- If you think you have encountered a bug, please [submit an issue](https://github.com/xec-cm/biocroxytest/issues).
Expand All @@ -141,8 +124,6 @@ test_that("Function bar() @ L27", {

- Working on your first Pull Request? You can learn how from this *free* series [How to Contribute to an Open Source Project on GitHub](https://kcd.im/pull-request)

<br>

## Code of Conduct

Please note that the `r BiocStyle::Githubpkg("xec-cm/biocroxytest")` project is
Expand Down
89 changes: 61 additions & 28 deletions vignettes/biocroxytest.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,6 @@ editor_options:
wrap: 72
---

```{=html}
<style>
body {
text-align: justify}
</style>
```
```{r, include = FALSE}
knitr::opts_chunk$set(
message = FALSE,
Expand All @@ -29,50 +23,82 @@ knitr::opts_chunk$set(
options(digits = 3)
```

<br>

The `r BiocStyle::Githubpkg("xec-cm/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 `r BiocStyle::Githubpkg("r-lib/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.

`r BiocStyle::Githubpkg("xec-cm/biocroxytest")` addresses this issue by introducing a new roclet, `@longtests`, inspired by `r BiocStyle::Githubpkg("mikldk/roxytest")`. This allows developers to document and store long tests directly within their `r BiocStyle::Githubpkg("r-lib/roxygen2")` comments. By using the `@longtests` roclet, extensive tests are run and checked regularly without impacting the efficiency of the daily build process.
The `r BiocStyle::Githubpkg("xec-cm/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 `r BiocStyle::Githubpkg("r-lib/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.

`r BiocStyle::Githubpkg("xec-cm/biocroxytest")` addresses this issue by
introducing a new roclet, `@longtests`, inspired by `r BiocStyle::Githubpkg("mikldk/roxytest")`.
This allows developers to document and store long tests directly within their
`r BiocStyle::Githubpkg("r-lib/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,
`r BiocStyle::Githubpkg("xec-cm/biocroxytest")` contributes to the creation of
robust, reliable, and efficient Bioconductor packages.

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, `r BiocStyle::Githubpkg("xec-cm/biocroxytest")` contributes to the creation of robust, reliable, and efficient Bioconductor packages.

<br>

## biocroxytest setup

Once the `r BiocStyle::Githubpkg("xec-cm/biocroxytest")` package is installed, you need to carry out two steps to correctly set up long tests in your package:
Once the `r BiocStyle::Githubpkg("xec-cm/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
**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:
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
**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 servers.
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 servers.

```{r}
# Create the longtests directory and .BBSoptions file
biocroxytest::use_longtests()
```

With these two steps, your package will be set up to write, document, and store long tests directly in your `r BiocStyle::Githubpkg("r-lib/roxygen2")` comments, improving the efficiency and organization of your test code.
With these two steps, your package will be set up to write, document, and store
long tests directly in your `r BiocStyle::Githubpkg("r-lib/roxygen2")` comments,
improving the efficiency and organization of your test code.


<br>

## Basic Process

The `r BiocStyle::Githubpkg("xec-cm/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:
The `r BiocStyle::Githubpkg("xec-cm/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
**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:
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:

```{r}
#' A function to do x
Expand All @@ -89,14 +115,20 @@ foo <- function(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"))`.
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()`
**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.
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:
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:

```{r results='hide'}
# Generated by biocroxytest: do not edit by hand!
Expand All @@ -109,9 +141,10 @@ testthat::test_that("Function foo() @ L11", {
})
```

This file contains the long tests for the `foo()` function, ready to be run by `r BiocStyle::Githubpkg("r-lib/testthat")`.
This file contains the long tests for the `foo()` function, ready to be run by
`r BiocStyle::Githubpkg("r-lib/testthat")`.


<br>

## Session info

Expand Down

0 comments on commit ebcb1ba

Please sign in to comment.