Documentation¶
Apart from comments in specification there are two additional keywords which are preferred to document the object and describe test cases. These are:
- title
- description
Short summary¶
title is used to present test results to the user.
When used on specification level title is a short summary of object’s goal.
title on test case level indicates test case goal.
When title is missing user will be presented with function name(specification level) or domain(test case level).
Long description¶
description contains actual documentation for programmers.
When used on specification level description is a documentation for object itself.
description on test case level helps understand reasons of particular test and its quirks.
Examples¶
Specification level documentation¶
Note that example below is syntactically correct and will compile without any error. You can preserve TDD workflow without any additional action or jumping between files. You also are not required to have any test cases in specification.
def integral(data):
"""
spec:
title: Calculate integral
description:
Calculates integral using Monte Carlo
"""
Test case level documentation¶
def identity(obj):
"""
spec:
domain 1:
title: Should work properly for integers
description: Provided with 1 function returns 1
results 1
"""
return obj