16. Unit Testing - Doctest and Unittest.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*********************************************************************************************************\n",
    "# A Tour of Python 3  \n",
    "version 1.0.1  \n",
    "Authors: Phil Pfeiffer, Zack Bunch, and Feyisayo Oyeniyi  \n",
    "East Tennessee State University  \n",
    "Last updated June 2021  \n",
    " \n",
    "Section 16.3: author Brett Hamilton; ed. Phil Pfeiffer  \n",
    "*********************************************************************************************************"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 16. Unit Testing - Doctest and Unittest  \n",
    " 16.1 [Overview](#Unit-Testing-Overview)  \n",
    " 16.2 [Doctest](#Unit-Testing-Doctest)  \n",
    " 16.3 [Unittest](#Unit-Testing-Unittest)  \n",
    "&ensp; 16.3.1 [Overview](#Unit-Testing-Unittest-Overview)  \n",
    "&ensp; 16.3.2 [Creating and running test cases](#Unit-Testing-Unittest-Test-Cases)  \n",
    "&ensp; 16.3.3 [Organizing and expanding unit testing](#Unit-Testing-Unittest-Organizing-Testing)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 16.1  Overview <a name='Unit-Testing-Overview'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Unit testing*, the testing of a program's individual modules, is a standard starting point for program testing. ",
    "Assuring that a program's modules work in isolation from one another before attempting *integration testing*--the ",
    "testing of those modules in combination--simplifies the overall testing of a program's operation.\n",
    "\n",
    "This module introduces two standard Python frameworks for unit testing: \n",
    "-  `docttest` - a classic framework that uses specially formatted comments embedded in source code to drive testing.\n",
    "-  `unittest` - a later framework, a port of the cross-language `nUnit` test framework to Python, that uses classes with specially named methods to manage testing."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 16.2 Doctest  <a name='Unit-Testing-Doctest'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Docstrings have a special significance for the Python library's [`doctest`](https://docs.python.org/3/library/doctest.html) module. ",
    "This module's `run` method\n",
    "-  searches docstrings for substrings that are formatted as docstring-like test cases\n",
    "    -  Test cases are signaled with initial \">>>\" prompt strings.\n",
    "-  executes those commands to confirm that they return the specified results and/or have the desired effects.\n",
    "    -  Expected results are given after the commands to execute.\n",
    "    -  \"Traceback\" results are treated specially: ",
    "    ..., with the ELLIPSIS option enabled, causes `doctest` to ignore Traceback details when checking expected results.\n",
    "\n",
    "The Python library manual's documentation gives further examples for running `doctest` on entire modules-- ",
    " i.e., .py files-- from the command line as well as from Python codes: a mode of use that the manual says is much more common in practice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 16.2   A sample routine for generating powers of 2, with doctest code.\n",
    "\n",
    "def powers_of_2():\n",
    "  \"\"\"generate successive powers of 2, starting with 2^0 \"\"\"\n",
    "  current_power_of_2 = 1\n",
    "  while True:\n",
    "    yield current_power_of_2\n",
    "    current_power_of_2 *= 2\n",
    "\n",
    "def print_first_n_powers_of_2(n):\n",
    "  \"\"\"  print the first n powers of 2, starting with 2^0\n",
    "\n",
    "  routine prints the first n powers of 2 for a user-supplied integer n,\n",
    "  starting with 2^0 and ending with 2^n-1.\n",
    "\n",
    "  >>> print_first_n_powers_of_2(0.5)\n",
    "  Traceback (most recent call last):\n",
    "     ...\n",
    "  TypeError: 'float' object cannot be interpreted as an integer\n",
    "  >>> print_first_n_powers_of_2(-1)\n",
    "  >>> print_first_n_powers_of_2(0)\n",
    "  >>> print_first_n_powers_of_2(1)\n",
    "  1\n",
    "  >>> print_first_n_powers_of_2(5)\n",
    "  1\n",
    "  2\n",
    "  4\n",
    "  8\n",
    "  16\n",
    "  \"\"\"\n",
    "  p2 = powers_of_2()           # obtain a copy of the generator function for local use\n",
    "  for i in range(0,n):  print(next(p2))\n",
    "\n",
    "import doctest\n",
    "\n",
    "# Show all test cases and their results as the cases execute\n",
    "doctest.run_docstring_examples(print_first_n_powers_of_2, None, optionflags=doctest.ELLIPSIS, verbose=True)\n",
    "\n",
    "# Limit output to failed tests (default)\n",
    "doctest.run_docstring_examples(print_first_n_powers_of_2, None, optionflags=doctest.ELLIPSIS)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 16.3 Unittest <a name='Unit-Testing-Unittest'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 16.3.1 Overview <a name='Unit-Testing-Unittest-Overview'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The standard Python library includes `unittest`: a framework for automating the testing of Python programs.",
    " `unittest` manages testing using three main components: \n",
    "- **Test Case** - A code that that tests a second code's operations. ",
    " A test case should test one aspect of the code under test. \n",
    "- **Test Suite** - A collection of test cases or other test suites that are to be tested together. ",
    " While `unittest` will automatically combine test cases, ",
    "`TestSuite` provides more control over what a test session will test. \n",
    "- **Test Runner** - The part of `unittest` that controls test execution and output. ",
    " It collects success and failure data and outputs summary information. \n",
    " \n",
    "`unittest` uses values returned by `unittest` assert methods to determine a test's outcome. ",
    "The test runner collects these values and displays the results at the end of the test. ",
    "The most common assert methods include the following:\n",
    "\n",
    " &ensp;&ensp; `assertEqual(a, b)` - asserts a == b  \n",
    " &ensp;&ensp; `assertNotEqual(a, b)` - asserts a != b  \n",
    " &ensp;&ensp; `assertTrue(a)` - asserts a is `True`  \n",
    " &ensp;&ensp; `assertFalse(a)` - asserts a is `false`  \n",
    " &ensp;&ensp; `assertIn(a, b)` - asserts a is a member of b  \n",
    " &ensp;&ensp; `assertNotIn(a)` - asserts a is not a member of b  \n",
    " \n",
    " For a full list of assert methods, refer to the ",
    " [`unittest` documentation.](https://docs.python.org/3/library/unittest.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 16.3.2 Creating and running test cases <a name='Unit-Testing-Unittest-Test-Cases'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A `unittest` test case is a specially named method in a subclass of `unittest`'s `TestCase` class. ",
    "All test methods must begin with the word 'test'. \n",
    "\n",
    "Test methods should use one or more assert methods that test a code's operation. ",
    "After each test case completes, the test runner displays a summary of the values returned by its assert methods. ",
    "Failed tests will display a traceback to the failed assert method and a descriptive error message."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 16.3.2 Showing the creation and execution of a test case, using assert methods to test methods of shape classes.\n",
    "# Output includes data from passed and failed test.\n",
    "\n",
    "# unittest - unit testing framework from the standard Python library\n",
    "# math - library providing math calculations and special numbers, i.e. pi\n",
    "\n",
    "import unittest\n",
    "import math\n",
    "\n",
    "class Shape:\n",
    "  def __init__(self, name, color):\n",
    "    self.name = name\n",
    "    self.color = color\n",
    "    \n",
    "  def describe(self):\n",
    "    return f\"Name: {self.name}\\nColor: {self.color}\"\n",
    "\n",
    "class Square(Shape):\n",
    "  def __init__(self, name, color, side):\n",
    "    super().__init__(name, color)\n",
    "    self.side = side\n",
    "        \n",
    "  def get_area(self):\n",
    "    return self.side * self.side\n",
    "\n",
    "  def get_perimeter(self):\n",
    "    return self.side * 4\n",
    "\n",
    "class Circle(Shape):\n",
    "  def __init__(self, name, color, radius):\n",
    "    super().__init__(name, color)\n",
    "    self.radius = radius\n",
    "    \n",
    "  def get_area(self):\n",
    "    return math.pi * (self.radius * self.radius)\n",
    "\n",
    "# Must inherit from TestCase\n",
    "class TestShapes(unittest.TestCase):\n",
    "  # Test cases all begin with word 'test'\n",
    "  def test_constructors(self):\n",
    "    # Test the Shape class\n",
    "    my_shape = Shape(\"shape\", \"blue\")\n",
    "    self.assertEqual(my_shape.name, \"shape\") # Assert both arguments are equal\n",
    "    self.assertEqual(my_shape.color, \"blue\")\n",
    "    \n",
    "    # Test the Square subclass\n",
    "    my_square = Square(\"square\", \"red\", 8)\n",
    "    self.assertEqual(my_square.name, \"square\")\n",
    "    self.assertEqual(my_square.color, \"red\")\n",
    "    self.assertEqual(my_square.side, 8)\n",
    "    \n",
    "    # Test the Circle subclass\n",
    "    my_circle = Circle(\"circle\", \"yellow\", 4)\n",
    "    self.assertEqual(my_circle.name, \"circle\")\n",
    "    self.assertEqual(my_circle.color, \"yellow\")\n",
    "    self.assertEqual(my_circle.radius, 4)\n",
    "    \n",
    "  def test_square_area(self):\n",
    "    my_square = Square(\"square\", \"red\", 8)\n",
    "    self.assertTrue(my_square.get_area() == 63) # This test will fail\n",
    "    \n",
    "  def test_circle_area(self):\n",
    "    my_circle = Circle(\"circle\", \"yellow\", 4)\n",
    "    self.assertTrue(my_circle.get_area() == math.pi * (4 * 4)) # Assert expression evaluates True\n",
    "    \n",
    "# Use the main function from the unittest module\n",
    "unittest.main(argv=[''], verbosity=2, exit=False)        "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 16.3.2.1:**\n\n",
    "</span>",
    "<span style='color:navy' >",
    "In the following code cell, ",
    " add a method to the previous example's Circle class that computes the circle's diameter. ",
    " Write a test method to test if the diameter calculation is correct.",
    "</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 16.3.3 Organizing and expanding unit testing <a name='Unit-Testing-Unittest-Organizing-Testing'></a>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`unittest` provides optional methods for initializing and finalizing testing:\n",
    "\n",
    " - `setUp()` - If this method is present, test runner will execute it before any other method, ",
    "   making it a place to instantiate objects, create or open files, ",
    "   or initialize other resources that the test methods will use. \n",
    " - `tearDown()` - If this method is present, test runner will execute it last, ",
    "   making it a place to finalize and deallocate resources after tests run. \n",
    " \n",
    "`unittest` also provides three decorators that specify conditions in which tests may be skipped:\n",
    " - `@unittest.skip(reason)` - unconditionally skip this test \n",
    " - `@unittest.skipIf(condition, reason)` - skip this test when `condition` evaluates to True \n",
    " - `@unittest.skipUnless(reason)` - skip this test when `condition` evaluates to False \n",
    " \n",
    "`unittest` displays the `reason` argument when a test is skipped."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# 16.3.3 Demonstrating the use of setUp() and tearDown(); decorators for skipping tests; and\n",
    "# @unittest.expectedFailure - decorator that informs the test runner to expect this test method to have a failed\n",
    "\n",
    "import unittest\n",
    "\n",
    "class Letters:\n",
    "  def __init__(self, letters):\n",
    "    self.letters = letters\n",
    "    \n",
    "  def compare_letters(self, a, b):\n",
    "    # Return 1 is a > b, -1 if a < b, 0 if a == b\n",
    "    return 1 if ord(a) > ord(b) else (-1 if ord(a) < ord(b) else 0)\n",
    "\n",
    "  def get_dict(self):\n",
    "    # Return dict with keys of letters in list and values of how many times they appear\n",
    "    d = {}\n",
    "    for letter in self.letters:\n",
    "      if letter in d.keys():\n",
    "        d[letter] += 1\n",
    "      else:\n",
    "        d[letter] = 1\n",
    "    return d\n",
    "\n",
    "  def combine_letters(self):\n",
    "    # Combine letters in list to make a string\n",
    "    string = \"\"\n",
    "    for letter in self.letters:\n",
    "      string += letter\n",
    "    return string\n",
    "\n",
    "class TestShapes(unittest.TestCase):\n",
    "  def setUp(self):\n",
    "    # Create objects that the test methods will use\n",
    "    self.my_letters1 = Letters( ['a', 'b', 'c', 'c', 'd', 'd'] )\n",
    "    self.my_letters2 = Letters( ['a', 'a', 'b', 'b', 'c', 'd'] )\n",
    "    self.my_letters3 = Letters( ['p', 'r', 'o', 'g', 'r', 'a', 'm', 'm', 'i', 'n', 'g'] )\n",
    "\n",
    "  @unittest.skipIf('get_dict' not in dir(Letters), \"get_dict does not exist in class Letters\")\n",
    "  def test_get_dict(self):\n",
    "    my_dict1 = self.my_letters1.get_dict()\n",
    "    my_dict2 = self.my_letters2.get_dict()\n",
    "    self.assertIn( \"d\", my_dict1.keys() )\n",
    "    self.assertEqual( my_dict2['b'], 2)\n",
    "\n",
    "  @unittest.skip(\"unconditional skip\") # This test will always be skipped\n",
    "  def test_combine_letters(self):\n",
    "    string = self.my_letters3.combine_letters()\n",
    "    self.assertEqual( string, \"programming\")\n",
    "    \n",
    "  @unittest.expectedFailure # This test will 'pass' if assert method fails\n",
    "  def test_compare_letters(self):\n",
    "    result = self.my_letters1.compare_letters(5, 5) # Should return 0\n",
    "    self.assertEqual( result, 1 ) # This will fail, but expected failure\n",
    "    \n",
    "  def tearDown(self):\n",
    "    # Free up object memory\n",
    "    del self.my_letters1\n",
    "    del self.my_letters2\n",
    "    del self.my_letters3\n",
    "    \n",
    "# Use the main function from the unittest module\n",
    "unittest.main(argv=[''], verbosity=2, exit=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<span style='color:blue'>",
    "&#128073;&ensp;&ensp;**Exercise 16.3.3.1:**\n\n",
    "</span>",
    "<span style='color:navy' >",
    "In the following code cell, ",
    "create a class, `Numbers`, which includes a `divide(a, b)` method that divides a by b.",
    " Write a test case, including `setUp` and `tearDown`, to instantiate a `Numbers` object and delete it, respectively.",
    " Test the `divide` method by including a skip decorator that checks if b == 0 and provide a descriptive skipping message.",
    "</span>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.1"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}