xfail: acceptance test for Document.add_comment()

Author: scanny

features/doc-add-comment.feature

@@ -0,0 +1,14 @@
+Feature: Add a comment to a document
+  In order add a comment to a document
+  As a developer using python-docx
+  I need a way to add a comment specifying both its content and its reference
+
+
+  @wip
+  Scenario: Document.add_comment(runs, text, author, initials)
+    Given a document having a comments part
+     When I assign comment = document.add_comment(runs, "A comment", "John Doe", "JD")
+     Then comment is a Comment object
+      And comment.text == "A comment"
+      And comment.author == "John Doe"
+      And comment.initials == "JD"

features/steps/comments.py

@@ -63,6 +63,17 @@ def when_I_assign_comment_eq_comments_add_comment_with_author_and_initials(conte
     context.comment = context.comments.add_comment(author="John Doe", initials="JD")
 
 
+@when('I assign comment = document.add_comment(runs, "A comment", "John Doe", "JD")')
+def when_I_assign_comment_eq_document_add_comment(context: Context):
+    runs = list(context.document.paragraphs[0].runs)
+    context.comment = context.document.add_comment(
+        runs=runs,
+        text="A comment",
+        author="John Doe",
+        initials="JD",
+    )
+
+
 @when('I assign "{initials}" to comment.initials')
 def when_I_assign_initials(context: Context, initials: str):
     context.comment.initials = initials
@@ -98,10 +109,9 @@ def when_I_call_comments_get_2(context: Context):
 # then =====================================================
 
 
-@then("comment.author is the author of the comment")
-def then_comment_author_is_the_author_of_the_comment(context: Context):
-    actual = context.comment.author
-    assert actual == "Steve Canny", f"expected author 'Steve Canny', got '{actual}'"
+@then("comment is a Comment object")
+def then_comment_is_a_Comment_object(context: Context):
+    assert type(context.comment) is Comment
 
 
 @then('comment.author == "{author}"')
@@ -110,6 +120,12 @@ def then_comment_author_eq_author(context: Context, author: str):
     assert actual == author, f"expected author '{author}', got '{actual}'"
 
 
+@then("comment.author is the author of the comment")
+def then_comment_author_is_the_author_of_the_comment(context: Context):
+    actual = context.comment.author
+    assert actual == "Steve Canny", f"expected author 'Steve Canny', got '{actual}'"
+
+
 @then("comment.comment_id == 0")
 def then_comment_id_is_0(context: Context):
     assert context.comment.comment_id == 0
@@ -146,6 +162,13 @@ def then_comment_paragraphs_idx_style_name_eq_style(context: Context, idx: str,
     assert actual == expected, f"expected style name '{expected}', got '{actual}'"
 
 
+@then('comment.text == "{text}"')
+def then_comment_text_eq_text(context: Context, text: str):
+    actual = context.comment.text
+    expected = text
+    assert actual == expected, f"expected text '{expected}', got '{actual}'"
+
+
 @then("comment.timestamp is the date and time the comment was authored")
 def then_comment_timestamp_is_the_date_and_time_the_comment_was_authored(context: Context):
     assert context.comment.timestamp == dt.datetime(2025, 6, 7, 11, 20, 0, tzinfo=dt.timezone.utc)

features/steps/settings.py

@@ -1,6 +1,7 @@
 """Step implementations for document settings-related features."""
 
 from behave import given, then, when
+from behave.runner import Context
 
 from docx import Document
 from docx.settings import Settings
@@ -11,17 +12,19 @@
 
 
 @given("a document having a settings part")
-def given_a_document_having_a_settings_part(context):
+def given_a_document_having_a_settings_part(context: Context):
     context.document = Document(test_docx("doc-word-default-blank"))
 
 
 @given("a document having no settings part")
-def given_a_document_having_no_settings_part(context):
+def given_a_document_having_no_settings_part(context: Context):
     context.document = Document(test_docx("set-no-settings-part"))
 
 
 @given("a Settings object {with_or_without} odd and even page headers as settings")
-def given_a_Settings_object_with_or_without_odd_and_even_hdrs(context, with_or_without):
+def given_a_Settings_object_with_or_without_odd_and_even_hdrs(
+    context: Context, with_or_without: str
+):
     testfile_name = {"with": "doc-odd-even-hdrs", "without": "sct-section-props"}[with_or_without]
     context.settings = Document(test_docx(testfile_name)).settings
 
@@ -30,21 +33,23 @@ def given_a_Settings_object_with_or_without_odd_and_even_hdrs(context, with_or_w
 
 
 @when("I assign {bool_val} to settings.odd_and_even_pages_header_footer")
-def when_I_assign_value_to_settings_odd_and_even_pages_header_footer(context, bool_val):
+def when_I_assign_value_to_settings_odd_and_even_pages_header_footer(
+    context: Context, bool_val: str
+):
     context.settings.odd_and_even_pages_header_footer = eval(bool_val)
 
 
 # then =====================================================
 
 
 @then("document.settings is a Settings object")
-def then_document_settings_is_a_Settings_object(context):
+def then_document_settings_is_a_Settings_object(context: Context):
     document = context.document
     assert type(document.settings) is Settings
 
 
 @then("settings.odd_and_even_pages_header_footer is {bool_val}")
-def then_settings_odd_and_even_pages_header_footer_is(context, bool_val):
+def then_settings_odd_and_even_pages_header_footer_is(context: Context, bool_val: str):
     actual = context.settings.odd_and_even_pages_header_footer
     expected = eval(bool_val)
     assert actual == expected, "settings.odd_and_even_pages_header_footer is %s" % actual