DidactMacros
Doctest documentation vs testing in a mix project
I went to take a look at the ExUnit.DocTest documentation and the examples provided…
The
doctestmacro loops through all functions and macros defined inMyModule, parsing their documentation in search of code examples.A very basic example is:
iex> 1 + 1 2Expressions on multiple lines are also supported:
iex> Enum.map([1, 2, 3], fn x -> ...> x * 2 ...> end) [2, 4, 6]
…do not resemble the unit testing implementation in the mix stub file that examples the format for unit testing.
defmodule ModuleNameTest do
use ExUnit.Case
doctest ModuleName
test "greets the world" do
assert ModuleName.hello() == :world
end
end
Rather the emphasis is ostensibly on multi-line syntax, and different types of doc testing.
What role does doctest play in mix unit testing?
Does the default file utilise doctest , or is the macro simply present in the starter test file in case of eventual use of doctest tests?
Calling
doctest(Module)will generate tests for all doctests found in themodule.
It is not clear to me what format these are to take inside the module in order to be identifiable.
Marked As Solved
sbuttgereit
I would argue really none.
Doctests test the code examples in the documentation and I would suggest not thinking of them in anyway beyond that or as being related to unit testing. As such they’re relatively simple in form and assumptions are made about those examples such that the macro can automatically generate a test for them.
As for mix stub file. It’s really conflating two things. The doctest ModuleName is just testing the examples and the more extensive unit tests are in the test "greets the world" do [...] lines (and presumably tests thereafter. For a brief example this is fine, but I can see where it could confuse matters some, too.
I actually don’t mix the unit and doc tests in my own tests. I separate out the doctest into its own testing module. That way I can run the documentation testing or run the unit tests alone depending on what I want to focus on.
Also Liked
benwilson512
sbuttgereit
I believe there is.
I’ve mentioned elsewhere that I split my tests into three kinds of testing: unit, integration, and doc tests; each kind of test exists in testing modules which don’t mix kinds of test. This allows me to do something like: @moduletag :unit. Here’s an example of a doctest module:
defmodule DoctestsTest do
use AuthenticationTestCase, async: true
@moduletag :doctest
@moduletag :capture_log
doctest MscmpSystAuthn
end
I then use the --only flag with mix test, for example mix test --only doctest. This will run the doctests and exclude the unit and integration. When I run mix test --only integration, I get only the integration tests and not the unit or doctests. I have to imagine that the other tag oriented mix test options also work as expected.
However, I have also found that explicitly tagging the doctests like I am isn’t necessary. Even when I don’t add the @moduletag :doctest module attribute, the tag is still respected when including or excluding the doctests as though I added it. That tagging must be happening behind the scenes (or something to that effect). I would expect that this probably would work for your scenario of mixed unit/doctest files if you tagged everything else individually; a @moduletag might override the doctest identification (or not, I’ve not tried it)… but it gives hint that excluding doctest on the command line without any additional tagging might be possible.
sodapopcan
OHHHHHHHHHHHHHHHHH I completely misunderstood! Yes, this makes a lot of sense and I quite like this idea. I thought you were saying you moved the actual documentation to a different module from their functions which is what raised my eyebrow 
sodapopcan
To answer this, @doc lines (or perhaps just any comment out line? I’ve never tried anything else) that start with iex> or ...>. The latter is how you do a line continuation. The assertion appears on its own line directly after the last prompt. Basically, you are testing exactly as it would work in an iex session.
@doc """
## Examples
iex> 1 + 1
2
"""
As per the docs, you should also indent examples four spaces. Again, I’m not sure if this is strictly required as I’ve never tried any other way.
sbuttgereit
Hehe… I actually, do in fact do that… but that’s a different topic I believe
I misread your comment. I don’t split docs away from the thing that they document; the API surface of the module is split from the implementation… and the docs follow the API surface functions.
Popular in Questions
Other popular topics
Latest on Elixir Forum
Sponsor Spotlight
Courses that'll move you from confusion to "Aha, now I get it!"
Categories:
Sub Categories:
Forums
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Practical resources that improve the lives of professional developers.
Producing high quality Elixir screencasts since 2017.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"