ElementNode find() functionality and unit tests.

Author: ntoll

polyplug.py

@@ -161,7 +161,7 @@ def get_value(self):
             self.expect(self.QUOTES)
             while True:
                 c = self.char
-                if not (c.isalpha() or c.isdigit() or c in "_-."):
+                if not (c.isalpha() or c.isdigit() or c in "_-. ;:!"):
                     break
                 result += self.get_char()
             self.expect(self.QUOTES)
@@ -296,10 +296,16 @@ def __init__(self, **kwargs):
 
     @property
     def outerHTML(self):
+        """
+        Get a string representation of the element's outer HTML.
+        """
         return NotImplemented
 
     @property
     def as_dict(self):
+        """
+        JSON serializable.
+        """
         return NotImplemented
 
 
@@ -356,7 +362,7 @@ def outerHTML(self):
         """
         result = "<" + self.tagName
         for attr, val in self.attributes.items():
-            result += " " + attr + "=\"" + val + "\""
+            result += " " + attr + '="' + val + '"'
         result += ">"
         if self.tagName == "textarea":
             result += self.value
@@ -386,6 +392,9 @@ def innerHTML(self, raw):
 
     @property
     def childNodes(self):
+        """
+        A data structure representing the tree of child nodes.
+        """
         if self.tagName == "textarea":
             # The textarea doesn't have children. Only a text value.
             return []
@@ -411,6 +420,9 @@ def childNodes(self):
 
     @property
     def as_dict(self):
+        """
+        JSON serializable.
+        """
         result = {
             "nodeType": 1,
             "tagName": self.tagName,
@@ -422,6 +434,98 @@ def as_dict(self):
             result["value"] = self.value
         return result
 
+    def find(self, selector):
+        """
+        Recursively check this node, and its children, and return a result
+        representing nodes that match "selector" string. The selector
+        string understands:
+
+        * .my-id - returns the first ElementNode with the id "my-id". Returns
+          None if no match is found.
+        * #my-class - returns a list containing elements with the class
+          "my-class". Returns an empty list if no match is found.
+        * li - returns a list containing elements with the tagName "li".
+          Returns an empty list if no match is found.
+        """
+        # Validate selector.
+        if not selector:
+            raise ValueError("Missing selector.")
+        result = None
+        if selector[0] == ".":
+            # Select by unique id.
+            target_id = selector[1:]
+            if target_id:
+                return self._find_by_id(target_id)
+            else:
+                raise ValueError("Invalid id.")
+        elif selector[0] == "#":
+            # Select by css class.
+            target_class = selector[1:]
+            if target_class:
+                return self._find_by_class(target_class)
+            else:
+                raise ValueError("Invalid class.")
+        else:
+            # select by tagName.
+            if selector.isalpha():
+                return self._find_by_tagName(selector.lower())
+            else:
+                raise ValueError("Invalid tag name.")
+
+    def _find_by_id(self, target):
+        """
+        Return this node, or the first of its children, if it has the id
+        attribute of target. Returns None if no match is found.
+        """
+        my_id = self.attributes.get("id")
+        if my_id and my_id == target:
+            return self
+        else:
+            for child in (
+                node
+                for node in self.childNodes
+                if isinstance(node, ElementNode)
+            ):
+                result = child._find_by_id(target)
+                if result:
+                    return result
+        return None
+
+    def _find_by_class(self, target):
+        """
+        Return a list containing this node, or any of its children, if the
+        node has the associated target class.
+        """
+        result = []
+        class_attr = self.attributes.get("class", "")
+        if class_attr:
+            classes = [
+                class_name
+                for class_name in class_attr.split(" ")
+                if class_name
+            ]
+            if target in classes:
+                result.append(self)
+        for child in (
+            node for node in self.childNodes if isinstance(node, ElementNode)
+        ):
+            result.extend(child._find_by_class(target))
+        return result
+
+    def _find_by_tagName(self, target):
+        """
+        Return a list containing this node, or any of its children, if the
+        node has the associated target as its tagName (e.g. "div" or "p").
+        """
+        result = []
+        if self.tagName == target:
+            result.append(self)
+        for child in (
+            node for node in self.childNodes if isinstance(node, ElementNode)
+        ):
+            result.extend(child._find_by_tagName(target))
+        return result
+        
 
 class TextNode(Node):
     """
