2. Working with doctest

- The first testing tool we're going to look at is called doctest. The name is short for "document testing" or perhaps a "testable document".

*** So, to resume my answer: doctests are useful when you have to write small scripts, and when you have to pass them or show them to researchers that are not computer scientists. dalloliogm in StackOverflow

Where doctest performs best

- The design decisions that went into doctest make it particularly well suited to writing acceptance tests at the integration and system testing levels. The is because doctest mixes human-only text with examples that both humans and computers can read.

- The basic idea you should be getting from all this is that doctest is ideal for uses where humans and computers will both benefit from reading them.

- >>> : prompt are sent to Python interpreter.

  .  .  . : sent as continuations of the code from the previous line.

- Any lines that don't start with >>>, .  .  . , up to the next blank line or >>> prompt represents the output expected from the statement.

- The doctest module ignores anything in the file that isn't part of a test, which means that you can put explanatory text, HTML, line-art diagrams, or whatever else strikes your fancy in between your tests. 

Example - a more complext test

>>> import sys

>>> def test_write():

... sys.stdout.write("Hello\n")

... return True

>>> test_write()

Hello

True

>>> def faulty(:

... yield from [1,2,3,4,5]

Traceback (most recent call last):

SyntaxError: invalid syntax

Expecting blank lines

- The doctest handles this situation by matching a line that contains only the text <BLANKLINE> in the expected output with a real blank line in the actual output.

Controlling doctest behavior with directives

- Directives are specially formatted comments that you can place after the source code of a test and that tell doctest to alter its default behavior in some way. A directive comment begins with # doctest:, after which comes a comma-separated list of options.

a + (plus symbol) -> followed by the behavior name

a - (minus symbol) -> followed by the behavior name.

Ignoring part of the result

- By using the +ELLIPSIS directive, you can make doctest treat the text ...(called an ellipsis) in the expected output as a wildcard that will match any text in the output. 

Example - ellipsis test drive

>>> sys.modules # doctest: +ELLIPSIS

{...} 

>>> 'This is an expression that evaluates to a string'

... # doctest: +ELLIPSIS

'This is ... a string'

>>> 'This is also a string' # doctest: +ELLIPSIS

'This is ... a string'

>>> import datetime

>>> datetime.datetime.now().isoformat() # doctest: +ELLIPSIS

'...-...-...T...:...:...'

Example - invoking normality

>>> print()

<BLANKLINE>

>>> [1, 2, 3, 4, 5, 6, 7, 8, 9]

... # doctest: +NORMALIZE_WHITESPACE

[1, 2, 3,

 4, 5, 6,

 7, 8, 9]

>>> print("This text contains weired spacing.") 

... # doctest: +NORMALIZE_WHITESPACE

This text contains weired              spacing.

>>> print(list(range(5))) # doctest: +NORMALIZE_WHITESPACE

[0, 1, 2, 3,      4]     

Example - humans only(Skipping an example)

>>> 'This test would fail.' # doctest: +SKIP

If it counldn't be worse

The execution scope of doctest tests

- When doctest is running the tests from text files, all the tests from the same file are run in the same execution scope. This means that, if you import a module or bind a variable in one test, that module or variable is still available in later tests.

. How does doctest recognize the beginning of a test in a document? >>>

- How does doctest know when a test continues to further lines? ...

- How does doctest recognize the beginning and end of the expected output of a test? black line and the next sign of >>>

- How would you tell doctest that you want to break the expected output across several lines, even though that's not how the test actually outputs it? # doctest: +ELLIPSIS

- Which parts of an exception report are ignored by doctest? # doctest: +SKIP

- Why do we care what code can see the variables created by a test? It has a high possibility of contaminating other tests.

- How can we make doctest not care what a section of output contains? isolating modules or variables in function.

Exercise - English to doctest

- Try to make the doctests so that they're not just for the computer. Good doctests tend to clarify things for human readers as well.

- docstrings are a Python feature that allows programmers to embed documentation directly into their source code.

Example - a doctest in a docstring

*** docstring is not simple comment but, surprisingly, it is one of the attribute of function. Therefore, it is callable in runtime.

- For those who don't know, docstrings are a Python feature that allows programmers to embed documentation directly into their source code.

def testable(x):

r"""

The 'testable' function returns the square root of its parameter,

or 3, whichever is larger

>>> testable(7)

3.0

>>> testable(16)

4.0

>>> testable(9)

3.0

>>> testable(10) == 10 ** 0.5

True

"""

if x < 9: 

return 3.0

return x ** 0.5

python3 -m doctest -v test.py

- because docstrings need to serve as API documentation - you can see the reason for this just by looking at the example.

*** doctest can replace the document specifications with a sort of tests easily written by human.

Node data

Summary