Improve error messages on failed circuit-equality assertions (Qiskit#…

…9882)

* Improve error messages on failed circuit-equality assertions

This improves the error message when running the test suite, if an
`assertEqual` is applied to two circuits; on a failed test, the circuits
are now drawn so they can be compared, rather than just seeing that the
two pointers are not the same.

* Apply suggestions from code review

Co-authored-by: Matthew Treinish <[email protected]>

---------

Co-authored-by: Matthew Treinish <[email protected]>

qiskit/test/base.py

@@ -30,6 +30,7 @@
 
 from qiskit.tools.parallel import get_platform_parallel_default
 from qiskit.utils import optionals as _optionals
+from qiskit.circuit import QuantumCircuit
 from .decorators import enforce_subclasses_call
 from .utils import Path, setup_test_logging
 
@@ -77,6 +78,7 @@ def __init__(self, *args, **kwargs):
 
     def setUp(self):
         super().setUp()
+        self.addTypeEqualityFunc(QuantumCircuit, self.assertQuantumCircuitEqual)
         if self.__setup_called:
             raise ValueError(
                 "In File: %s\n"
@@ -110,6 +112,20 @@ def _get_resource_path(filename, path=Path.TEST):
         """
         return os.path.normpath(os.path.join(path.value, filename))
 
+    def assertQuantumCircuitEqual(self, qc1, qc2, msg=None):
+        """Extra assertion method to give a better error message when two circuits are unequal."""
+        if qc1 == qc2:
+            return
+        if msg is None:
+            msg = "The two circuits are not equal."
+        msg += f"""
+Left circuit:
+{qc1}
+
+Right circuit:
+{qc2}"""
+        raise self.failureException(msg)
+
     def assertDictAlmostEqual(
         self, dict1, dict2, delta=None, msg=None, places=None, default_value=0
     ):