feat(DeploymentView): add animation support

Author: yt-ms

src/structurizr/view/animation.py

@@ -46,9 +46,9 @@ class Animation(AbstractBase):
     Define a wrapper for a collection of animation steps.
 
     Attributes:
-        order:
-        elements:
-        relationships:
+        order: the order in which this animation step appears
+        elements: the IDs of the elements to show in this step
+        relationships: ths IDs of the relationships to show in this step
 
     """
 

src/structurizr/view/deployment_view.py

@@ -21,9 +21,11 @@
 from ..mixin.model_ref_mixin import ModelRefMixin
 from ..model.container_instance import ContainerInstance
 from ..model.deployment_node import DeploymentNode
+from ..model.element import Element
 from ..model.infrastructure_node import InfrastructureNode
 from ..model.relationship import Relationship
 from ..model.software_system_instance import SoftwareSystemInstance
+from ..model.static_structure_element import StaticStructureElement
 from .animation import Animation
 from .view import View
 
@@ -95,6 +97,11 @@ def add(
         else:
             pass  # TODO
 
+    def __iadd__(self, item: Union[DeploymentNode, Relationship]):
+        """Add a deployment node or relationship to this view."""
+        self.add(item)
+        return self
+
     def remove(
         self,
         item: Union[
@@ -147,15 +154,77 @@ def name(self):
             name = f"{name} - {self.environment}"
         return name
 
-    # def can_be_removed(element: Element)
+    def add_animation(
+        self, *element_instances: Union[StaticStructureElement, InfrastructureNode]
+    ):
+        """Add an animation step, with the given elements and infrastructure nodes."""
+        if len(element_instances) == 0:
+            raise ValueError(
+                "One or more software system/container instances and/or "
+                + "infrastructure nodes must be specified"
+            )
+
+        element_ids_in_previous_steps = set()
+        for step in self.animations:
+            element_ids_in_previous_steps = element_ids_in_previous_steps.union(
+                step.elements
+            )
 
-    # def add_animation(element_instances)
+        element_ids_in_this_step = set()
+        relationship_ids_in_this_step = set()
+
+        for element in element_instances:
+            if (
+                self.is_element_in_view(element)
+                and element.id not in element_ids_in_previous_steps
+            ):
+                element_ids_in_previous_steps.add(element.id)
+                element_ids_in_this_step.add(element.id)
+
+                deployment_node = self._find_deployment_node(element)
+                while deployment_node is not None:
+                    if deployment_node.id not in element_ids_in_previous_steps:
+                        element_ids_in_previous_steps.add(deployment_node.id)
+                        element_ids_in_this_step.add(deployment_node.id)
+                    deployment_node = deployment_node.parent
+
+        if element_ids_in_this_step == set():
+            raise ValueError(
+                "None of the specified container instances exist in this view."
+            )
 
-    # def add_animation_step(elements)
+        for relationship_view in self.relationship_views:
+            relationship = relationship_view.relationship
+            if (
+                relationship.source.id in element_ids_in_this_step
+                and relationship.destination.id in element_ids_in_previous_steps
+            ) or (
+                relationship.destination.id in element_ids_in_this_step
+                and relationship.source.id in element_ids_in_previous_steps
+            ):
+                relationship_ids_in_this_step.add(relationship.id)
+
+        self._animations.append(
+            Animation(
+                order=len(self._animations) + 1,
+                elements=element_ids_in_this_step,
+                relationships=relationship_ids_in_this_step,
+            )
+        )
 
-    # def _find_deployment_node(element: Element)
+    def _find_deployment_node(self, element: Element) -> DeploymentNode:
+        all_deployment_nodes = [
+            e for e in self.model.get_elements() if isinstance(e, DeploymentNode)
+        ]
+        for node in all_deployment_nodes:
+            if (
+                element in node.container_instances
+                or element in node.infrastructure_nodes
+            ):
+                return node
+        return None
 
     @property
     def animations(self) -> Iterable[Animation]:
         """Return the animations for this view."""
-        pass  # TODO
+        return list(self._animations)

src/structurizr/view/view.py

@@ -208,6 +208,10 @@ def copy_layout_information_from(self, source: "View") -> None:
                     source_relationship_view
                 )
 
+    def is_element_in_view(self, element: Element) -> bool:
+        """Return True if the given element is in this view."""
+        return any([e.element.id == element.id for e in self.element_views])
+
     def find_element_view(
         self, source_element_view: ElementView
     ) -> Optional[ElementView]:

tests/unit/view/test_deployment_view.py

@@ -188,14 +188,115 @@ def test_deployment_view_add_deployment_node_adds_parent(empty_workspace: Worksp
     deployment_view = empty_workspace.views.create_deployment_view(
         software_system=software_system, key="deployment", description="Description"
     )
-    deployment_view.add(child_deployment_node)
+    deployment_view += child_deployment_node
     element_views = deployment_view.element_views
     assert len(element_views) == 3
     assert any([x.element is parent_deployment_node for x in element_views])
     assert any([x.element is child_deployment_node for x in element_views])
     assert any([x.element is container_instance for x in element_views])
 
 
-# TODO: Animations
+def test_add_animation_step_raises_if_no_elements(empty_workspace: Workspace):
+    """Check error handling if no elements passed."""
+    deployment_view = empty_workspace.views.create_deployment_view(
+        key="deployment", description="Description"
+    )
+    with pytest.raises(ValueError):
+        deployment_view.add_animation()
+
+
+def test_add_animation_step(empty_workspace: Workspace):
+    """Check happy path."""
+    model = empty_workspace.model
+    views = empty_workspace.views
+
+    software_system = model.add_software_system("Software System")
+    web_application = software_system.add_container("Web Application")
+    database = software_system.add_container("Database")
+    web_application.uses(database, "Reads from and writes to", "JDBC/HTTPS")
+
+    developer_laptop = model.add_deployment_node("Developer Laptop")
+    apache_tomcat = developer_laptop.add_deployment_node("Apache Tomcat")
+    oracle = developer_laptop.add_deployment_node("Oracle")
+    web_application_instance = apache_tomcat.add_container(web_application)
+    database_instance = oracle.add_container(database)
+
+    deployment_view = views.create_deployment_view(
+        software_system=software_system, key="deployment", description="Description"
+    )
+    deployment_view += developer_laptop
+
+    deployment_view.add_animation(web_application_instance)
+    deployment_view.add_animation(database_instance)
+
+    step1 = deployment_view.animations[0]
+    assert step1.order == 1
+    assert len(step1.elements) == 3
+    assert developer_laptop.id in step1.elements
+    assert apache_tomcat.id in step1.elements
+    assert web_application_instance.id in step1.elements
+    assert len(step1.relationships) == 0
+
+    step2 = deployment_view.animations[1]
+    assert step2.order == 2
+    assert len(step2.elements) == 2
+    assert oracle.id in step2.elements
+    assert database_instance.id in step2.elements
+    assert len(step2.relationships) == 1
+    assert next(iter(web_application_instance.relationships)).id in step2.relationships
+
+
+def test_animation_ignores_containers_outside_this_view(empty_workspace: Workspace):
+    """Check that containers outside this view are ignored when adding animations."""
+    model = empty_workspace.model
+    views = empty_workspace.views
+
+    software_system = model.add_software_system("Software System")
+    web_application = software_system.add_container("Web Application")
+    database = software_system.add_container("Database")
+    web_application.uses(database, "Reads from and writes to", "JDBC/HTTPS")
+
+    developer_laptop = model.add_deployment_node("Developer Laptop")
+    apache_tomcat = developer_laptop.add_deployment_node("Apache Tomcat")
+    oracle = developer_laptop.add_deployment_node("Oracle")
+    web_application_instance = apache_tomcat.add_container(web_application)
+    database_instance = oracle.add_container(database)
+
+    deployment_view = views.create_deployment_view(
+        software_system=software_system, key="deployment", description="Description"
+    )
+    deployment_view += apache_tomcat
+
+    # database_instance isn't in the view this time
+    deployment_view.add_animation(web_application_instance, database_instance)
+
+    step1 = deployment_view.animations[0]
+    assert developer_laptop.id in step1.elements
+    assert database.id not in step1.elements
+
+
+def test_animation_raises_if_no_container_instances_found(empty_workspace: Workspace):
+    """Check error raised if no container instance exists in the view."""
+    model = empty_workspace.model
+    views = empty_workspace.views
+
+    software_system = model.add_software_system("Software System")
+    web_application = software_system.add_container("Web Application")
+    database = software_system.add_container("Database")
+    web_application.uses(database, "Reads from and writes to", "JDBC/HTTPS")
+
+    developer_laptop = model.add_deployment_node("Developer Laptop")
+    apache_tomcat = developer_laptop.add_deployment_node("Apache Tomcat")
+    oracle = developer_laptop.add_deployment_node("Oracle")
+    web_application_instance = apache_tomcat.add_container(web_application)
+    database_instance = oracle.add_container(database)
+
+    deployment_view = views.create_deployment_view(
+        software_system=software_system, key="deployment", description="Description"
+    )
+
+    with pytest.raises(ValueError):
+        deployment_view.add_animation(web_application_instance, database_instance)
+
 
 # TODO: Removing