rfctr: bulk test-layout updates

Back in the day I thought it better to extract a test-specific fixture
for each test. That had the benefit of making parameterized tests fold
cleanly without the parameters in the decorator. The downside was you
had to look in two places to understand the test so I dropped that
practice. Fix some of these I need to change or add to later.

Author: scanny

src/docx/oxml/text/run.py

@@ -1,5 +1,7 @@
 """Custom element classes related to text runs (CT_R)."""
 
+from __future__ import annotations
+
 from docx.oxml.ns import qn
 from docx.oxml.simpletypes import ST_BrClear, ST_BrType
 from docx.oxml.xmlchemy import BaseOxmlElement, OptionalAttribute, ZeroOrMore, ZeroOrOne
@@ -18,7 +20,7 @@ class CT_R(BaseOxmlElement):
     tab = ZeroOrMore("w:tab")
     drawing = ZeroOrMore("w:drawing")
 
-    def add_t(self, text):
+    def add_t(self, text: str) -> CT_Text:
         """Return a newly added `<w:t>` element containing `text`."""
         t = self._add_t(text=text)
         if len(text.strip()) < len(text):

src/docx/text/run.py

@@ -128,18 +128,19 @@ def style(self, style_or_name):
         self._r.style = style_id
 
     @property
-    def text(self):
-        """String formed by concatenating the text equivalent of each run content child
-        element into a Python string. Each ``<w:t>`` element adds the text characters it
-        contains. A ``<w:tab/>`` element adds a ``\\t`` character. A ``<w:cr/>`` or
-        ``<w:br>`` element each add a ``\\n`` character. Note that a ``<w:br>`` element
-        can indicate a page break or column break as well as a line break. All
-        ``<w:br>`` elements translate to a single ``\\n`` character regardless of their
-        type. All other content child elements, such as ``<w:drawing>``, are ignored.
-
-        Assigning text to this property has the reverse effect, translating each ``\\t``
-        character to a ``<w:tab/>`` element and each ``\\n`` or ``\\r`` character to a
-        ``<w:cr/>`` element. Any existing run content is replaced. Run formatting is
+    def text(self) -> str:
+        """String formed by concatenating the text equivalent of each run.
+
+        Each `<w:t>` element adds the text characters it contains. A `<w:tab/>` element
+        adds a `\\t` character. A `<w:cr/>` or `<w:br>` element each add a `\\n`
+        character. Note that a `<w:br>` element can indicate a page break or column
+        break as well as a line break. Only line-break `<w:br>` elements translate to
+        a `\\n` character. Others are ignored. All other content child elements, such as
+        `<w:drawing>`, are ignored.
+
+        Assigning text to this property has the reverse effect, translating each `\\t`
+        character to a `<w:tab/>` element and each `\\n` or `\\r` character to a
+        `<w:cr/>` element. Any existing run content is replaced. Run formatting is
         preserved.
         """
         return self._r.text

tests/oxml/text/test_run.py

@@ -1,31 +1,35 @@
 """Test suite for the docx.oxml.text.run module."""
 
+from typing import cast
+
 import pytest
 
-from ...unitutil.cxml import element, xml
+from docx.oxml.text.run import CT_R
 
+from ...unitutil.cxml import element, xml
 
-class DescribeCT_R(object):
-    def it_can_add_a_t_preserving_edge_whitespace(self, add_t_fixture):
-        r, text, expected_xml = add_t_fixture
-        r.add_t(text)
-        assert r.xml == expected_xml
 
-    # fixtures -------------------------------------------------------
+class DescribeCT_R:
+    """Unit-test suite for the CT_R (run, <w:r>) element."""
 
-    @pytest.fixture(
-        params=[
+    @pytest.mark.parametrize(
+        ("initial_cxml", "text", "expected_cxml"),
+        [
             ("w:r", "foobar", 'w:r/w:t"foobar"'),
             ("w:r", "foobar ", 'w:r/w:t{xml:space=preserve}"foobar "'),
             (
                 "w:r/(w:rPr/w:rStyle{w:val=emphasis}, w:cr)",
                 "foobar",
                 'w:r/(w:rPr/w:rStyle{w:val=emphasis}, w:cr, w:t"foobar")',
             ),
-        ]
+        ],
     )
-    def add_t_fixture(self, request):
-        initial_cxml, text, expected_cxml = request.param
-        r = element(initial_cxml)
+    def it_can_add_a_t_preserving_edge_whitespace(
+        self, initial_cxml: str, text: str, expected_cxml: str
+    ):
+        r = cast(CT_R, element(initial_cxml))
         expected_xml = xml(expected_cxml)
-        return r, text, expected_xml
+
+        r.add_t(text)
+
+        assert r.xml == expected_xml

tests/text/test_paragraph.py

@@ -34,9 +34,23 @@ def it_can_change_its_paragraph_style(self, style_set_fixture):
         )
         assert paragraph._p.xml == expected_xml
 
-    def it_knows_the_text_it_contains(self, text_get_fixture):
-        paragraph, expected_text = text_get_fixture
-        assert paragraph.text == expected_text
+    @pytest.mark.parametrize(
+        ("p_cxml", "expected_value"),
+        [
+            ("w:p", ""),
+            ("w:p/w:r", ""),
+            ("w:p/w:r/w:t", ""),
+            ('w:p/w:r/w:t"foo"', "foo"),
+            ('w:p/w:r/(w:t"foo", w:t"bar")', "foobar"),
+            ('w:p/w:r/(w:t"fo ", w:t"bar")', "fo bar"),
+            ('w:p/w:r/(w:t"foo", w:tab, w:t"bar")', "foo\tbar"),
+            ('w:p/w:r/(w:t"foo", w:br,  w:t"bar")', "foo\nbar"),
+            ('w:p/w:r/(w:t"foo", w:cr,  w:t"bar")', "foo\nbar"),
+        ],
+    )
+    def it_knows_the_text_it_contains(self, p_cxml: str, expected_value: str):
+        paragraph = Paragraph(element(p_cxml), None)
+        assert paragraph.text == expected_value
 
     def it_can_replace_the_text_it_contains(self, text_set_fixture):
         paragraph, text, expected_text = text_set_fixture
@@ -223,24 +237,6 @@ def style_set_fixture(self, request, part_prop_):
         expected_xml = xml(expected_cxml)
         return paragraph, value, expected_xml
 
-    @pytest.fixture(
-        params=[
-            ("w:p", ""),
-            ("w:p/w:r", ""),
-            ("w:p/w:r/w:t", ""),
-            ('w:p/w:r/w:t"foo"', "foo"),
-            ('w:p/w:r/(w:t"foo", w:t"bar")', "foobar"),
-            ('w:p/w:r/(w:t"fo ", w:t"bar")', "fo bar"),
-            ('w:p/w:r/(w:t"foo", w:tab, w:t"bar")', "foo\tbar"),
-            ('w:p/w:r/(w:t"foo", w:br,  w:t"bar")', "foo\nbar"),
-            ('w:p/w:r/(w:t"foo", w:cr,  w:t"bar")', "foo\nbar"),
-        ]
-    )
-    def text_get_fixture(self, request):
-        p_cxml, expected_text_value = request.param
-        paragraph = Paragraph(element(p_cxml), None)
-        return paragraph, expected_text_value
-
     @pytest.fixture
     def text_set_fixture(self):
         paragraph = Paragraph(element("w:p"), None)

tests/text/test_run.py

@@ -1,9 +1,14 @@
 """Test suite for the docx.text.run module."""
 
+from __future__ import annotations
+
+from typing import cast
+
 import pytest
 
 from docx.enum.style import WD_STYLE_TYPE
 from docx.enum.text import WD_BREAK, WD_UNDERLINE
+from docx.oxml.text.run import CT_R
 from docx.parts.document import DocumentPart
 from docx.shape import InlineShape
 from docx.text.font import Font
@@ -64,9 +69,23 @@ def it_can_add_text(self, add_text_fixture, Text_):
         assert run._r.xml == expected_xml
         assert _text is Text_.return_value
 
-    def it_can_add_a_break(self, add_break_fixture):
-        run, break_type, expected_xml = add_break_fixture
+    @pytest.mark.parametrize(
+        ("break_type", "expected_cxml"),
+        [
+            (WD_BREAK.LINE, "w:r/w:br"),
+            (WD_BREAK.PAGE, "w:r/w:br{w:type=page}"),
+            (WD_BREAK.COLUMN, "w:r/w:br{w:type=column}"),
+            (WD_BREAK.LINE_CLEAR_LEFT, "w:r/w:br{w:type=textWrapping, w:clear=left}"),
+            (WD_BREAK.LINE_CLEAR_RIGHT, "w:r/w:br{w:type=textWrapping, w:clear=right}"),
+            (WD_BREAK.LINE_CLEAR_ALL, "w:r/w:br{w:type=textWrapping, w:clear=all}"),
+        ],
+    )
+    def it_can_add_a_break(self, break_type: WD_BREAK, expected_cxml: str):
+        run = Run(element("w:r"), None)
+        expected_xml = xml(expected_cxml)
+
         run.add_break(break_type)
+
         assert run._r.xml == expected_xml
 
     def it_can_add_a_tab(self, add_tab_fixture):
@@ -91,8 +110,18 @@ def it_can_remove_its_content_but_keep_formatting(self, clear_fixture):
         assert run._r.xml == expected_xml
         assert _run is run
 
-    def it_knows_the_text_it_contains(self, text_get_fixture):
-        run, expected_text = text_get_fixture
+    @pytest.mark.parametrize(
+        ("r_cxml", "expected_text"),
+        [
+            ("w:r", ""),
+            ('w:r/w:t"foobar"', "foobar"),
+            ('w:r/(w:t"abc", w:tab, w:t"def", w:cr)', "abc\tdef\n"),
+            ('w:r/(w:br{w:type=page}, w:t"abc", w:t"def", w:tab)', "\nabcdef\t"),
+        ],
+    )
+    def it_knows_the_text_it_contains(self, r_cxml: str, expected_text: str):
+        r = cast(CT_R, element(r_cxml))
+        run = Run(r, None)  # pyright: ignore[reportGeneralTypeIssues]
         assert run.text == expected_text
 
     def it_can_replace_the_text_it_contains(self, text_set_fixture):
@@ -102,22 +131,6 @@ def it_can_replace_the_text_it_contains(self, text_set_fixture):
 
     # fixtures -------------------------------------------------------
 
-    @pytest.fixture(
-        params=[
-            (WD_BREAK.LINE, "w:r/w:br"),
-            (WD_BREAK.PAGE, "w:r/w:br{w:type=page}"),
-            (WD_BREAK.COLUMN, "w:r/w:br{w:type=column}"),
-            (WD_BREAK.LINE_CLEAR_LEFT, "w:r/w:br{w:type=textWrapping, w:clear=left}"),
-            (WD_BREAK.LINE_CLEAR_RIGHT, "w:r/w:br{w:type=textWrapping, w:clear=right}"),
-            (WD_BREAK.LINE_CLEAR_ALL, "w:r/w:br{w:type=textWrapping, w:clear=all}"),
-        ]
-    )
-    def add_break_fixture(self, request):
-        break_type, expected_cxml = request.param
-        run = Run(element("w:r"), None)
-        expected_xml = xml(expected_cxml)
-        return run, break_type, expected_xml
-
     @pytest.fixture
     def add_picture_fixture(self, part_prop_, document_part_, InlineShape_, picture_):
         run = Run(element("w:r/wp:x"), None)
@@ -247,19 +260,6 @@ def style_set_fixture(self, request, part_prop_):
         expected_xml = xml(expected_cxml)
         return run, value, expected_xml
 
-    @pytest.fixture(
-        params=[
-            ("w:r", ""),
-            ('w:r/w:t"foobar"', "foobar"),
-            ('w:r/(w:t"abc", w:tab, w:t"def", w:cr)', "abc\tdef\n"),
-            ('w:r/(w:br{w:type=page}, w:t"abc", w:t"def", w:tab)', "\nabcdef\t"),
-        ]
-    )
-    def text_get_fixture(self, request):
-        r_cxml, expected_text = request.param
-        run = Run(element(r_cxml), None)
-        return run, expected_text
-
     @pytest.fixture(
         params=[
             ("abc  def", 'w:r/w:t"abc  def"'),

tests/unitutil/cxml.py

@@ -28,13 +28,13 @@
 # ====================================================================
 
 
-def element(cxel_str):
+def element(cxel_str: str):
     """Return an oxml element parsed from the XML generated from `cxel_str`."""
     _xml = xml(cxel_str)
     return parse_xml(_xml)
 
 
-def xml(cxel_str):
+def xml(cxel_str: str) -> str:
     """Return the XML generated from `cxel_str`."""
     root_token = root_node.parseString(cxel_str)
     xml = root_token.element.xml