Doctest with large binary

Questions / Help
1

I’m trying to write a doctest to show the usage of a particular function, however this function returns a tuple that has the contents of a File.read! inside of it. This causes an issue as I cannot sanely add an example return value that will allow the test to pass.

Example, when run in iex the result will be nicely truncated

iex> my_fun()
{:ok, <<1, 2, 3, ...>>

However in the doctest I can’t use the ... truncation at the end of the binary and presumably would have to paste in the entire contents to make this pass (which would not please someone reading through docs :astonished:)

I see that the docs for File.read! also doesn’t have a usage example, which I would guess is because of this same reason.

Has anyone tackled this before? Or is this a limitation of ExUnit that people tend to work around?

2

I know it’s not really your issue here, but doctests are meant for pure functions without side effects, like reading a file.

But you can read this https://hexdocs.pm/ex_unit/ExUnit.DocTest.html. There are some hints on how to handle the more delicate cases in doctests.

2 Likes
3

Ah yes that makes sense.

I think that usage example will be destined for the readme instead.

4

For functions that don’t fit well into doctests, you can still provide examples in the docs, only omitting the iex> prompt that will run the example through a doctest. Like here, for example: https://hexdocs.pm/elixir/Process.html#sleep/1

1 Like
5

That’s a very good point, I will go with that approach. :thumbsup:

6

Blog post and example on the topic.