• View
• Edit
• History
• Print

runnableExamples

doctest is a Python module in the standard library that lets you embed tests directly in docstrings and run them automatically. You have a function, and you can assign the tests to it. No need to put the tests in a separate file, you can embed the tests in the docstring of the function.

In Nim, you can do the same. First, let's see a Python example.

Python

If you execute it, it prints "10" on the screen.

Let's execute the embedded tests:

$ python3 -m doctest -v main.py
Trying:
    twice(5)
Expecting:
    10
ok
Trying:
    twice(-3)
Expecting:
    -6
ok
2 items had no tests:
    main
    main.main
1 item passed all tests:
   2 tests in main.twice
2 tests in 3 items.
2 passed.
Test passed.

The option -v stands for verbose output.

$ python3 -m doctest main.py
$

𝥶In this case, if the tests pass, there's no output.

Of course, if a test fails, you get an error message.

Nim

nim doc is Nim's built-in documentation generator. It extracts documentation comments from .nim source files and produces HTML (or other formats) automatically.

Nim uses ## (double hash) for doc comments.

I want to show later how to generate docs for a module.

This time, I only want to show how to write embedded tests (similarly to Python's doctests), and how to execute these tests.

You cannot execute just the embedded tests. However, if you issue the command nim doc, it'll generate the docs AND it'll execute the tests too.

However! Only exported symbols (marked with *) appear in the docs by default! And only those tests are executed that belong to an exported symbol. So don't forget the * sign!

$ nim doc main.nim

Check the output. If a test fails, you'll get an error message.

The command generates the docs in a directory called htmldocs/. If you just wanted to run the tests, then you can delete this folder.

Gotcha

Every runnableExample is compiled and tested individually. If you want to use something from the standard library, then you need to import it there, inside the runnableExample, instead of importing it at the top level:

Here, toSeq() comes from std/sequtils .