4 ms·
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://
by ch4s3 9y ago
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-and-with.html#doctests https://elixir-lang.org/getting-started/mix-otp/docs-tests-a...
- wry_discontent 9y agoI 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.
- masklinn 9y agoIME 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.
- ch4s3 9y agoThey're really only for documentation and the simplest of single function unit tests.
- pmontra 9y agoThe idea is to provide a DRY way to ensure that the examples are correct. Few things are worse than a wrong example.
- masklinn 9y agoThat'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.
- amelius 9y agoI can see that working for a functional language. But how do you specify the side effects?
- ch4s3 9y agoYou 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"
- forsaken 9y agoPython also has a similar concept: https://docs.python.org/2/library/doctest.html 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 http://www.sphinx-doc.org/en/stable/ext/doctest.html
- sjellis 9y agoI was surprised (and pleased) to find out that Rust has doctests as well.