Re: [R-pkg-devel] Interpret feedback: not write testthat-tests in examples
If you do want to communicate around tests a bit more, without cluttering the manual, you might find the covrpage package interesting https://yonicd.github.io/covrpage/ It creates a README in the tests folder, with test results, and it can create a vignette with the same content. On dj., jul. 16, 2020 at 19:40, Henrik Bengtsson wrote: If the point of having, say, stopifnot(add(1, 2) == sum(c(1, 2)) is to make it explicit to the reader that your add() function gives the same results as sum(), then I argue that is valid to use in an example. I'm pretty sure I've used that in some of my examples. For the purpose, there should be no reason why you can't use other "assert" functions for this purpose, e.g. testthat::expect_equal(add(1, 2), sum(c(1, 2)) Now, if the point of your "assert" statement is only to validate your package/code, then I agree it should not be in the example code because it adds clutter. Such validation should be in a package test. So, if the former, I suggest you reply to the CRAN Team and explain this. /Henrik On Thu, Jul 16, 2020 at 6:28 AM Richel Bilderbeek wrote: > > Dear R package developers, > > I would enjoy some help regarding some feedback I got on my package from a > CRAN volunteer, as I am unsure how to interpret this correctly. > > This is the feedback I got (I added '[do]'): > > > Please [do] not write testthat-tests in your examples. > > I wonder if this is about using `testthat` or using tests in general. > > To simplify the context, say I wrote a package with a function called `add`, > that adds two numbers. My example code would then be something like this: > > ``` > library(testthat) > > expect_equal(add(1, 2), 3) > ``` > > The first interpretation is about using `testthat`: maybe I should use base R > (`stopifnot`) or another testing library (`testit`) or hand-craft it myself? > > The second interpretation is about using tests in example code. I like to > actively demonstrate that my code works as expected. I checked the policies > regarding examples, and I could not find a rule that I should refrain from > doing so. > > What is the correct response to this feedback? > > Thanks for your guidance, Richel Bilderbeek > > __ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Interpret feedback: not write testthat-tests in examples
The point of an example is to provide an illustration of how the function
should be used for people who are not software developers. IMO any use of any
other functions should be absolutely minimized to reduce the cognitive overload
("you need to understand 13 other concepts before you can understand what this
function does"). Even stopifnot is in my view best avoided, and if you choose
to use it then the use of that function should come _after_ the use of the
function so it can be ignored by the reader without disrupting their reading of
the example.
Complex interactions between functions should be described in vignettes, and
tests should be stored in test code. R package help already has a reputation
for being obtuse to beginners and mixing tests into examples exacerbates that
perception.
On July 16, 2020 10:39:45 AM PDT, Henrik Bengtsson
wrote:
>If the point of having, say,
>
>stopifnot(add(1, 2) == sum(c(1, 2))
>
>is to make it explicit to the reader that your add() function gives
>the same results as sum(), then I argue that is valid to use in an
>example. I'm pretty sure I've used that in some of my examples. For
>the purpose, there should be no reason why you can't use other
>"assert" functions for this purpose, e.g.
>
>testthat::expect_equal(add(1, 2), sum(c(1, 2))
>
>Now, if the point of your "assert" statement is only to validate your
>package/code, then I agree it should not be in the example code
>because it adds clutter. Such validation should be in a package test.
>
>So, if the former, I suggest you reply to the CRAN Team and explain
>this.
>
>/Henrik
>
>On Thu, Jul 16, 2020 at 6:28 AM Richel Bilderbeek
> wrote:
>>
>> Dear R package developers,
>>
>> I would enjoy some help regarding some feedback I got on my package
>from a CRAN volunteer, as I am unsure how to interpret this correctly.
>>
>> This is the feedback I got (I added '[do]'):
>>
>> > Please [do] not write testthat-tests in your examples.
>>
>> I wonder if this is about using `testthat` or using tests in general.
>>
>> To simplify the context, say I wrote a package with a function called
>`add`, that adds two numbers. My example code would then be something
>like this:
>>
>> ```
>> library(testthat)
>>
>> expect_equal(add(1, 2), 3)
>> ```
>>
>> The first interpretation is about using `testthat`: maybe I should
>use base R (`stopifnot`) or another testing library (`testit`) or
>hand-craft it myself?
>>
>> The second interpretation is about using tests in example code. I
>like to actively demonstrate that my code works as expected. I checked
>the policies regarding examples, and I could not find a rule that I
>should refrain from doing so.
>>
>> What is the correct response to this feedback?
>>
>> Thanks for your guidance, Richel Bilderbeek
>>
>> __
>> R-package-devel@r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
>__
>R-package-devel@r-project.org mailing list
>https://stat.ethz.ch/mailman/listinfo/r-package-devel
--
Sent from my phone. Please excuse my brevity.
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Interpret feedback: not write testthat-tests in examples
If the point of having, say, stopifnot(add(1, 2) == sum(c(1, 2)) is to make it explicit to the reader that your add() function gives the same results as sum(), then I argue that is valid to use in an example. I'm pretty sure I've used that in some of my examples. For the purpose, there should be no reason why you can't use other "assert" functions for this purpose, e.g. testthat::expect_equal(add(1, 2), sum(c(1, 2)) Now, if the point of your "assert" statement is only to validate your package/code, then I agree it should not be in the example code because it adds clutter. Such validation should be in a package test. So, if the former, I suggest you reply to the CRAN Team and explain this. /Henrik On Thu, Jul 16, 2020 at 6:28 AM Richel Bilderbeek wrote: > > Dear R package developers, > > I would enjoy some help regarding some feedback I got on my package from a > CRAN volunteer, as I am unsure how to interpret this correctly. > > This is the feedback I got (I added '[do]'): > > > Please [do] not write testthat-tests in your examples. > > I wonder if this is about using `testthat` or using tests in general. > > To simplify the context, say I wrote a package with a function called `add`, > that adds two numbers. My example code would then be something like this: > > ``` > library(testthat) > > expect_equal(add(1, 2), 3) > ``` > > The first interpretation is about using `testthat`: maybe I should use base R > (`stopifnot`) or another testing library (`testit`) or hand-craft it myself? > > The second interpretation is about using tests in example code. I like to > actively demonstrate that my code works as expected. I checked the policies > regarding examples, and I could not find a rule that I should refrain from > doing so. > > What is the correct response to this feedback? > > Thanks for your guidance, Richel Bilderbeek > > __ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Interpret feedback: not write testthat-tests in examples
Dear Richel, The comment itself is pretty clear I think: to be accepted on CRAN you should not use testthat tests in your examples. I can't speak for CRAN but I'm pretty convinced this is for testing in general. Tests are for testing, not for demonstration. Most users of your package will probably have never heard of testthat because they are not package authors. They also probably don't need testthat to use your package, so it distracts them from learning how your package works. Packages like testthat (and RUnit, unity and tinytest) are in the first place aimed at package authors to make sure that their package works as it should and to avoid re-introducing bugs (regressions). Best, Mark On Thu, Jul 16, 2020 at 3:28 PM Richel Bilderbeek < ric...@richelbilderbeek.nl> wrote: > Dear R package developers, > > I would enjoy some help regarding some feedback I got on my package from a > CRAN volunteer, as I am unsure how to interpret this correctly. > > This is the feedback I got (I added '[do]'): > > > Please [do] not write testthat-tests in your examples. > > I wonder if this is about using `testthat` or using tests in general. > > To simplify the context, say I wrote a package with a function called > `add`, that adds two numbers. My example code would then be something like > this: > > ``` > library(testthat) > > expect_equal(add(1, 2), 3) > ``` > > The first interpretation is about using `testthat`: maybe I should use > base R (`stopifnot`) or another testing library (`testit`) or hand-craft it > myself? > > The second interpretation is about using tests in example code. I like to > actively demonstrate that my code works as expected. I checked the policies > regarding examples, and I could not find a rule that I should refrain from > doing so. > > What is the correct response to this feedback? > > Thanks for your guidance, Richel Bilderbeek > > __ > R-package-devel@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-package-devel > [[alternative HTML version deleted]] __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
Re: [R-pkg-devel] Interpret feedback: not write testthat-tests in examples
Richel,
I think that feedback is important. Examples are examples first, and tests
second, as in if your examples no longer work, then maybe you need to check
your underlying code.
{testthat} tests belong in their own `tests` directory, and are used to
directly test your code and provide feedback about whether your code is
working.
The pattern I normally see if you want to directly check the output of an
example is a `stopifnot(x == y)`, but I've never observed having
`expect_equal` in example code.
There might not be a policy against it, but I think the general expectation
is that {testthat} code stays in `tests`, not in examples in the
documentation.
-Robert
On Thu, Jul 16, 2020 at 9:28 AM Richel Bilderbeek <
ric...@richelbilderbeek.nl> wrote:
> Dear R package developers,
>
> I would enjoy some help regarding some feedback I got on my package from a
> CRAN volunteer, as I am unsure how to interpret this correctly.
>
> This is the feedback I got (I added '[do]'):
>
> > Please [do] not write testthat-tests in your examples.
>
> I wonder if this is about using `testthat` or using tests in general.
>
> To simplify the context, say I wrote a package with a function called
> `add`, that adds two numbers. My example code would then be something like
> this:
>
> ```
> library(testthat)
>
> expect_equal(add(1, 2), 3)
> ```
>
> The first interpretation is about using `testthat`: maybe I should use
> base R (`stopifnot`) or another testing library (`testit`) or hand-craft it
> myself?
>
> The second interpretation is about using tests in example code. I like to
> actively demonstrate that my code works as expected. I checked the policies
> regarding examples, and I could not find a rule that I should refrain from
> doing so.
>
> What is the correct response to this feedback?
>
> Thanks for your guidance, Richel Bilderbeek
>
> __
> R-package-devel@r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-package-devel
>
[[alternative HTML version deleted]]
__
R-package-devel@r-project.org mailing list
https://stat.ethz.ch/mailman/listinfo/r-package-devel
[R-pkg-devel] Interpret feedback: not write testthat-tests in examples
Dear R package developers, I would enjoy some help regarding some feedback I got on my package from a CRAN volunteer, as I am unsure how to interpret this correctly. This is the feedback I got (I added '[do]'): > Please [do] not write testthat-tests in your examples. I wonder if this is about using `testthat` or using tests in general. To simplify the context, say I wrote a package with a function called `add`, that adds two numbers. My example code would then be something like this: ``` library(testthat) expect_equal(add(1, 2), 3) ``` The first interpretation is about using `testthat`: maybe I should use base R (`stopifnot`) or another testing library (`testit`) or hand-craft it myself? The second interpretation is about using tests in example code. I like to actively demonstrate that my code works as expected. I checked the policies regarding examples, and I could not find a rule that I should refrain from doing so. What is the correct response to this feedback? Thanks for your guidance, Richel Bilderbeek __ R-package-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-package-devel
