Alright ! Let’s talk about testing in Python specifically using doctest and unittest frameworks. These tools can help you create comprehensive test suites for your code that exercise every line of it. But what exactly are docstrings, and how can they be used as tests?

Docstrings are those little snippets of text at the beginning of a function or class definition in Python code. They provide documentation that can be easily accessed by other developers or even yourself when you forget what a function does. However, did you know that these docstrings also serve as examples for Python’s built-in testing framework?

Python comes with two testing frameworks doctest and unittest. The “doctest” module finds examples in the docstrings for a module and runs them, comparing the output with the expected output given in the docstring. This is great because it allows you to test your code without having to write any additional tests!

Let’s say we have a simple function that adds two numbers together:

# This script defines a function that adds two numbers together and returns their sum.
def add_numbers(x: int, y: int) -> int:
    """Adds two numbers together and returns their sum."""
    return x + y # The return statement is indented to be within the function, and the function's docstring is properly formatted.

# The following code calls the function and prints the result.
print(add_numbers(2, 3)) # The function is called with two integer arguments and the result is printed.

# Output: 5

To test this using doctest, you can run the following command in your terminal or console:

bash
# This script is used to run doctest on a Python file.
# It takes in the name of the Python file as an argument and runs the doctest module on it.

# The first line specifies the interpreter to be used, in this case, python.
# The -m flag is used to run a module as a script.
# The doctest module is specified after the -m flag.
# The name of the Python file is passed as an argument after the module name.
python -m doctest <filename.py>

This will execute all of the docstrings as tests and compare their output to what’s expected. If everything passes, you’ll see a message that says “Trying:”. If anything fails, you’ll get an error message with details about which test failed.

Now how to extract these docstrings for testing purposes. First, make sure your code is properly formatted and includes docstrings for all of the functions or classes you want to test. Then, save a copy of your module as a text file (let’s call it “library.txt” for this example).

Next, open up your terminal or console and navigate to the directory where your library is saved. Run the following command:

# This script is used to run doctests on a Python module and save the results to a text file.
# It assumes that the module has been properly documented with docstrings for all functions and classes.

# First, we need to specify the name of the module we want to test.
# We will use the variable <filename.py> to represent the module name.
# Note: This variable should be replaced with the actual name of the module.
module_name=<filename.py>

# Next, we use the "python -m doctest" command to run the doctests on the specified module.
# The "| tee" command is used to save the output of the doctests to a text file called "extracted_tests.txt".
# The "> /dev/null" command is used to suppress any additional output in the terminal.
python -m doctest $module_name | tee extracted_tests.txt > /dev/null

# Note: The "$" symbol is used to reference the value of a variable in bash.

# After running this script, the "extracted_tests.txt" file will contain the results of the doctests.
# This file can then be used to check the functionality of the module and ensure that all tests are passing.

This will extract all of the docstrings from your module as tests and save them to a new file called “extracted_tests.txt”. The “tee” command is used here so that we can see both the output in our terminal or console (which shows us if any tests failed) and also save it to a separate file for future reference.

And there you have it, You’ve now extracted docstrings from your Python module as tests using doctest. This is a great way to ensure that your code works properly without having to write additional tests or run them manually every time you make changes.