Stream: helpdesk (published)

Topic: Docs as tests?


view this post on Zulip Davi Sales Barreira (Jul 17 2024 at 16:30):

As I'm developing a package, one way I have been using to test the code has been to write down examples and see if the works without throwing an error message. The package I'm coding produces visualizations, so it is not always easy to check for equality in the output, as slight variations might not be an error.

I'm writing the documentation with Documenter.jl and Literate.jl. Whenever the docs are compiled, they also run all the code examples. I was wondering whether I can turn the examples in the docs into actual tests, without manually rewriting the same examples into a testset. On the other hand, is this a bad practice for some reason?

view this post on Zulip jar (Jul 17 2024 at 17:37):

Imo doctests are good for testing that your documentation behaves correctly. Testing that your package behaves correctly is a different job; I don't think it's good to mix them.

view this post on Zulip Gunnar Farnebäck (Jul 17 2024 at 17:46):

Most of the time I would agree about that but it depends on what the package is doing. I have one small package where the tests are the documentation.

view this post on Zulip DrChainsaw (Jul 18 2024 at 10:00):

For the visual testing part, there is VisualRegressionTests.jl which might be helpful.

For the docs as test regardless of the visual part, I have made use of literate to port some old readme examples from before I learned documenter where I could just take the testfile, make use of the #src annotation and add some markdown and more comments, e.g. here which is included in the runtests file and where docs end up like this.

Probably not how I would do it if when starting a new package though.


Last updated: Nov 22 2024 at 04:41 UTC