@@ -441,6 +545,9 @@ def outerHTML(self):
 
     @property
     def as_dict(self):
+        """
+        JSON serializable.
+        """
         return {
             "nodeType": 3,
             "nodeName": "#text",
@@ -467,6 +574,9 @@ def outerHTML(self):
 
     @property
     def as_dict(self):
+        """
+        JSON serializable.
+        """
         return {
             "nodeType": 8,
             "nodeName": "#comment",
@@ -492,14 +602,30 @@ def outerHTML(self):
 
     @property
     def as_dict(self):
+        """
+        JSON serializable.
+        """
         return {"nodeType": 11, "childNodes": []}
 
 
 def plug(query, event_type):
     """
-    A decorator to plug a Python function into a DOM event specified by a
-    query to match elements in the DOM tree, and an event_type (e.g. "click").
+    A decorator wrapper to plug a Python function into a DOM event specified
+    by a query to match elements in the DOM tree, and an event_type (e.g.
+    "click").
 
-    The decorator must ... TODO: FINISH THIS
+    Returns a decorator function that wraps the user's own function that is
+    to be registered.
+
+    This decorator wrapper function creates a closure in which various
+    contextual aspects are contained.
     """
-    pass
+
+    def decorator(fn):
+        @wraps(fn)
+        def wrapper(*args, **kwargs):
+            fn(*args, **kwargs)
+
+        return wrapper
+
+    return decorator

tests/test_polyplug.py

@@ -5,6 +5,7 @@
 import json
 import pytest
 import polyplug
+from unittest import mock
 
 
 DOM_FROM_JSON = {
@@ -330,7 +331,7 @@ def test_element_node_get_outer_html():
     """
     n = polyplug.ElementNode(tagName="div", attributes={"foo": "bar"})
     n.add_child(polyplug.TextNode(nodeValue="Hello"))
-    assert n.outerHTML == "<div foo=\"bar\">Hello</div>"
+    assert n.outerHTML == '<div foo="bar">Hello</div>'
 
 
 def test_element_node_get_inner_html_empty():
@@ -349,6 +350,7 @@ def test_element_node_get_set_inner_html_complex():
     n.innerHTML = "<!-- comment --><p>Hello</p>"
     assert n.innerHTML == "<!-- comment --><p>Hello</p>"
 
+
 def test_element_node_set_inner_html_empty():
     """
     Set the innerHTML of the node as empty.
@@ -367,6 +369,133 @@ def test_element_node_set_inner_html_textarea():
     n.innerHTML = "<textarea>Test <fake html></textarea>"
     assert n.innerHTML == "<textarea>Test <fake html></textarea>"
 
+
+def test_element_node_find():
+    """
+    The find method validates the selector.
+    """
+    # Can't be empty.
+    selector = ""
+    n = polyplug.ElementNode(tagName="div")
+    with pytest.raises(ValueError):
+        n.find(selector)
+    # Must be a valid id.
+    selector = ".my-id"  # valid
+    n._find_by_id = mock.MagicMock()
+    n.find(selector)
+    n._find_by_id.assert_called_once_with("my-id")
+    selector = "."  # in-valid
+    with pytest.raises(ValueError):
+        n.find(selector)
+    # Must be a valid class.
+    selector = "#my-class"  # valid
+    n._find_by_class = mock.MagicMock()
+    n.find(selector)
+    n._find_by_class.assert_called_once_with("my-class")
+    selector = "#"  # in-valid
+    with pytest.raises(ValueError):
+        n.find(selector)
+    # Must be a valid tagName.
+    selector = "tagName"  # valid
+    n._find_by_tagName = mock.MagicMock()
+    n.find(selector)
+    n._find_by_tagName.assert_called_once_with("tagname")  # lowercase!
+    selector = "not a tag name because spaces etc"  # in-valid
+    with pytest.raises(ValueError):
+        n.find(selector)
+
+
+def test_element_node_find_by_id():
+    """
+    The expected individual nodes are returned for various combinations of
+    searching the tree by unique id.
+    """
+    # Will return itself as the first match.
+    n = polyplug.ElementNode(tagName="div", attributes={"id": "foo"})
+    assert n == n.find(".foo")
+    # Will return the expected child.
+    n = polyplug.ElementNode(tagName="div")
+    n.innerHTML = "<ul><li>Nope</li><li id='foo'>Yup</li></ul>"
+    result = n.find(".foo")
+    assert isinstance(result, polyplug.ElementNode)
+    assert result.innerHTML == "Yup"
+    # Returns None if no match.
+    assert n.find(".bar") is None
+
+
+def test_element_node_find_by_class():
+    """
+    The expected collection of matching nodes are returned for various
+    combinations of searching the tree by CSS class.
+    """
+    # Returns itself if matched.
+    n = polyplug.ElementNode(tagName="div", attributes={"class": "foo"})
+    assert [
+        n,
+    ] == n.find("#foo")
+    # Returns expected children (along with itself).
+    n = polyplug.ElementNode(tagName="div", attributes={"class": "foo"})
+    n.innerHTML = "<ul><li class='foo'>Yup</li><li class='foo'>Yup</li></ul>"
+    result = n.find("#foo")
+    assert len(result) == 3
+    assert result[0] == n
+    assert result[1].tagName == "li"
+    assert result[2].tagName == "li"
+    # Returns just expected children (not itself).
+    n = polyplug.ElementNode(tagName="div", attributes={"class": "bar"})
+    n.innerHTML = "<ul><li class='foo'>Yup</li><li class='foo'>Yup</li></ul>"
+    result = n.find("#foo")
+    assert len(result) == 2
+    assert result[0].tagName == "li"
+    assert result[1].tagName == "li"
+    # Returns just expected children with multiple classes.
+    n = polyplug.ElementNode(tagName="div", attributes={"class": "bar foo"})
+    n.innerHTML = (
+        "<ul><li class='foo bar'>Yup</li><li class='foobar'>Nope</li></ul>"
+    )
+    result = n.find("#foo")
+    assert len(result) == 2
+    assert result[0] == n
+    assert result[1].tagName == "li"
+    # No match returns an empty list.
+    n = polyplug.ElementNode(tagName="div", attributes={"class": "bar"})
+    n.innerHTML = "<ul><li class='foo'>Nope</li><li class='foo'>Nope</li></ul>"
+    result = n.find("#baz")
+    assert result == []
+
+
+def test_element_node_find_by_tagName():
+    """
+    The expected collection of matching nodes are returned for various
+    combinations of searching the tree by tagName.
+    """
+    # Returns itself if matched.
+    n = polyplug.ElementNode(tagName="div")
+    assert [
+        n,
+    ] == n.find("div")
+    # Returns expected children (along with itself).
+    n = polyplug.ElementNode(tagName="li")
+    n.innerHTML = "<ul><li>Yup</li><li>Yup</li></ul>"
+    result = n.find("li")
+    assert len(result) == 3
+    assert result[0] == n
+    assert result[1].innerHTML == "Yup"
+    assert result[2].innerHTML == "Yup"
+    # Returns just expected children (not itself).
+    n = polyplug.ElementNode(tagName="div")
+    n.innerHTML = "<ul><li>Yup</li><li>Yup</li></ul>"
+    result = n.find("li")
+    assert len(result) == 2
+    assert result[0].innerHTML == "Yup"
+    assert result[1].innerHTML == "Yup"
+    # No match returns an empty list.
+    n = polyplug.ElementNode(tagName="div")
+    n.innerHTML = "<ul><li>Nope</li><li>Nope</li></ul>"
+    result = n.find("p")
+    assert result == []
+
+
 def test_text_node():
     """
     The TextNode instantiates as expected.
@@ -526,9 +655,9 @@ def test_htmltokenizer_get_value():
     """
     Given a potential value for an attribute, grab and return it.
     """
-    raw = "='foo'>"
+    raw = "='font: arial; font-weight: bold!important;'>"
     tok = polyplug.HTMLTokenizer(raw)
-    assert tok.get_value() == "foo"
+    assert tok.get_value() == "font: arial; font-weight: bold!important;"
     assert tok.expect(">") is None