txt: refactor Paragraph.insert_paragraph_before()

Steve Canny · Steve Canny · commit 8297f2cb1b75 · 2015-02-08T00:01:14.000-08:00
Extract _insert_paragraph_before() helper method. The helper method can
be tested integrated with oxml. The remaining part of the method is
tested with mocks.

Aside from being good hygiene, this removes the integration dependency
on paragraph.style, allowing that property to be reimplemented without
causing a fail in the _insert_paragraph_before unit tests.
diff --git a/docx/text/paragraph.py b/docx/text/paragraph.py
@@ -65,8 +65,7 @@ def insert_paragraph_before(self, text=None, style=None):
         text in a single run. If *style* is provided, that style is assigned
         to the new paragraph.
         """
-        p = self._p.add_p_before()
-        paragraph = Paragraph(p, self._parent)
+        paragraph = self._insert_paragraph_before()
         if text:
             paragraph.add_run(text)
         if style is not None:
@@ -116,3 +115,11 @@ def text(self):
     def text(self, text):
         self.clear()
         self.add_run(text)
+
+    def _insert_paragraph_before(self):
+        """
+        Return a newly created paragraph, inserted directly before this
+        paragraph.
+        """
+        p = self._p.add_p_before()
+        return Paragraph(p, self._parent)
diff --git a/tests/text/test_paragraph.py b/tests/text/test_paragraph.py
@@ -9,7 +9,6 @@
 )
 
 from docx.enum.text import WD_ALIGN_PARAGRAPH
-from docx.oxml.ns import qn
 from docx.oxml.text.paragraph import CT_P
 from docx.oxml.text.run import CT_R
 from docx.text.paragraph import Paragraph
@@ -18,7 +17,7 @@
 import pytest
 
 from ..unitutil.cxml import element, xml
-from ..unitutil.mock import call, class_mock, instance_mock
+from ..unitutil.mock import call, class_mock, instance_mock, method_mock
 
 
 class DescribeParagraph(object):
@@ -66,12 +65,15 @@ def it_can_replace_the_text_it_contains(self, text_set_fixture):
         assert paragraph.text == expected_text
 
     def it_can_insert_a_paragraph_before_itself(self, insert_before_fixture):
-        paragraph, text, style, body, expected_xml = insert_before_fixture
+        paragraph, text, style, paragraph_, add_run_calls = (
+            insert_before_fixture
+        )
         new_paragraph = paragraph.insert_paragraph_before(text, style)
-        assert isinstance(new_paragraph, Paragraph)
-        assert new_paragraph.text == text
+
+        paragraph._insert_paragraph_before.assert_called_once_with()
+        assert new_paragraph.add_run.call_args_list == add_run_calls
         assert new_paragraph.style == style
-        assert body.xml == expected_xml
+        assert new_paragraph is paragraph_
 
     def it_can_remove_its_content_while_preserving_formatting(
             self, clear_fixture):
@@ -80,6 +82,12 @@ def it_can_remove_its_content_while_preserving_formatting(
         assert paragraph._p.xml == expected_xml
         assert _paragraph is paragraph
 
+    def it_inserts_a_paragraph_before_to_help(self, _insert_before_fixture):
+        paragraph, body, expected_xml = _insert_before_fixture
+        new_paragraph = paragraph._insert_paragraph_before()
+        assert isinstance(new_paragraph, Paragraph)
+        assert body.xml == expected_xml
+
     # fixtures -------------------------------------------------------
 
     @pytest.fixture(params=[
@@ -135,15 +143,31 @@ def clear_fixture(self, request):
         return paragraph, expected_xml
 
     @pytest.fixture(params=[
-        ('w:body/w:p', 'foobar', 'Heading1',
-         'w:body/(w:p/(w:pPr/w:pStyle{w:val=Heading1},w:r/w:t"foobar"),w:p)')
+        (None,  None),
+        ('Foo', None),
+        (None,  'Bar'),
+        ('Foo', 'Bar'),
     ])
-    def insert_before_fixture(self, request):
-        body_cxml, text, style, expected_cxml = request.param
+    def insert_before_fixture(self, request, _insert_paragraph_before_,
+                              add_run_):
+        paragraph = Paragraph(None, None)
+        paragraph_ = _insert_paragraph_before_.return_value
+        text, style = request.param
+        add_run_calls = [] if text is None else [call(text)]
+        paragraph_.style = None
+        return (
+            paragraph, text, style, paragraph_, add_run_calls
+        )
+
+    @pytest.fixture(params=[
+        ('w:body/w:p{id=42}', 'w:body/(w:p,w:p{id=42})')
+    ])
+    def _insert_before_fixture(self, request):
+        body_cxml, expected_cxml = request.param
         body = element(body_cxml)
-        paragraph = Paragraph(body.find(qn('w:p')), None)
+        paragraph = Paragraph(body[0], None)
         expected_xml = xml(expected_cxml)
-        return paragraph, text, style, body, expected_xml
+        return paragraph, body, expected_xml
 
     @pytest.fixture
     def runs_fixture(self, p_, Run_, r_, r_2_, runs_):
@@ -205,6 +229,14 @@ def text_set_fixture(self):
 
     # fixture components ---------------------------------------------
 
+    @pytest.fixture
+    def add_run_(self, request):
+        return method_mock(request, Paragraph, 'add_run')
+
+    @pytest.fixture
+    def _insert_paragraph_before_(self, request):
+        return method_mock(request, Paragraph, '_insert_paragraph_before')
+
     @pytest.fixture
     def p_(self, request, r_, r_2_):
         return instance_mock(request, CT_P, r_lst=(r_, r_2_))
