Raise exception for failed scan with details

Make sure a test fails if a scan fails that was not expected to fail.
Additionally, provide details about the failed scan in the message
provided by pytest.

Closes # 113

camayoc/exceptions.py

@@ -40,3 +40,11 @@ class WaitTimeError(Exception):
     allowed. Instead of allowing the task to hang, it has aborted and raised
     this error.
     """
+
+
+class FailedScanException(Exception):
+    """A test has raised this exception because a scan failed.
+
+    While waiting for the scan to acheive some other state, the scan failed.
+    The test expected the scan to succeed, so this exception has been raised.
+    """

camayoc/qcs_models.py

@@ -395,6 +395,15 @@ def restart(self, **kwargs):
         path = urljoin(self.path(), 'restart/')
         return self.client.put(path, {}, **kwargs)
 
+    def results(self, **kwargs):
+        """Send a GET self.endpoint/{id}/results/ to read scan details.
+
+        :param ``**kwargs``: Additional arguments accepted by Requests's
+            `request.request()` method.
+        """
+        path = urljoin(self.path(), 'results/')
+        return self.client.get(path, **kwargs)
+
     def status(self):
         """Check on the status of the scan.
 

camayoc/tests/qcs/api/v1/scans/test_network_scans.py

@@ -57,10 +57,10 @@ def first_network_source():
     except (ConfigFileNotFoundError, KeyError):
         src = [
             {
-             'hosts': ['localhost'],
-             'name':'localhost',
-             'credentials':'root'
-             }
+                'hosts': ['localhost'],
+                'name':'localhost',
+                'credentials':'root'
+            }
         ]
     return src
 

camayoc/tests/qcs/api/v1/scans/utils.py

@@ -8,7 +8,7 @@
     Source,
     Scan
 )
-from camayoc.exceptions import WaitTimeError
+from camayoc.exceptions import WaitTimeError, FailedScanException
 
 
 def wait_until_state(scan, timeout=120, state='completed'):
@@ -23,17 +23,36 @@ def wait_until_state(scan, timeout=120, state='completed'):
     anticipated that a scan may take longer to complete.
     """
     while (
-        not scan.status() or not scan.status() in [
-            'failed',
-            state]) and timeout > 0:
+            not scan.status() or not scan.status() == state) and timeout > 0:
         time.sleep(5)
         timeout -= 5
         if timeout <= 0:
             raise WaitTimeError(
-                'You have called wait_until_state() on a scan and the scan\n'
-                'timed out while waiting to achieve the state="{}" When the\n'
-                'scan timed out, it had the state="{}".\n'
-                .format(state, scan.status())
+                'You have called wait_until_state() on a scan with ID={} and\n'
+                'the scan timed out while waiting to achieve the state="{}"\n'
+                'When the scan timed out, it had the state="{}".\n'
+                'The full details of the scan were \n{}\n'
+                'The "results" available from the scan were \n{}\n'
+                .format(
+                    scan._id,
+                    state,
+                    scan.status(),
+                    scan.read().json(),
+                    scan.results().json(),
+                )
+            )
+        if state != 'failed' and scan.status() == 'failed':
+            raise FailedScanException(
+                'You have called wait_until_state() on a scan with ID={} and\n'
+                'the scan failed instead of acheiving state={}.\n'
+                'When it failed, the details about the scan were \n{}\n'
+                'The "results" available from the scan were \n{}\n'
+                .format(
+                    scan._id,
+                    state,
+                    scan.read().json(),
+                    scan.results().json(),
+                )
             )