Add test examples to the wrapper development template (#12)

* Improve exception handling and boundaries of SimulationEngine.

* Add wrapper API test examples.

* Add usage tests examples.

* Add unit tests examples.

* Add integration tests example.

* Describe which tests are mandatory and which are optional in the test module's docstring.

Author: domgz

package_name/engine.py

@@ -1,6 +1,7 @@
 """This file emulates communication with a simulation engine."""
 
 from dataclasses import dataclass
+from functools import wraps
 from typing import List, Optional
 
 from numpy import ndarray
@@ -14,67 +15,136 @@ class Atom:
     velocity: ndarray
 
 
+class AtomNotFoundException(KeyError):
+    """Exception to be raised when a non-existent atom is requested.
+
+    Exception raised by `SimulationEngine` when an index that is not associated
+    with an atom in the engine is looked up.
+    """
+
+    def __init__(self, *args):
+        """Initialize the exception with a default message."""
+        default_msg = "No atom with given index registered in the engine"
+        if not args:
+            args = (default_msg,)
+        super().__init__(*args)
+
+
+def raise_atom_not_found_exception(func):
+    """A decorator to automatically raise AtomNotFoundException.
+
+    Raises AtomNotFoundException when the first positional argument of the
+    decorated method of `SimulationEngine` does not correspond to an atom that
+    is registered in the engine.
+    """
+
+    @wraps(func)
+    def decorated(self, index: int, *args, **kwargs):
+        exception = AtomNotFoundException()
+        if index < 0:
+            raise exception
+        try:
+            atom = self._atoms[index]
+        except IndexError as e:
+            raise exception from e
+        if atom is None:
+            raise exception
+        return func(self, index, *args, **kwargs)
+
+    return decorated
+
+
 class SimulationEngine:
-    """Simple engine sample code."""
+    """Simple engine sample code.
+
+    This simulation engine associates atoms with an integer index. Indexing
+    starts at zero, and each time an atom is added, `last_index + 1` is
+    associated with it. Indexes of deleted atoms are never reused for new
+    atoms.
+    """
 
-    atoms: List[Optional[Atom]]
+    _atoms: List[Optional[Atom]]
 
     def __init__(self):
-        """Initialize the simulation engine."""
-        self.atoms = list()
+        """Initializes the simulation engine."""
+        self._atoms = list()
         print("Engine instantiated!")
 
     def __str__(self) -> str:
         """String representation of the simulation engine."""
         return "Some Engine Connection"
 
     def run(self, time_steps: int = 1) -> None:
-        """Call the run command of the engine."""
+        """Calls the run command of the engine."""
         print("Now the engine is running")
-        for atom in self.atoms:
+        for atom in self._atoms:
             atom.position = atom.position + atom.velocity * time_steps
 
     def add_atom(self, position: ndarray, velocity: ndarray) -> None:
-        """Add an atom to the engine.
+        """Adds an atom to the engine.
 
         Args:
             position: A 3D array for the position of the atom.
             velocity: A 3D array for the velocity of the atom.
         """
         print(
             "Add atom %s with position %s and velocity %s"
-            % (len(self.atoms), position, velocity)
+            % (len(self._atoms), position, velocity)
         )
-        self.atoms.append(Atom(position, velocity))
+        self._atoms.append(Atom(position, velocity))
 
+    @raise_atom_not_found_exception
     def delete_atom(self, index: int) -> None:
-        """Remove an atom from the engine.
+        """Removes an atom from the engine.
 
         Args:
             index: The index of the atom to remove.
+
+        Raises:
+            AtomNotFoundException: No atom with given index registered in the
+                engine.
         """
-        self.atoms[index] = None
+        exception = AtomNotFoundException()
+        try:
+            atom = self._atoms[index]
+        except KeyError as e:
+            raise exception from e
+        if atom is None:
+            raise exception
+
+        self._atoms[index] = None
 
+    @raise_atom_not_found_exception
     def update_position(self, index: int, position: ndarray) -> None:
         """Update the position of the atom.
 
         Args:
             index: The index of the atom to update
             position: The new position.
+
+        Raises:
+            AtomNotFoundException: No atom with given index registered in the
+                engine.
         """
         print("Update atom %s. Setting position to %s" % (index, position))
-        self.atoms[index].position = position
+        self._atoms[index].position = position
 
+    @raise_atom_not_found_exception
     def update_velocity(self, index: int, velocity: ndarray) -> None:
         """Update the velocity of an atom.
 
         Args:
             index: The index of the atom
             velocity: The new velocity.
+
+        Raises:
+            AtomNotFoundException: No atom with given index registered in the
+                engine.
         """
         print("Update atom %s. Setting velocity to %s" % (index, velocity))
-        self.atoms[index].velocity = velocity
+        self._atoms[index].velocity = velocity
 
+    @raise_atom_not_found_exception
     def get_velocity(self, index: int) -> ndarray:
         """Get the velocity of an atom.
 
@@ -83,16 +153,25 @@ def get_velocity(self, index: int) -> ndarray:
 
         Returns:
             The velocity of the atom.
+
+        Raises:
+            AtomNotFoundException: No atom with given index registered in the
+                engine.
         """
-        return self.atoms[index].velocity
+        return self._atoms[index].velocity
 
-    def get_position(self, index) -> ndarray:
+    @raise_atom_not_found_exception
+    def get_position(self, index: int) -> ndarray:
         """Get the position of the atom.
 
         Args:
             index: The index of the atom.
 
         Returns:
             The position of the atom.
+
+        Raises:
+            AtomNotFoundException: No atom with given index registered in the
+                engine.
         """
-        return self.atoms[index].position
+        return self._atoms[index].position

tests/__init__.py

@@ -1 +1,15 @@
-"""Use this module to write tests for your wrapper."""
+"""Use this module to write tests for your wrapper.
+
+Modify the files in this module to adapt them to your own wrapper. You can
+organize your test files and their contents in any way you wish and use any
+testing framework.
+
+Writing tests that cover the typical use case of your wrapper (see
+`test_usage.py`) and tests that cover calls to all the wrapper API functions
+you use in your wrapper (see `test_wrapper_api.py`) is very strongly
+recommended, and may even be required if the wrapper is to be officially
+endorsed by us.
+
+Optionally, you can also write unit tests (see `test_unit.py`) and integration
+tests (see `test_integration.py`).
+"""

tests/test_integration.py

@@ -0,0 +1,175 @@
+"""Tests the integration of the different modules used in your wrapper.
+
+This file is meant to contain tests that verify that the different components
+of your software are also functional when they have to work together.
+
+Modify this file to adapt it to your own wrapper. You can organize your tests
+in any way you wish (e.g. distribute them among different files) and use any
+testing framework, and you can omit this kind of testing in your package,
+although it is recommended not to do so.
+"""
+
+import unittest
+from functools import wraps
+from inspect import getfullargspec
+from typing import get_type_hints
+
+from package_name.wrapper import SimulationWrapper
+
+
+class TestIntegrationWrapperEngine(unittest.TestCase):
+    """Tests the integration of the wrapper and the engine classes.
+
+    As the engine is simple, only a test that checks that the correct types are
+    passed by the wrapper to the engine functions is provided. As the
+    consistency check of the wrapper already checks that the dimension or data
+    types of the arrays passed by the wrapper are correct, this coverage should
+    be sufficient.
+
+    Nevertheless, always be on guard:
+        "A software tester walks into a bar. Asks to be seated outside, behind
+        the counter and in the basement. Orders 1 beer, 374738493 beers, -3
+        beers, 'asdfgh' beers, a mojito, 5.8 mojitos and a Rubik's Cube. Jumps
+        on and dances on all the tables. Testing is complete.
+
+        The bar opens to the public and after a few hour a customer comes in
+        and asks where the bathroom is. The bar explodes and bursts into
+        flames."
+    """
+
+    def test_types_engine(self):
+        """Test that correct types are passed to the engine functions.
+
+        Tests that the correct types are passed to the engine functions. The
+        engine functions are only called when the `commit` and `compute`
+        functions from the wrapper API are called. And actually `compute` calls
+        commit. Therefore, this test just needs to run a simulation to verify
+        all calls made to the engine.
+
+        Actually this is something that you would do, at least for the static
+        case, with a type checker such as mypy. However, it is a pretty good
+        example of an integration test, that is why it is included.
+        """
+        from simphony_osp.namespaces import ontology_namespace as namespace
+        from simphony_osp.wrappers import SimulationWrapper
+
+        # decorate the methods on the engine so that they verify the declared
+        # type hints
+        session = SimulationWrapper()
+        wrapper = session.driver.interface
+        # read the diagram on the SimPhoNy documentation to understand how the
+        # wrapper object was retrieved from the session object:
+        # https://simphony.readthedocs.io/en/v4.0.0rc4/developers/
+        # wrappers.html#wrapper-abstract-class
+        session.driver.interface = self._prepare_wrapper_for_types_test(
+            wrapper
+        )
+
+        # run a simulation, that should raise no validation errors
+
+        with session:
+            atm = namespace.Atom()
+            pos = namespace.Position(value=[8, 5, 3], unit="m")
+            vel = namespace.Velocity(value=[1, 2, 3], unit="m/s")
+            atm[namespace.hasPart] = pos, vel
+            session.compute(time_steps=5)
+
+    @staticmethod
+    def _prepare_wrapper_for_types_test(
+        wrapper: SimulationWrapper,
+    ) -> SimulationWrapper:
+        """Decorate relevant engine functions with a type-checking decorator.
+
+        The type-checking decorator verifies that the types that are passed
+        to the engine functions match the type hints defined in their
+        signature.
+
+        Actually this is something that you would do, at least for the static
+        case, with a type checker such as mypy. However, it is a pretty good
+        example of an integration test, that is why it is included.
+        """
+        # prepare a decorator to validate type hints
+        class ValidationError(Exception):
+            """Specific exception to be used only in this test."""
+
+            pass
+
+        def verify_hints(method):
+            """Makes the decorated function validate type hints.
+
+            The method to decorate must be a bound method.
+            """
+
+            @wraps(method)
+            def decorated(*args, **kwargs):
+                hints_kwargs = {argument: None for argument in kwargs}
+                hints_args = {
+                    argument: None
+                    for argument in getfullargspec(method).args[
+                        1:
+                    ]  # exclude "self"
+                    if argument not in hints_kwargs
+                }
+                hints_return = None
+                for argument, type_ in get_type_hints(method).items():
+                    if argument == "return":
+                        hints_return = type_
+                    elif argument in hints_kwargs:
+                        hints_kwargs[argument] = type_
+                    else:
+                        hints_args[argument] = type_
+
+                exception_text = (
+                    "Expected {argument} to be of {type_}, not {actual}"
+                )
+                for i, (argument, type_) in enumerate(hints_args.items()):
+                    if type_ is not None and not isinstance(args[i], type_):
+                        raise ValidationError(
+                            exception_text.format(
+                                argument=argument,
+                                type_=type_,
+                                actual=type(args[i]),
+                            )
+                        )
+                for argument, type_ in hints_kwargs.items():
+                    if not isinstance(kwargs[argument], type_):
+                        raise ValidationError(
+                            exception_text.format(
+                                argument=argument,
+                                type_=type_,
+                                actual=type(kwargs[argument]),
+                            )
+                        )
+                return_ = method(*args, **kwargs)
+                if hints_return is not None and not isinstance(
+                    return_, hints_return
+                ):
+                    raise ValidationError(
+                        exception_text.format(
+                            argument="return",
+                            type_=hints_return,
+                            actual=type(return_),
+                        )
+                    )
+                return return_
+
+            return decorated
+
+        # decorate the functions of the engine
+        engine = wrapper._engine
+        for engine_method in (
+            "run",
+            "add_atom",
+            "delete_atom",
+            "update_position",
+            "update_velocity",
+            "get_velocity",
+            "get_position",
+        ):
+            setattr(
+                engine,
+                engine_method,
+                verify_hints(getattr(engine, engine_method)),
+            )
+
+        return wrapper