Modern Python Projects Transcripts
Chapter: Testing code
Lecture: Testing code examples in the documentation
0:00 One of the things that we usually forget to keep up to date is the documentation
0:03 mostly because we don't have a tool that will tell us when it's outdated and
0:09 it's no longer valid. pytest can solve part of this problem.
0:13 If you put some code examples in your documentation,
0:16 it can evaluate them and tell you when they are no longer working.
0:19 Take a look at this function.
0:21 We have a documentation that specifies how to use it,
0:24 but actually the documentation is incorrect.
0:27 But if we run pytest with --doctest-modules, parameter,
0:32 it will check for parts of your documentations,
0:34 starting with this triple right angle bracket(>>>).
0:37 If it finds any line like that,
0:39 pytest will treat the following text as python code,
0:43 and it will check that the result of this code is equal to the next line
0:47 in the documentation. If it's not,
0:49 it will report an error. So let's give it a try.
0:59 And as you can see, pytest is complaining that there is a problem with docstring
1:02 of add_two_numbers function.
1:05 It was expecting 5, because here was specified 5.
1:10 But actually the result of adding two numbers was 4.
1:14 So that's a pretty cool way to test that code examples in your documentation are upto date.