Improve documentation of arnied wrapper and tests

[pyi2ncommon] / test / test_arnied_wrapper.py

diff --git a/test/test_arnied_wrapper.py b/test/test_arnied_wrapper.py
index 57ab125..e061150 100755 (executable)
--- a/test/test_arnied_wrapper.py
+++ b/test/test_arnied_wrapper.py
@@ -28,8 +28,19 @@ from src import arnied_wrapper
 
 
 class DummyCmdOutputMapping(object):
+    """
+    Class to replace the :py:function:`arnied_wrapper.run_cmd` function.
 
+    In the arnied_wrapper, when running a command, instead of calling the actual
+    function, this class' constructor will be invoked and an instance returned
+    instead. It stubs :py:class:`subprocess.CompletedProcess`, such that the
+    returncode and stdout attributes are set depending on the command or on the
+    test.
+    """
+
+    # whether to return 1 as a fail indicator
     fail_switch = False
+    # mapping between expected commands and their mocked output + return code
     cmds = [
         {"cmd": "pgrep -l -x arnied", "stdout": b"", "returncode": 0},
 
@@ -57,6 +68,11 @@ class DummyCmdOutputMapping(object):
     asserted_cmds = []
 
     def __init__(self, cmd="", ignore_errors=False, vm=None, timeout=60):
+        """
+        Class constructor to mimic the run function of the arnied wrapper.
+
+        Arguments are the same of the mocked function.
+        """
         self.returncode = 0
         self.stdout = b""
         self._get_result(cmd)
@@ -64,9 +80,19 @@ class DummyCmdOutputMapping(object):
             self.returncode = 1
 
     def __str__(self):
+        """String representation of this class."""
         return "status %i, stdout %s" % (self.returncode, self.stdout)
 
     def _get_result(self, cmd):
+        """
+        Return the first (or raise) values in the mapping matching the command.
+
+        :param str cmd: command to check the mapping against
+        :raises: :py:class:`ValueError` if the command has no corresponding
+                 mapping
+        :returns: this instance with the return code and stdout attributes set
+        :rtype: :py:class:`DummyCmdOutputMapping`
+        """
         for dummy_cmd in self.asserted_cmds:
             if dummy_cmd['cmd'] == cmd:
                 self.returncode = dummy_cmd['returncode']
@@ -76,15 +102,16 @@ class DummyCmdOutputMapping(object):
                          "for the universe" % cmd)
 
 
-@mock.patch('src.arnied_wrapper.run_cmd', DummyCmdOutputMapping)
+# make sure that invoking `run_cmd` returns an instance of DummyCmdOutputMapping
+@mock.patch("src.arnied_wrapper.run_cmd", DummyCmdOutputMapping)
 class ArniedWrapperTest(unittest.TestCase):
-
     def setUp(self):
         DummyCmdOutputMapping.fail_switch = False
         DummyCmdOutputMapping.asserted_cmds = []
         self.cmd_db = DummyCmdOutputMapping.cmds
 
     def test_verify_running(self):
+        """Test checking for running programs."""
         DummyCmdOutputMapping.asserted_cmds = self.cmd_db[0:1]
         arnied_wrapper.verify_running(timeout=1)
         DummyCmdOutputMapping.fail_switch = True
@@ -92,10 +119,12 @@ class ArniedWrapperTest(unittest.TestCase):
             arnied_wrapper.verify_running(timeout=1)
 
     def test_wait_for_arnied(self):
+        """Test waiting for arnied to be ready."""
         DummyCmdOutputMapping.asserted_cmds = self.cmd_db
         arnied_wrapper.wait_for_arnied(timeout=10)
 
     def test_accept_license(self):
+        """Test accepting license."""
         DummyCmdOutputMapping.asserted_cmds = self.cmd_db[1:3]
         arnied_wrapper.accept_licence()
         # make sure an error is ignored since license might
@@ -108,9 +137,11 @@ class ArniedWrapperTest(unittest.TestCase):
         arnied_wrapper.go_online(1)
 
     def test_disable_virscan(self):
+        """Test disabling the virus scanner."""
         DummyCmdOutputMapping.asserted_cmds = self.cmd_db[6:]
         arnied_wrapper.disable_virscan()
 
     def test_email_transfer(self):
+        """Test e-mail transferring."""
         DummyCmdOutputMapping.asserted_cmds = self.cmd_db[14:15]
         arnied_wrapper.email_transfer()