Roxygen2: Interested in a @tests tag which allows unit tests in the function definition?

[bryanhanson]

I'm wondering what the level of interest is for new tag and corresponding block:

@tests testthat
_unit tests go here_
@nexttag

The idea is that the contents of the unit test block are copied to the relevant directory, in a file called test_functionName, along with the made_by verbiage. I would also allow @tests tinytest but you may consider that blasphemy. I have a working version on my machine which has parse, process, output and clean methods for the roclet.

I think the idea of including unit tests in the function definition file is 100% consistent with the idea of including the documentation in the file. It makes everything easier. I'm inspired by a collaborator who figured out how to attach tests to the function definition and hacked part of testthat to access the reporters.

If this tag is of interest I can fork the repo, bring my code in and make it as consistent as I can with roxygen2 standards, and issue a pull request.

I look forward to your feedback!

[gaborcsardi]

Note that you can implement this tag yourself in your package, see the vignette about extending roxygen.

[bryanhanson]

And that is what I have done (sorry I wasn't completely clear about that). My inquiry was more about whether such a feature was of interest for incorporating into roxygen2.

If there is no interest, that’s perfectly fine of course. I may however request that roxygen2 export some additional functions, as I currently have to use ::: to access them. But I’ll raise a separate issue about that if need be.

[GegznaV]

@gaborcsardi I vote up for this feature to be added.

@bryanhanson Could you give us a link to your package or GitHub repo?

[gaborcsardi]

@bryanhanson which internal roxygen functions do you need?

[bryanhanson]

I'm actually working on a version to submit to roxgyen2 as a pull request, but I have a standalone version. For the standalone I need roxygen2 to export

roxygen_setup,
roxy_meta_load
find_load_strategy
roxy_meta_set
block_set_env

I think these would be needed by anyone wanting to extend roxygen2.

Let me know if you would like a pull request to add the feature to roxygen2 or I should continue with the standalone.

Thanks.

[GegznaV]

@bryanhanson I think you should definitely create a pull request. I this way the developers of roxygen2 will have a chance to review it. Even if PR is not accepted, you will get feedback on why is it so.

[GegznaV]

@bryanhanson What's about the link to your package?

[bryanhanson]

Working standalone version with somewhat awkward but working test system (a separate package within a package): https://github.com/bryanhanson/roxut

Also, needs ::: operator until roxygen2 exports a few more things, so not eligible for CRAN.

[gaborcsardi]

roxygen_setup,
roxy_meta_load
find_load_strategy
roxy_meta_set
block_set_env

It seems that you need these because you are defining your own roxout() function instead of creating a tag and letting roxygenize() or document() do the work.

[gaborcsardi]

As @tests should work perfectly well in its own package, it is quite unlikely that we would merge or review a PR for this, sorry.

[bryanhanson]

Thank you, that’s fine, just wanted to inquire.

On Jun 17, 2020, at 12:38 PM, Gábor Csárdi [e-mail] wrote:

As @tests should work perfectly well in its own package, it is quite unlikely that we would merge or review a PR for this, sorry.

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub https://github.com/r-lib/roxygen2/issues/1104#issuecomment-645481211, or unsubscribe https://github.com/notifications/unsubscribe-auth/AABCIPRTPAJZ6FSJGDKBYBDRXDWO7ANCNFSM4NPLNOCA.

[bryanhanson]

Are you saying to call e.g. `roxygenize(roclets = "tests") as the more native approach?

[bryanhanson]

Figured it out thanks.

[gaborcsardi]

Yes. Let us know if you need something from roxygen.

[gaborcsardi]

One advantage of this approach is that a package can specify

Roxygen: list(packages = "roxut")

and then roxygen will automatically load your package. If you implement a new roclet (which you might or might not need to), then you can also specify the roclets to run.

[bryanhanson]

Could you elaborate? Where do I use this invocation? And how can I specify the roclets?

[gaborcsardi]

It goes in DESCRIPTION. Here is an example: https://github.com/r-lib/pkgdepends/blob/76e91677dcb795f7aaf72f6b6fa64c5afe1d534b/DESCRIPTION#L18

It loads packages (roxygenlabs in this case) which typically define new tags, and if you need an extra or a special roclet, you can also list that here. You could also refer to a roclet as roxygenlabs::roxygenlabs_rd and then roxygenlabs is loaded automatically, no need for packages. But often it is enough to create new tags without new roclets.

People will just need to roxygenize() or devtools::document() and roxygen2 does the rest.

[bryanhanson]

Thanks for your help so far @gaborcsardi it is much appreciated. In DESCRIPTION I have:

Roxygen: list(packages = "roxut", roclets = c("collate", "namespace", "rd", "roxut::tests_roclet"))

and this is accepted by the build and check process, and the package works correctly, but I still have to use roxygenize(roclets = "tests_roclet") in order for the tests roclet to be recognized/active. So I must be missing something since I can't just use roxygenize(). Any suggestions?

Full repo here: https://github.com/bryanhanson/roxut

[bryanhanson]

Nevermind... I see the Roxygen: list... statement goes in a package using roxut, not in roxut.

I figured this out by looking at roxytest a package that already does what roxut does (sad face emoji). Only found this when I looked around on Twitter...

Thanks again for you help.