Hacker News Reader

Comment by ch4s3 | Hacker News Reader

Have you seen Elixir's doctests[1]? They're docs with a code example that gets run by your tests, and if the example doesn't work, your tests fail.

[1]https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...

View on HN

Python also has a similar concept: https://docs.python.org/2/library/doctest.html

Sphinx also has additional doc testing methods that let you test the code examples in your actual docs: http://www.sphinx-doc.org/en/stable/ext/doctest.html

I was surprised (and pleased) to find out that Rust has doctests as well.

I haven't seen that before, but I really like it. I've thought before that it'd be a good idea to include tests adjacent to the code they're testing before, but I'm not sure of a good way to do that, particularly in Javascript.

IME it's an OK way to show examples which are validated (and thus don't get broken as the API changes), but it's really not a good way to have actual tests. Terrible debugging experience aside, actual unit tests just make very little sense as part of a documentation.

They're really only for documentation and the simplest of single function unit tests.

The idea is to provide a DRY way to ensure that the examples are correct. Few things are worse than a wrong example.

That's a fine idea and exactly why doctests exist but I am specifically replying to a comment talking about tests. Not testing examples, having actual tests included in the documentation. Which, again, experience taught me is a terrible idea.

I can see that working for a functional language. But how do you specify the side effects?

You would have to assert equality on the value of the data/file/whatever being mutated.

Here's an example:

##Examples

  iex> user = Repo.insert!(%MyApp.User{id: 1, some_state: "whatever"})

  ...> {:ok, user} = MyApp.Users.DataTransformer.transform_with_effects(user)

  ...> Repo.one(where: MyApp.User.id == 1).some_state

  "new state"

Reply on news.ycombinator.com