Enterprise agent platform for building, deploying, and operating AI teammates.
import hashlib
import io
import json
from unittest.mock import Mock
import pytest
import requests
from docx import Document
from xagent.web.tools.mcp import word
def _docx_bytes(build_fn=None) -> bytes:
document = Document()
if build_fn:
build_fn(document)
buffer = io.BytesIO()
document.save(buffer)
return buffer.getvalue()
def _edit_metadata(etag='"abc"') -> dict:
return {
"id": "item-1",
"eTag": etag,
"parentReference": {"driveId": "drive-1"},
}
def _edit_download_mock(content: bytes, *, etag='"abc"') -> Mock:
responses = iter(
[MockResponse(_edit_metadata(etag)), MockResponse(content=content)]
)
return Mock(side_effect=lambda *a, **k: next(responses))
def _bypass_edit_checkout(monkeypatch) -> None:
"""Keep upload-mechanics tests focused; checkout has dedicated coverage."""
monkeypatch.setattr(
word, "_checkout_edit_snapshot", lambda snapshot, _message, **_kw: snapshot.etag
)
monkeypatch.setattr(
word, "_check_in_edit_snapshot", lambda _snapshot, _content: None
)
monkeypatch.setattr(word, "_discard_edit_checkout", lambda _snapshot: None)
def _snapshot_for(document: Document, etag='"abc"') -> word._EditSnapshot:
buffer = io.BytesIO()
document.save(buffer)
return word._EditSnapshot(
"/drives/drive-1/items/item-1",
etag,
hashlib.sha256(buffer.getvalue()).hexdigest(),
)
class MockResponse:
def __init__(
self,
json_data=None,
status_code=200,
content=None,
url=None,
headers=None,
):
self._json_data = json_data if json_data is not None else {}
self.status_code = status_code
self.content = (
json.dumps(self._json_data).encode("utf-8") if content is None else content
)
self.text = self.content.decode("utf-8", errors="replace")
self.url = url or "https://graph.microsoft.com/v1.0/example"
self.headers = headers if headers is not None else {}
self.closed = False
def json(self):
return self._json_data
def raise_for_status(self):
if self.status_code >= 400:
raise requests.HTTPError(
f"{self.status_code} Client Error: Error for url: {self.url}",
response=self,
)
def close(self):
self.closed = True
def __enter__(self):
return self
def __exit__(self, *exc_info):
self.close()
def iter_content(self, chunk_size=1):
content = self.content
for i in range(0, len(content), chunk_size):
yield content[i : i + chunk_size]
@pytest.fixture(autouse=True)
def _credentials(monkeypatch):
monkeypatch.setenv("AUTH_TOKEN", "test-graph-token")
# ---------------------------------------------------------------------------
# path helpers
# ---------------------------------------------------------------------------
def test_item_path_defaults_to_own_onedrive():
assert word._item_path("Report.docx", None, None) == "/me/drive/root:/Report.docx:"
@pytest.mark.parametrize(
("site_id", "drive_id", "field_name"),
[("", None, "site_id"), (None, "", "drive_id"), ("site-1", "", "drive_id")],
)
def test_item_path_rejects_explicit_empty_scope_ids(site_id, drive_id, field_name):
with pytest.raises(ValueError, match=field_name):
word._item_path("Report.docx", site_id, drive_id)
def test_item_path_closes_colon_for_path_shaped_site_id():
"""A "hostname:/relative-path" site id must be closed with a second
colon before appending "/drive", per Graph's sharepoint-addressing
docs -- otherwise "/drive" is parsed as part of the site's own
server-relative path instead of as a sub-resource name."""
path = word._item_path("Report.docx", "contoso.sharepoint.com:/teams/hr", None)
assert path == ("/sites/contoso.sharepoint.com:/teams/hr:/drive/root:/Report.docx:")
def test_item_path_leaves_composite_site_id_unchanged():
path = word._item_path("Report.docx", "contoso.sharepoint.com,site,web", None)
assert path == ("/sites/contoso.sharepoint.com,site,web/drive/root:/Report.docx:")
def test_content_path_appends_content():
assert (
word._content_path("Report.docx", None, None)
== "/me/drive/root:/Report.docx:/content"
)
def test_normalize_relative_path_rejects_trailing_period():
with pytest.raises(ValueError, match="must not end with a period"):
word._normalize_relative_path("Report.docx.")
def test_normalize_relative_path_rejects_dot_segments():
with pytest.raises(ValueError, match="must not contain"):
word._normalize_relative_path("../secret.docx")
@pytest.mark.parametrize("path", ["Report", "Report.txt", "Report.docm"])
def test_normalize_relative_path_requires_docx(path):
with pytest.raises(ValueError, match=r"\.docx"):
word._normalize_relative_path(path)
def test_normalize_relative_path_accepts_case_insensitive_docx():
assert word._normalize_relative_path("Reports/Q3.DOCX") == "Reports/Q3.DOCX"
def test_set_paragraph_text_adds_run_when_empty():
document = Document()
paragraph = document.add_paragraph()
assert not paragraph.runs
word._set_paragraph_text(paragraph, "Hello")
assert paragraph.text == "Hello"
def test_set_paragraph_text_reuses_first_run():
document = Document()
paragraph = document.add_paragraph()
paragraph.add_run("A")
paragraph.add_run("B")
paragraph.add_run("C")
word._set_paragraph_text(paragraph, "Replaced")
assert paragraph.text == "Replaced"
def test_set_paragraph_text_rejects_hyperlink_paragraph():
"""A hyperlink's own run lives inside <w:hyperlink>, outside
paragraph.runs -- word._set_paragraph_text must refuse rather than
appending a duplicate plain-text run alongside the untouched link."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
document = Document()
paragraph = document.add_paragraph()
hyperlink = OxmlElement("w:hyperlink")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "Click here"
run_elm.append(text_elm)
hyperlink.append(run_elm)
paragraph._p.append(hyperlink)
assert not paragraph.runs # confirms the hyperlink run is invisible to .runs
with pytest.raises(ValueError, match="hyperlink"):
word._set_paragraph_text(paragraph, "New text")
assert paragraph._p.findall(qn("w:hyperlink")) # untouched, not duplicated
def test_set_paragraph_text_rejects_hyperlink_nested_in_sdt():
"""A hyperlink can be wrapped in a structured document tag (<w:sdt>) --
a direct-child-only check for <w:hyperlink> would miss it and let the
zero-runs branch duplicate it instead of refusing."""
from docx.oxml.shared import OxmlElement
document = Document()
paragraph = document.add_paragraph()
sdt = OxmlElement("w:sdt")
sdt_content = OxmlElement("w:sdtContent")
hyperlink = OxmlElement("w:hyperlink")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "Click here"
run_elm.append(text_elm)
hyperlink.append(run_elm)
sdt_content.append(hyperlink)
sdt.append(sdt_content)
paragraph._p.append(sdt)
assert not paragraph.runs # confirms the hyperlink run is invisible to .runs
with pytest.raises(ValueError, match="hyperlink"):
word._set_paragraph_text(paragraph, "New text")
def test_set_paragraph_text_rejects_tracked_insertion():
"""A <w:ins>-wrapped run's text is outside paragraph.runs, so rewriting
only the direct-child runs would leave the tracked insertion's old text
stale and still physically present -- verified: it stays in the saved
XML even though it drops out of paragraph.text -- rather than replaced."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
document = Document()
paragraph = document.add_paragraph("before ")
ins = OxmlElement("w:ins")
ins.set(qn("w:author"), "Alice")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "Q3 revenue"
run_elm.append(text_elm)
ins.append(run_elm)
paragraph._p.append(ins)
with pytest.raises(ValueError, match="tracked change"):
word._set_paragraph_text(paragraph, "New text")
def test_set_paragraph_text_rejects_content_control():
"""A <w:sdt> (structured document tag / content control) holds its own
runs the same way a hyperlink does -- invisible to paragraph.runs."""
from docx.oxml.shared import OxmlElement
document = Document()
paragraph = document.add_paragraph()
sdt = OxmlElement("w:sdt")
sdt_content = OxmlElement("w:sdtContent")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "field value"
run_elm.append(text_elm)
sdt_content.append(run_elm)
sdt.append(sdt_content)
paragraph._p.append(sdt)
with pytest.raises(ValueError, match="content control"):
word._set_paragraph_text(paragraph, "New text")
@pytest.mark.parametrize(
"tag",
[
"w:smartTag",
"w:customXml",
"w:fldSimple",
"w:bdo",
"w:dir",
"w14:conflictIns",
"w14:conflictDel",
],
)
def test_set_paragraph_text_rejects_other_run_owning_wrappers(tag):
"""w:smartTag (a legacy Office smart tag), w:customXml (a custom XML
markup region), and w:fldSimple (a simple field's cached result, e.g.
PAGE/DATE/a TOC entry) all hold their own runs outside paragraph.runs
the same way a hyperlink or content control does -- verified directly:
the wrapped text is still physically present in the saved XML after a
rewrite, stale alongside the new text."""
from docx.oxml.shared import OxmlElement
document = Document()
paragraph = document.add_paragraph()
wrapper = OxmlElement(tag)
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "wrapped value"
run_elm.append(text_elm)
wrapper.append(run_elm)
paragraph._p.append(wrapper)
assert not paragraph.runs # confirms the wrapped run is invisible to .runs
with pytest.raises(ValueError):
word._set_paragraph_text(paragraph, "New text")
def test_set_paragraph_text_rejects_office_math():
from docx.oxml.shared import OxmlElement
document = Document()
paragraph = document.add_paragraph()
math = OxmlElement("m:oMath")
math_run = OxmlElement("m:r")
math_text = OxmlElement("m:t")
math_text.text = "x + y"
math_run.append(math_text)
math.append(math_run)
paragraph._p.append(math)
with pytest.raises(ValueError, match="Office Math"):
word._set_paragraph_text(paragraph, "New text")
def test_set_paragraph_text_rejects_run_with_image():
import base64
from docx.shared import Inches
png_bytes = base64.b64decode(
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUB"
"AScY42YAAAAASUVORK5CYII="
)
document = Document()
paragraph = document.add_paragraph("caption ")
picture_run = paragraph.add_run()
picture_run.add_picture(io.BytesIO(png_bytes), width=Inches(0.1))
with pytest.raises(ValueError, match="non-text content"):
word._set_paragraph_text(paragraph, "New text")
def test_set_paragraph_text_rejects_run_with_page_break():
from docx.enum.text import WD_BREAK
document = Document()
paragraph = document.add_paragraph()
run = paragraph.add_run()
run.add_break(WD_BREAK.PAGE)
with pytest.raises(ValueError, match="non-text content"):
word._set_paragraph_text(paragraph, "New text")
def test_run_has_non_text_content_rejects_unlisted_element_kinds():
"""_run_has_non_text_content treats any child other than <w:rPr>/<w:t>
as unsafe, not just the specific tags this module happens to test --
<w:noBreakHyphen> and <w:sym> are silently destroyed by Run.text just
like an image or field character, verified directly against
python-docx's own CT_R.text setter, but neither has a dedicated test
above (nor is either tag hardcoded anywhere in the guard itself)."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
for tag, attrs in [
("w:noBreakHyphen", {}),
("w:sym", {"w:font": "Wingdings", "w:char": "F0E0"}),
]:
document = Document()
paragraph = document.add_paragraph()
run = paragraph.add_run("A")
elm = OxmlElement(tag)
for name, value in attrs.items():
elm.set(qn(name), value)
run._r.append(elm)
assert word._run_has_non_text_content(run), tag
def test_set_paragraph_text_rejects_run_with_tab():
"""A <w:tab> is not itself corrupted by Run.text (python-docx's setter
reconstructs it from a literal \\t), but the guard is deliberately
conservative -- it only special-cases <w:rPr>/<w:t> as known-safe
rather than trying to keep an allowlist of every element that happens
to round-trip correctly -- so a run with a tab is refused too."""
document = Document()
paragraph = document.add_paragraph()
run = paragraph.add_run()
run.add_tab()
with pytest.raises(ValueError, match="non-text content"):
word._set_paragraph_text(paragraph, "New text")
# ---------------------------------------------------------------------------
# create / existence check
# ---------------------------------------------------------------------------
def test_create_document_rejects_when_session_creation_conflicts(monkeypatch):
mock_request = Mock(
return_value=MockResponse(
{"error": {"code": "nameAlreadyExists"}}, status_code=409
)
)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_create_document("Report.docx"))
assert result["status"] == "error"
assert "already exists" in result["message"]
assert mock_request.call_args.kwargs["url"].endswith("createUploadSession")
def test_create_document_rejects_when_upload_put_conflicts(monkeypatch):
mock_request = Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
)
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(
return_value=MockResponse(
{"error": {"code": "nameAlreadyExists"}}, status_code=409
)
)
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_create_document("Report.docx"))
assert result["status"] == "error"
assert "already exists" in result["message"]
def test_create_document_upload_failure_does_not_leak_session_url(monkeypatch):
"""The upload-session URL is a pre-authenticated bearer secret (a token
in its own query string) -- a failed upload must never let that URL
reach the caller through the error message, whether the failure comes
from raise_for_status() or a lower-level connection/timeout error."""
secret_url = "https://upload.example/session?token=super-secret-value"
mock_request = Mock(return_value=MockResponse({"uploadUrl": secret_url}))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({}, status_code=500, url=secret_url))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_create_document("Report.docx"))
assert result["status"] == "error"
assert "super-secret-value" not in result["message"]
assert secret_url not in result["message"]
def test_create_document_upload_connection_error_does_not_leak_session_url(
monkeypatch,
):
secret_url = "https://upload.example/session?token=super-secret-value"
mock_request = Mock(return_value=MockResponse({"uploadUrl": secret_url}))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(
side_effect=requests.ConnectionError(f"Connection refused: {secret_url}")
)
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_create_document("Report.docx"))
assert result["status"] == "error"
assert "super-secret-value" not in result["message"]
assert secret_url not in result["message"]
def test_create_only_upload_does_not_chain_secret_bearing_exception(monkeypatch):
"""raise ... from exc would still attach the original, URL-bearing
exception as __cause__ even though the raised message itself is
sanitized -- a future traceback/log/APM capture could surface it.
from None must be used instead, matching onedrive.py's precedent."""
secret_url = "https://upload.example/session?token=super-secret-value"
mock_request = Mock(return_value=MockResponse({"uploadUrl": secret_url}))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({}, status_code=500, url=secret_url))
monkeypatch.setattr(word.requests, "put", mock_put)
monkeypatch.setattr(
word.requests, "get", Mock(side_effect=requests.ConnectionError("dropped"))
)
monkeypatch.setattr(word.time, "sleep", Mock())
with pytest.raises(RuntimeError) as exc_info:
word._create_only_upload(_docx_bytes(), "Report.docx", None, None)
assert exc_info.value.__cause__ is None
def test_create_only_upload_connection_error_does_not_chain_exception(monkeypatch):
secret_url = "https://upload.example/session?token=super-secret-value"
mock_request = Mock(return_value=MockResponse({"uploadUrl": secret_url}))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(
side_effect=requests.ConnectionError(f"Connection refused: {secret_url}")
)
monkeypatch.setattr(word.requests, "put", mock_put)
monkeypatch.setattr(
word.requests, "get", Mock(side_effect=requests.ConnectionError("dropped"))
)
monkeypatch.setattr(word.time, "sleep", Mock())
with pytest.raises(RuntimeError) as exc_info:
word._create_only_upload(_docx_bytes(), "Report.docx", None, None)
assert exc_info.value.__cause__ is None
def test_create_document_uploads_blank_document(monkeypatch):
mock_request = Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
)
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "new-item"}, status_code=201))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_create_document("Report.docx"))
assert result["status"] == "success"
assert result["item"]["id"] == "new-item"
session_call = mock_request.call_args
assert session_call.kwargs["url"].endswith("createUploadSession")
assert session_call.kwargs["json"] == {
"item": {"@microsoft.graph.conflictBehavior": "fail"}
}
put_call = mock_put.call_args
assert put_call.args[0] == "https://upload.example/session"
assert put_call.kwargs["headers"]["Content-Type"] == word._WORD_MIME_TYPE
assert "Authorization" not in put_call.kwargs.get("headers", {})
# Re-parses as a real, valid (if blank) docx.
Document(io.BytesIO(put_call.kwargs["data"]))
def test_create_document_projects_driveitem_to_small_stable_fields(monkeypatch):
"""A committed write must never return the full Graph driveItem -- only
the small stable fields a caller needs (id, eTag, name). The full item
carries unbounded fields (webUrl, parentReference, identity metadata)
that could push the response past the output cap, where the outer
raw-truncating output filter would mangle it into invalid JSON after
the write has already committed."""
mock_request = Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
)
monkeypatch.setattr(word.requests, "request", mock_request)
big_item = {
"id": "new-item",
"eTag": '"abc"',
"name": "Report.docx",
"@microsoft.graph.downloadUrl": "https://download.example/secret-token",
"webUrl": "https://contoso.sharepoint.com/" + "a" * 500,
"parentReference": {"driveId": "drive-1", "path": "/drive/root:/Folder"},
"createdBy": {"user": {"displayName": "Someone", "id": "user-1"}},
}
mock_put = Mock(return_value=MockResponse(big_item, status_code=201))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_create_document("Report.docx"))
assert result["status"] == "success"
assert result["item"] == {"id": "new-item", "eTag": '"abc"', "name": "Report.docx"}
def test_success_with_item_degrades_to_fit_a_low_cap(monkeypatch):
"""Even the projected {id, eTag, name} envelope isn't provably bounded --
an unusually long name must not prevent _success_with_item from
returning valid JSON that fits the configured cap."""
monkeypatch.setattr(word, "get_tool_max_output_length", lambda: 60)
item = {"id": "item-1", "eTag": '"abc"', "name": "a" * 200}
encoded = word._success_with_item(item)
assert len(encoded) <= 60
parsed = json.loads(encoded)
assert parsed["status"] == "success"
def test_create_document_does_not_claim_identical_destination_after_lost_response(
monkeypatch,
):
content = _docx_bytes()
mock_request = Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
)
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(side_effect=requests.ConnectionError("committed response was lost"))
monkeypatch.setattr(
word.requests,
"put",
mock_put,
)
monkeypatch.setattr(
word.requests, "get", Mock(return_value=MockResponse({}, status_code=404))
)
monkeypatch.setattr(word.time, "sleep", Mock())
with pytest.raises(RuntimeError, match="outcome is unknown"):
word._create_only_upload(content, "Report.docx", None, None)
# Only createUploadSession is addressed through Graph. In particular, the
# destination path is never read and byte-compared to claim another
# session's indistinguishable blank document.
assert mock_request.call_count == 1
assert mock_put.call_count == 1
# ---------------------------------------------------------------------------
# read
# ---------------------------------------------------------------------------
def test_get_document_text_joins_paragraphs(monkeypatch):
content = _docx_bytes(
lambda d: (d.add_paragraph("First"), d.add_paragraph("Second"))
)
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "success"
assert result["text"] == "First\nSecond"
assert result["table_count"] == 0
def test_get_document_text_rejects_non_docx_content(monkeypatch):
mock_request = Mock(return_value=MockResponse(content=b"not a docx file"))
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "error"
assert "Word document" in result["message"]
def test_get_document_text_streams_with_identity_encoding(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("hello"))
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
word.word_get_document_text("Report.docx")
_, kwargs = mock_request.call_args
assert kwargs["stream"] is True
assert kwargs["headers"]["Accept-Encoding"] == "identity"
def test_get_document_text_rejects_declared_content_length_over_limit(monkeypatch):
oversized = word._MAX_DOWNLOAD_BYTES + 1
mock_request = Mock(
return_value=MockResponse(
content=b"irrelevant",
headers={"Content-Length": str(oversized)},
)
)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "error"
assert "too large" in result["message"]
def test_get_document_text_rejects_streamed_body_over_limit(monkeypatch):
# No (or a wrong) Content-Length header must not bypass the cap -- the
# streamed byte count is the source of truth.
oversized_content = b"x" * (word._MAX_DOWNLOAD_BYTES + 1)
mock_request = Mock(return_value=MockResponse(content=oversized_content))
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "error"
assert "too large" in result["message"]
def test_get_document_text_rejects_compressed_content_encoding(monkeypatch):
mock_request = Mock(
return_value=MockResponse(
content=b"compressed-bytes",
headers={"Content-Encoding": "gzip"},
)
)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "error"
assert "compressed" in result["message"]
def test_get_document_text_closes_connection_on_rejection(monkeypatch):
# A stream=True response left open on a rejection path holds its
# connection until garbage collection instead of returning it to the
# pool immediately -- every rejection branch in _read_capped_content
# must close the response, not just a fully-consumed one.
response = MockResponse(
content=b"compressed-bytes", headers={"Content-Encoding": "gzip"}
)
mock_request = Mock(return_value=response)
monkeypatch.setattr(word.requests, "request", mock_request)
word.word_get_document_text("Report.docx")
assert response.closed is True
def test_get_document_text_download_error_does_not_leak_redirect_url(monkeypatch):
"""Graph's /content redirects to a pre-authenticated download URL --
itself a bearer secret. A connection failure while following that
redirect embeds the URL in requests' own exception message, so it must
not be stringified into the returned error."""
secret_url = "https://download.example/blob?token=super-secret-value"
def side_effect(*args, **kwargs):
if kwargs.get("params") == {"$select": "eTag"}:
return MockResponse({})
raise requests.ConnectionError(f"Connection refused: {secret_url}")
mock_request = Mock(side_effect=side_effect)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "error"
assert "super-secret-value" not in result["message"]
assert secret_url not in result["message"]
def test_list_paragraphs_includes_style(monkeypatch):
content = _docx_bytes(lambda d: d.add_heading("Title", level=1))
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_list_paragraphs("Report.docx"))
assert result["status"] == "success"
paragraph = result["paragraphs"][0]
assert {key: paragraph[key] for key in ("index", "text", "style")} == {
"index": 0,
"text": "Title",
"style": "Heading 1",
}
assert result["has_more"] is False
def test_read_generation_rejects_changed_document_on_continuation(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("changed"))
monkeypatch.setattr(
word.requests, "request", Mock(return_value=MockResponse(content=content))
)
result = json.loads(
word.word_get_document_text(
"Report.docx", offset=1, expected_generation="stale-generation"
)
)
assert result["status"] == "error"
assert "changed" in result["message"]
def test_read_continuation_requires_generation():
result = json.loads(word.word_get_document_text("Report.docx", offset=1))
assert result["status"] == "error"
assert "expected_generation" in result["message"]
def test_low_output_cap_still_returns_valid_json(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("x" * 1_000))
monkeypatch.setattr(
word.requests, "request", Mock(return_value=MockResponse(content=content))
)
monkeypatch.setattr(word, "get_tool_max_output_length", lambda: 100)
encoded = word.word_get_document_text("Report.docx")
assert len(encoded) <= 100
assert json.loads(encoded)["status"] == "error"
def test_get_document_text_is_explicitly_main_body_only(monkeypatch):
def build(document):
document.add_paragraph("body")
document.sections[0].header.paragraphs[0].text = "header"
document.sections[0].footer.paragraphs[0].text = "footer"
content = _docx_bytes(build)
monkeypatch.setattr(
word.requests, "request", Mock(return_value=MockResponse(content=content))
)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["text"] == "body"
def test_get_document_text_pages_are_valid_json_and_recover_all_text(monkeypatch):
expected = ('quote " and slash \\ and text ' * 800).strip()
content = _docx_bytes(lambda d: d.add_paragraph(expected))
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(
word, "get_tool_max_output_length", lambda: word._MIN_PAGINATION_OUTPUT_LENGTH
)
offset = 0
generation = None
chunks = []
while True:
encoded = word.word_get_document_text(
"Report.docx",
offset=offset,
limit=1,
expected_generation=generation,
)
assert len(encoded) <= word._MIN_PAGINATION_OUTPUT_LENGTH
page = json.loads(encoded)
assert page["status"] == "success"
chunks.append(page["text"])
if not page["has_more"]:
break
assert page["next_offset"] > offset
assert page["next_offset"] - offset >= word._MIN_TEXT_PAGE_CHARS
offset = page["next_offset"]
generation = page["generation"]
assert "".join(chunks) == expected
def test_list_paragraphs_normalizes_tiny_limit_without_skipping(monkeypatch):
expected = [f"paragraph-{index}" for index in range(105)]
content = _docx_bytes(lambda d: [d.add_paragraph(text) for text in expected])
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
first = json.loads(word.word_list_paragraphs("Report.docx", limit=1))
second = json.loads(
word.word_list_paragraphs(
"Report.docx",
offset=first["next_offset"],
text_offset=first["next_text_offset"],
limit=1,
expected_generation=first["generation"],
)
)
assert [p["text"] for p in first["paragraphs"]] == expected[:100]
assert first["has_more"] is True
assert [p["text"] for p in second["paragraphs"]] == expected[100:]
assert second["has_more"] is False
def test_list_paragraphs_splits_one_oversized_paragraph_recoverably(monkeypatch):
expected = "x" * 40_000
content = _docx_bytes(lambda d: d.add_paragraph(expected))
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(
word, "get_tool_max_output_length", lambda: word._MIN_PAGINATION_OUTPUT_LENGTH
)
offset = 0
text_offset = 0
generation = None
chunks = []
while True:
encoded = word.word_list_paragraphs(
"Report.docx",
offset=offset,
text_offset=text_offset,
limit=1,
expected_generation=generation,
)
assert len(encoded) <= word._MIN_PAGINATION_OUTPUT_LENGTH
page = json.loads(encoded)
chunks.append(page["paragraphs"][0]["text"])
if not page["has_more"]:
break
assert page["next_offset"] == 0
assert page["next_text_offset"] > text_offset
offset = page["next_offset"]
text_offset = page["next_text_offset"]
generation = page["generation"]
assert "".join(chunks) == expected
@pytest.mark.parametrize(
"tool", [word.word_get_document_text, word.word_list_paragraphs]
)
def test_paginated_reads_reject_tiny_output_cap_before_download(monkeypatch, tool):
mock_request = Mock()
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(
word,
"get_tool_max_output_length",
lambda: word._MIN_PAGINATION_OUTPUT_LENGTH - 1,
)
result = json.loads(tool("Report.docx"))
assert result["status"] == "error"
assert "requires XAGENT_TOOL_MAX_OUTPUT_LENGTH" in result["message"]
mock_request.assert_not_called()
@pytest.mark.parametrize(
"call",
[
lambda: word.word_create_document("Report.docx"),
lambda: word.word_set_paragraph_text(
"Report.docx", 0, "New text", expected_generation="deadbeef"
),
lambda: word.word_append_paragraph("Report.docx", "New text"),
lambda: word.word_add_heading("Report.docx", "New heading"),
lambda: word.word_insert_page_break("Report.docx"),
lambda: word.word_replace_text("Report.docx", "find", "replace"),
],
)
def test_mutating_tools_reject_tiny_output_cap_before_graph_work(monkeypatch, call):
"""A cap too small for _success() to fit lets the outer output filter
raw-truncate a real response into invalid JSON, since only _error() (not
_success()) degrades gracefully. Rejecting the cap upfront, before any
Graph work, avoids ever generating that unparsable output."""
mock_request = Mock()
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock()
monkeypatch.setattr(word.requests, "put", mock_put)
monkeypatch.setattr(
word,
"get_tool_max_output_length",
lambda: word._MIN_TOOL_OUTPUT_LENGTH - 1,
)
result = json.loads(call())
assert result["status"] == "error"
assert "XAGENT_TOOL_MAX_OUTPUT_LENGTH" in result["message"]
mock_request.assert_not_called()
mock_put.assert_not_called()
# ---------------------------------------------------------------------------
# write
# ---------------------------------------------------------------------------
def test_set_paragraph_text_out_of_range(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("Only paragraph"))
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
generation = hashlib.sha256(content).hexdigest()
result = json.loads(
word.word_set_paragraph_text(
"Report.docx", 5, "New text", expected_generation=generation
)
)
assert result["status"] == "error"
assert "out of range" in result["message"]
def test_set_paragraph_text_requires_read_generation():
result = json.loads(word.word_set_paragraph_text("Report.docx", 0, "New text"))
assert result["status"] == "error"
assert "expected_generation" in result["message"]
def test_set_paragraph_text_uploads_updated_document(monkeypatch):
_bypass_edit_checkout(monkeypatch)
content = _docx_bytes(lambda d: d.add_paragraph("Old text"))
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}, status_code=200))
monkeypatch.setattr(word.requests, "put", mock_put)
generation = hashlib.sha256(content).hexdigest()
result = json.loads(
word.word_set_paragraph_text(
"Report.docx", 0, "New text", expected_generation=generation
)
)
assert result["status"] == "success"
session_call = mock_request.call_args_list[2]
assert session_call.kwargs["headers"]["If-Match"] == '"abc"'
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[0].text == "New text"
def test_append_paragraph(monkeypatch):
_bypass_edit_checkout(monkeypatch)
content = _docx_bytes()
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_append_paragraph("Report.docx", "New paragraph"))
assert result["status"] == "success"
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[-1].text == "New paragraph"
@pytest.mark.parametrize(
("tool", "text"),
[
(word.word_append_paragraph, "New paragraph"),
(word.word_add_heading, "New heading"),
],
)
def test_word_mutation_can_start_on_new_page(monkeypatch, tool, text):
_bypass_edit_checkout(monkeypatch)
content = _docx_bytes()
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(tool("Report.docx", text, page_break_before=True))
assert result["status"] == "success"
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[-1].text == text
assert uploaded.paragraphs[-1].paragraph_format.page_break_before is True
def test_insert_page_break_at_end(monkeypatch):
_bypass_edit_checkout(monkeypatch)
def build(document):
document.add_paragraph("Existing")
document.add_table(rows=1, cols=1)
content = _docx_bytes(build)
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_insert_page_break("Report.docx"))
assert result["status"] == "success"
assert result["page_break_paragraph_index"] == 1
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[0].text == "Existing"
break_paragraph = uploaded.paragraphs[1]
assert break_paragraph.runs[-1]._r.xpath("./w:br[@w:type='page']")
assert list(uploaded.element.body).index(uploaded.tables[0]._tbl) < list(
uploaded.element.body
).index(break_paragraph._p)
def test_insert_page_break_after_paragraph_uses_generation(monkeypatch):
_bypass_edit_checkout(monkeypatch)
content = _docx_bytes(
lambda d: (d.add_paragraph("First"), d.add_paragraph("Second"))
)
generation = hashlib.sha256(content).hexdigest()
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(
word.word_insert_page_break(
"Report.docx", after_paragraph_index=0, expected_generation=generation
)
)
assert result["status"] == "success"
assert result["page_break_paragraph_index"] == 1
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[0].text == "First"
assert not uploaded.paragraphs[0].runs[-1]._r.xpath("./w:br[@w:type='page']")
assert uploaded.paragraphs[1].runs[-1]._r.xpath("./w:br[@w:type='page']")
assert uploaded.paragraphs[2].text == "Second"
def test_insert_page_break_at_index_requires_generation(monkeypatch):
mock_request = Mock()
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(
word.word_insert_page_break("Report.docx", after_paragraph_index=0)
)
assert result["status"] == "error"
assert "expected_generation" in result["message"]
mock_request.assert_not_called()
@pytest.mark.parametrize("after_paragraph_index", [-1, 1])
def test_insert_page_break_rejects_out_of_range_index(
monkeypatch, after_paragraph_index
):
_bypass_edit_checkout(monkeypatch)
content = _docx_bytes(lambda d: d.add_paragraph("Only paragraph"))
generation = hashlib.sha256(content).hexdigest()
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock()
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(
word.word_insert_page_break(
"Report.docx",
after_paragraph_index=after_paragraph_index,
expected_generation=generation,
)
)
assert result["status"] == "error"
assert "out of range" in result["message"]
mock_put.assert_not_called()
def test_insert_page_break_rejects_stale_generation(monkeypatch):
_bypass_edit_checkout(monkeypatch)
content = _docx_bytes(lambda d: d.add_paragraph("Only paragraph"))
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock()
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(
word.word_insert_page_break(
"Report.docx",
after_paragraph_index=0,
expected_generation="0" * 64,
)
)
assert result["status"] == "error"
assert "changed since" in result["message"]
mock_put.assert_not_called()
def test_add_heading_validates_level():
result = json.loads(word.word_add_heading("Report.docx", "Title", level=10))
assert result["status"] == "error"
assert "level" in result["message"]
def test_add_heading_uploads_updated_document(monkeypatch):
_bypass_edit_checkout(monkeypatch)
content = _docx_bytes()
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_add_heading("Report.docx", "Section", level=2))
assert result["status"] == "success"
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[-1].text == "Section"
assert uploaded.paragraphs[-1].style.name == "Heading 2"
def test_replace_text_counts_matches_within_runs(monkeypatch):
_bypass_edit_checkout(monkeypatch)
def build(d):
p = d.add_paragraph()
p.add_run("foo bar foo")
content = _docx_bytes(build)
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "success"
assert result["replacements"] == 2
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[0].text == "baz bar baz"
def test_replace_text_rejects_large_expansion_via_arithmetic_not_allocation(
monkeypatch,
):
"""The per-run growth budget must be checked using count * per-match
length delta -- integer arithmetic -- before run.text.replace() is ever
called. A run holding many repeats of a short match, replaced with a
long string, would otherwise materialize a replaced string far larger
than any budget could reject in time: 100,000 repeats of a 1-character
match times a 100,000-character replacement asks for ~10 billion
characters (several GB), long before either mutation budget below (400k)
is checked against the *already built* string."""
import tracemalloc
content = _docx_bytes(lambda d: d.add_paragraph("a" * 100_000))
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
tracemalloc.start()
try:
result = json.loads(word.word_replace_text("Report.docx", "a", "b" * 100_000))
finally:
_current, peak = tracemalloc.get_traced_memory()
tracemalloc.stop()
assert result["status"] == "error"
assert "too much text" in result["message"]
# Proves the budget was enforced via arithmetic on `count`, not by first
# building the ~10 billion character replaced string (several GB) --
# peak traced memory stays orders of magnitude smaller.
assert peak < 5_000_000
assert mock_request.call_count == 2
def test_replace_text_rejects_empty_find():
result = json.loads(word.word_replace_text("Report.docx", "", "x"))
assert result["status"] == "error"
def test_replace_text_skips_upload_when_nothing_matches(monkeypatch):
"""A no-op request must not still create a new document version --
uploading an unmodified document has no reason to happen."""
content = _docx_bytes(lambda d: d.add_paragraph("nothing relevant here"))
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "absent", "x"))
assert result["status"] == "success"
assert result["replacements"] == 0
assert "item" not in result
# Only the metadata + content download GETs happened -- no upload.
assert mock_request.call_count == 2
def test_replace_text_rejects_match_in_run_with_image(monkeypatch):
"""A match inside a run that also holds a drawing must be refused, not
silently applied -- run.text = ... would delete the drawing too."""
import base64
from docx.shared import Inches
png_bytes = base64.b64decode(
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUB"
"AScY42YAAAAASUVORK5CYII="
)
def build(d):
p = d.add_paragraph()
run = p.add_run("foo bar")
run.add_picture(io.BytesIO(png_bytes), width=Inches(0.1))
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "error"
assert "non-text content" in result["message"]
# Only the metadata + content download GETs happened -- no upload.
assert mock_request.call_count == 2
def test_replace_text_rejects_match_inside_content_control(monkeypatch):
"""A match inside a <w:sdt>'s run must be refused, not silently
rewritten -- doing so would desync the control's data binding, which
this tool has no way to update to match."""
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph()
sdt = OxmlElement("w:sdt")
sdt_content = OxmlElement("w:sdtContent")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "foo bar"
run_elm.append(text_elm)
sdt_content.append(run_elm)
sdt.append(sdt_content)
p._p.append(sdt)
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "error"
assert "content control" in result["message"]
# Only the metadata + content download GETs happened -- no upload.
assert mock_request.call_count == 2
def test_replace_text_rejects_match_inside_simple_field(monkeypatch):
"""A <w:fldSimple>'s cached result (e.g. a PAGE/DATE field or a TOC
entry) must be refused -- rewriting the cached text leaves the field's
own instruction unchanged, so Word's next refresh can revert it."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph()
fld_simple = OxmlElement("w:fldSimple")
fld_simple.set(qn("w:instr"), "PAGE")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "foo bar"
run_elm.append(text_elm)
fld_simple.append(run_elm)
p._p.append(fld_simple)
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "error"
assert "field" in result["message"]
# Only the metadata + content download GETs happened -- no upload.
assert mock_request.call_count == 2
@pytest.mark.parametrize("tag", ["w:smartTag", "w:customXml"])
def test_replace_text_rejects_match_inside_smart_tag_or_custom_xml(monkeypatch, tag):
"""word_set_paragraph_text already refuses a paragraph containing
w:smartTag/w:customXml -- word_replace_text's own, separate per-run
guard must refuse a match inside one too, not just w:sdt/w:fldSimple."""
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph()
wrapper = OxmlElement(tag)
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "foo bar"
run_elm.append(text_elm)
wrapper.append(run_elm)
p._p.append(wrapper)
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "error"
assert mock_request.call_count == 2
def test_replace_text_rejects_match_inside_complex_field_result(monkeypatch):
"""A complex field (begin/instrText/separate/result/end run sequence)
has no single wrapper element -- its cached result run must still be
recognized and refused via the fldChar state machine."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph()
def add_run_with(*children):
run_elm = OxmlElement("w:r")
for child in children:
run_elm.append(child)
p._p.append(run_elm)
begin = OxmlElement("w:fldChar")
begin.set(qn("w:fldCharType"), "begin")
add_run_with(begin)
instr = OxmlElement("w:instrText")
instr.text = " PAGEREF _Toc123 "
add_run_with(instr)
separate = OxmlElement("w:fldChar")
separate.set(qn("w:fldCharType"), "separate")
add_run_with(separate)
result_text = OxmlElement("w:t")
result_text.text = "foo bar"
add_run_with(result_text)
end = OxmlElement("w:fldChar")
end.set(qn("w:fldCharType"), "end")
add_run_with(end)
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "error"
assert "field" in result["message"]
# Only the metadata + content download GETs happened -- no upload.
assert mock_request.call_count == 2
def test_replace_text_rejects_match_inside_field_spanning_paragraphs(monkeypatch):
"""A complex field commonly opens in one paragraph and closes several
paragraphs later -- a multi-entry table of contents has its own begin/
separate in the first entry's paragraph, one entry per paragraph, and
end in the last. Tracking field state fresh per paragraph call would
lose protection for every entry after the first; it must be threaded
across the whole document instead."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
def add_run_with(paragraph, *children):
run_elm = OxmlElement("w:r")
for child in children:
run_elm.append(child)
paragraph._p.append(run_elm)
def build(d):
p0 = d.add_paragraph()
begin = OxmlElement("w:fldChar")
begin.set(qn("w:fldCharType"), "begin")
add_run_with(p0, begin)
instr = OxmlElement("w:instrText")
instr.text = " TOC "
add_run_with(p0, instr)
separate = OxmlElement("w:fldChar")
separate.set(qn("w:fldCharType"), "separate")
add_run_with(p0, separate)
p1 = d.add_paragraph()
entry_text = OxmlElement("w:t")
entry_text.text = "foo bar"
add_run_with(p1, entry_text)
p2 = d.add_paragraph()
end = OxmlElement("w:fldChar")
end.set(qn("w:fldCharType"), "end")
add_run_with(p2, end)
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "error"
assert "field" in result["message"]
def test_replace_text_edits_ordinary_text_after_a_field_ends(monkeypatch):
"""State must not leak past a field's own "end" marker -- a paragraph
with nothing but ordinary text, appearing after a completed field,
must remain freely editable."""
_bypass_edit_checkout(monkeypatch)
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
def add_run_with(paragraph, *children):
run_elm = OxmlElement("w:r")
for child in children:
run_elm.append(child)
paragraph._p.append(run_elm)
def build(d):
p0 = d.add_paragraph()
begin = OxmlElement("w:fldChar")
begin.set(qn("w:fldCharType"), "begin")
add_run_with(p0, begin)
separate = OxmlElement("w:fldChar")
separate.set(qn("w:fldCharType"), "separate")
add_run_with(p0, separate)
result_text = OxmlElement("w:t")
result_text.text = "cached result"
add_run_with(p0, result_text)
end = OxmlElement("w:fldChar")
end.set(qn("w:fldCharType"), "end")
add_run_with(p0, end)
d.add_paragraph("foo bar")
content = _docx_bytes(build)
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "success"
assert result["replacements"] == 1
def test_replace_text_rejects_match_in_outer_field_result_after_nested_field(
monkeypatch,
):
"""A field nested inside another field's result region (e.g. a TOC
entry's page number is itself a nested PAGEREF field) must not let its
own "end" prematurely un-protect the outer field's remaining result --
a single boolean flag gets this wrong; a depth stack doesn't."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
def add_run_with(paragraph, *children):
run_elm = OxmlElement("w:r")
for child in children:
run_elm.append(child)
paragraph._p.append(run_elm)
def fld_char(fld_type):
elm = OxmlElement("w:fldChar")
elm.set(qn("w:fldCharType"), fld_type)
return elm
def text_run(text):
elm = OxmlElement("w:t")
elm.text = text
return elm
def build(d):
p = d.add_paragraph()
add_run_with(p, fld_char("begin")) # outer begin
add_run_with(p, fld_char("separate")) # outer separate
add_run_with(p, fld_char("begin")) # nested begin
add_run_with(p, fld_char("separate")) # nested separate
add_run_with(p, text_run("nested result"))
add_run_with(p, fld_char("end")) # nested end
add_run_with(p, text_run("foo bar")) # outer's own trailing result
add_run_with(p, fld_char("end")) # outer end
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "error"
assert "field" in result["message"]
def test_replace_text_ignores_field_state_from_tracked_insertion(monkeypatch):
"""A complex field entirely inside a tracked-change insertion is
correctly skipped (it's not visible through this module's read tools
either) -- but its fldChar markers must not leak field-protected state
onto ordinary text later in the same paragraph."""
_bypass_edit_checkout(monkeypatch)
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph()
ins = OxmlElement("w:ins")
for fld_type in ("begin", "separate"):
run_elm = OxmlElement("w:r")
fld = OxmlElement("w:fldChar")
fld.set(qn("w:fldCharType"), fld_type)
run_elm.append(fld)
ins.append(run_elm)
result_run = OxmlElement("w:r")
result_text = OxmlElement("w:t")
result_text.text = "tracked field result"
result_run.append(result_text)
ins.append(result_run)
end_run = OxmlElement("w:r")
end_fld = OxmlElement("w:fldChar")
end_fld.set(qn("w:fldCharType"), "end")
end_run.append(end_fld)
ins.append(end_run)
p._p.append(ins)
p.add_run("foo bar")
content = _docx_bytes(build)
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "success"
assert result["replacements"] == 1
def test_replace_text_finds_match_inside_hyperlink_run(monkeypatch):
"""paragraph.runs excludes runs nested inside <w:hyperlink>. Iterating
only paragraph.runs would silently skip a match inside hyperlink text
even though word_get_document_text surfaces that same text."""
_bypass_edit_checkout(monkeypatch)
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph("before ")
hyperlink = OxmlElement("w:hyperlink")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "foo bar"
run_elm.append(text_elm)
hyperlink.append(run_elm)
p._p.append(hyperlink)
p.add_run(" after")
content = _docx_bytes(build)
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"uploadUrl": "https://upload.example/session"}),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "success"
assert result["replacements"] == 1
uploaded = Document(io.BytesIO(mock_put.call_args.kwargs["data"]))
assert uploaded.paragraphs[0].text == "before baz bar after"
def test_replace_text_ignores_match_inside_tracked_insertion(monkeypatch):
"""A <w:ins>-wrapped run holds someone else's pending, unaccepted
tracked-change insertion. A plain recursive run search would reach it
(unlike paragraph.runs, which excludes it) and silently rewrite that
person's edit with no new revision recorded -- must not touch it."""
from docx.oxml.ns import qn
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph("before ")
ins = OxmlElement("w:ins")
ins.set(qn("w:author"), "Alice")
run_elm = OxmlElement("w:r")
text_elm = OxmlElement("w:t")
text_elm.text = "foo bar"
run_elm.append(text_elm)
ins.append(run_elm)
p._p.append(ins)
p.add_run(" after")
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "success"
assert result["replacements"] == 0
# No match means no change -- only the download GET happened.
# Only the metadata + content download GETs happened -- no upload.
assert mock_request.call_count == 2
def test_replace_text_ignores_match_inside_text_box(monkeypatch):
"""A text box's content is a separate stream anchored to (not part of)
the run holding its <w:drawing> -- invisible to word_get_document_text
and word_list_paragraphs, so word_replace_text must not silently edit
it either."""
from docx.oxml.shared import OxmlElement
def build(d):
p = d.add_paragraph("outer text")
anchor = p.add_run()
drawing = OxmlElement("w:drawing")
txbx_content = OxmlElement("w:txbxContent")
inner_p = OxmlElement("w:p")
inner_run = OxmlElement("w:r")
inner_text = OxmlElement("w:t")
inner_text.text = "foo bar"
inner_run.append(inner_text)
inner_p.append(inner_run)
txbx_content.append(inner_p)
drawing.append(txbx_content)
anchor._r.append(drawing)
content = _docx_bytes(build)
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_replace_text("Report.docx", "foo", "baz"))
assert result["status"] == "success"
assert result["replacements"] == 0
# No match means no change -- only the download GET happened.
# Only the metadata + content download GETs happened -- no upload.
assert mock_request.call_count == 2
def test_set_paragraph_text_ignores_hyperlink_inside_text_box():
"""A hyperlink nested inside a text box isn't part of this paragraph's
own visible flow (word_get_document_text/word_list_paragraphs never
show it), so it must not trigger the hyperlink-refusal guard -- though
the paragraph is still refused for the real reason: the drawing-holding
run itself is non-text content."""
from docx.oxml.shared import OxmlElement
document = Document()
paragraph = document.add_paragraph("caption ")
anchor = paragraph.add_run()
drawing = OxmlElement("w:drawing")
txbx_content = OxmlElement("w:txbxContent")
inner_p = OxmlElement("w:p")
hyperlink = OxmlElement("w:hyperlink")
inner_run = OxmlElement("w:r")
inner_text = OxmlElement("w:t")
inner_text.text = "Click here"
inner_run.append(inner_text)
hyperlink.append(inner_run)
inner_p.append(hyperlink)
txbx_content.append(inner_p)
drawing.append(txbx_content)
anchor._r.append(drawing)
with pytest.raises(ValueError, match="non-text content"):
word._set_paragraph_text(paragraph, "New caption")
def test_upload_document_rejects_oversized_content(monkeypatch):
document = Document()
monkeypatch.setattr(word, "_MAX_UPLOAD_BYTES", 10)
with pytest.raises(ValueError, match="MB limit"):
word._upload_document(
document,
"Report.docx",
word._EditSnapshot("/drives/drive-1/items/item-1", '"abc"'),
)
def test_validate_docx_archive_bounds_expanded_size(monkeypatch):
"""_read_capped_content only bounds the compressed bytes read off the
wire -- a small, highly compressible archive can still pass that check
and exhaust memory once python-docx unpacks it. This is the separate,
decompressed-size guard that runs before that happens."""
import zipfile
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED) as archive:
archive.writestr("word/document.xml", b"x" * 100)
monkeypatch.setattr(word, "_MAX_DECOMPRESSED_BYTES", 50)
with pytest.raises(ValueError, match="expands beyond"):
word._validate_docx_archive(buffer.getvalue())
def test_validate_docx_archive_bounds_part_count(monkeypatch):
import zipfile
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w") as archive:
archive.writestr("word/document.xml", b"x")
archive.writestr("word/extra.xml", b"x")
monkeypatch.setattr(word, "_MAX_ARCHIVE_PARTS", 1)
with pytest.raises(ValueError, match="too many"):
word._validate_docx_archive(buffer.getvalue())
def test_validate_docx_archive_bounds_xml_elements(monkeypatch):
import zipfile
buffer = io.BytesIO()
xml = b"<root><a/><b/><c/></root>"
with zipfile.ZipFile(buffer, "w") as archive:
archive.writestr("word/document.xml", xml)
monkeypatch.setattr(word, "_MAX_XML_ELEMENTS", 3)
with pytest.raises(ValueError, match="too many XML elements"):
word._validate_docx_archive(buffer.getvalue())
def test_validate_docx_archive_bounds_paragraph_count(monkeypatch):
import zipfile
namespace = "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
xml = f'<w:document xmlns:w="{namespace}"><w:p/><w:p/></w:document>'.encode()
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w") as archive:
archive.writestr("word/document.xml", xml)
monkeypatch.setattr(word, "_MAX_DOCUMENT_PARAGRAPHS", 1)
with pytest.raises(ValueError, match="too many paragraphs"):
word._validate_docx_archive(buffer.getvalue())
def test_validate_docx_archive_bounds_main_body_text(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("sixteen chars!!!"))
monkeypatch.setattr(word, "_MAX_DOCUMENT_TEXT_CHARS", 5)
with pytest.raises(ValueError, match="too much main-body text"):
word._validate_docx_archive(content)
def test_validate_docx_archive_rejects_dtd_entities():
import zipfile
xml = b'<!DOCTYPE root [<!ENTITY x "boom">]><root>&x;</root>'
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w") as archive:
archive.writestr("word/document.xml", xml)
with pytest.raises(ValueError, match="not a valid Word document"):
word._validate_docx_archive(buffer.getvalue())
def test_validate_docx_archive_rejects_non_zip_content():
with pytest.raises(ValueError, match="not a valid Word document"):
word._validate_docx_archive(b"not a zip file")
def test_get_document_text_rejects_zip_bomb(monkeypatch):
"""End-to-end: a document that passes the compressed-size cap but
would expand far beyond a legitimate .docx is still refused before
python-docx ever unpacks it."""
import zipfile
buffer = io.BytesIO()
with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED) as archive:
archive.writestr("word/document.xml", b"x" * 1_000_000)
content = buffer.getvalue()
monkeypatch.setattr(word, "_MAX_DECOMPRESSED_BYTES", 100)
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "error"
assert "expands beyond" in result["message"]
def test_upload_document_sends_if_match_when_etag_given(monkeypatch):
_bypass_edit_checkout(monkeypatch)
mock_request = Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
)
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({"id": "item-1"}))
monkeypatch.setattr(word.requests, "put", mock_put)
word._upload_document(
Document(),
"Report.docx",
_snapshot_for(Document(), '"abc123"'),
)
session_call = mock_request.call_args
assert session_call.kwargs["headers"]["If-Match"] == '"abc123"'
assert session_call.kwargs["url"].endswith(
"/drives/drive-1/items/item-1/createUploadSession"
)
def test_upload_document_holds_checkout_through_final_commit(monkeypatch):
original = _docx_bytes(lambda d: d.add_paragraph("before"))
document = Document(io.BytesIO(original))
document.paragraphs[0].text = "after"
snapshot = word._EditSnapshot(
"/drives/drive-1/items/item-1",
'"before-etag"',
hashlib.sha256(original).hexdigest(),
)
responses = iter(
[
MockResponse({}, status_code=204), # checkout
MockResponse({"eTag": '"checked-out-etag"'}),
MockResponse(content=original),
MockResponse({"uploadUrl": "https://upload.example/session"}),
MockResponse({}, status_code=204), # check in
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(
word.requests,
"put",
Mock(return_value=MockResponse({"id": "item-1"}, status_code=200)),
)
result = word._upload_document(document, "Report.docx", snapshot)
assert result["id"] == "item-1"
urls = [call.kwargs["url"] for call in mock_request.call_args_list]
assert urls[0].endswith("/checkout")
assert urls[3].endswith("/createUploadSession")
assert urls[4].endswith("/checkin") # codespell:ignore checkin
assert mock_request.call_args_list[3].kwargs["headers"]["If-Match"] == (
'"checked-out-etag"'
)
def test_checkout_revalidation_discards_lock_when_content_changed(monkeypatch):
original = _docx_bytes(lambda d: d.add_paragraph("before"))
changed = _docx_bytes(lambda d: d.add_paragraph("someone else changed it"))
snapshot = word._EditSnapshot(
"/drives/drive-1/items/item-1",
'"before"',
hashlib.sha256(original).hexdigest(),
)
responses = iter(
[
MockResponse({}, status_code=204),
MockResponse({"eTag": '"changed"'}),
MockResponse(content=changed),
MockResponse({}, status_code=204),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
with pytest.raises(ValueError, match="changed by someone else"):
word._checkout_edit_snapshot(snapshot, "changed by someone else")
assert mock_request.call_args_list[-1].kwargs["url"].endswith("/discardCheckout")
def test_checkout_retries_locked_item_before_revalidating(monkeypatch):
original = _docx_bytes(lambda d: d.add_paragraph("before"))
snapshot = word._EditSnapshot(
"/drives/drive-1/items/item-1",
'"before"',
hashlib.sha256(original).hexdigest(),
)
responses = iter(
[
MockResponse({"error": {"code": "notAllowed"}}, status_code=423),
MockResponse({"error": {"code": "notAllowed"}}, status_code=423),
MockResponse({}, status_code=204),
MockResponse({"eTag": '"checked-out"'}),
MockResponse(content=original),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
sleep = Mock()
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(word.time, "sleep", sleep)
etag = word._checkout_edit_snapshot(snapshot, "changed by someone else")
assert etag == '"checked-out"'
assert [call.args for call in sleep.call_args_list] == [(1.0,), (2.0,)]
assert (
sum(
call.kwargs["url"].endswith("/checkout")
for call in mock_request.call_args_list
)
== 3
)
@pytest.mark.parametrize(
("status_code", "expected_code"),
[(409, "resource_locked"), (412, "version_conflict")],
)
def test_checkout_conflicts_have_structured_codes(
monkeypatch, status_code, expected_code
):
original = _docx_bytes(lambda d: d.add_paragraph("before"))
snapshot = word._EditSnapshot(
"/drives/drive-1/items/item-1",
'"before"',
hashlib.sha256(original).hexdigest(),
)
monkeypatch.setattr(
word.requests,
"request",
Mock(
return_value=MockResponse(
{"error": {"code": "conflict"}}, status_code=status_code
)
),
)
with pytest.raises(word._WordEditConflict) as exc_info:
word._checkout_edit_snapshot(snapshot, "version conflict")
assert exc_info.value.code == expected_code
def test_append_paragraph_returns_structured_lock_error_after_retries(monkeypatch):
content = _docx_bytes()
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({"error": {"code": "notAllowed"}}, status_code=423),
MockResponse({"error": {"code": "notAllowed"}}, status_code=423),
MockResponse({"error": {"code": "notAllowed"}}, status_code=423),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
sleep = Mock()
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(word.time, "sleep", sleep)
result = json.loads(word.word_append_paragraph("Report.docx", "New paragraph"))
assert result == {
"status": "error",
"message": (
"'Report.docx' is locked for editing; close it in Word or Teams and "
"retry later. This tool edits in place; use onedrive_download_file "
"and onedrive_upload_file with a new path to save a copy"
),
"code": "resource_locked",
"retryable": True,
"suggested_actions": ["close_document_and_retry"],
"lock_owner": None,
}
assert [call.args for call in sleep.call_args_list] == [(1.0,), (2.0,)]
def test_append_paragraph_returns_structured_version_conflict(monkeypatch):
content = _docx_bytes()
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({}, status_code=204),
MockResponse({"eTag": '"checked-out"'}),
MockResponse(content=content),
MockResponse({"error": {"code": "preconditionFailed"}}, status_code=412),
MockResponse({}, status_code=204),
]
)
monkeypatch.setattr(
word.requests, "request", Mock(side_effect=lambda *a, **k: next(responses))
)
result = json.loads(word.word_append_paragraph("Report.docx", "New paragraph"))
assert result["status"] == "error"
assert result["code"] == "version_conflict"
assert result["retryable"] is True
assert result["suggested_actions"] == ["reread_and_retry"]
@pytest.mark.parametrize("locked_phase", ["create-session", "content-put"])
def test_append_paragraph_returns_structured_lock_after_checkout(
monkeypatch, locked_phase
):
content = _docx_bytes()
upload_session_response = (
MockResponse({"error": {"code": "notAllowed"}}, status_code=423)
if locked_phase == "create-session"
else MockResponse({"uploadUrl": "https://upload.example/session"})
)
responses = iter(
[
MockResponse(_edit_metadata()),
MockResponse(content=content),
MockResponse({}, status_code=204),
MockResponse({"eTag": '"checked-out"'}),
MockResponse(content=content),
upload_session_response,
MockResponse({}, status_code=204),
]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
mock_put = Mock(return_value=MockResponse({}, status_code=423))
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(word.requests, "put", mock_put)
result = json.loads(word.word_append_paragraph("Report.docx", "New paragraph"))
assert result["status"] == "error"
assert result["code"] == "resource_locked"
assert result["retryable"] is True
assert "locked for editing" in result["message"]
assert result["suggested_actions"] == ["close_document_and_retry"]
assert mock_request.call_args_list[-1].kwargs["url"].endswith("/discardCheckout")
assert mock_put.call_count == (1 if locked_phase == "content-put" else 0)
def test_check_in_reconciles_when_success_response_is_lost(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("committed"))
responses = iter(
[
requests.ConnectionError("check-in response lost"),
MockResponse(content=content),
MockResponse({"publication": {"level": "published"}}),
]
)
def request(*args, **kwargs):
response = next(responses)
if isinstance(response, Exception):
raise response
return response
monkeypatch.setattr(word.requests, "request", Mock(side_effect=request))
snapshot = word._EditSnapshot(
"/drives/drive-1/items/item-1", '"before"', "generation"
)
word._check_in_edit_snapshot(snapshot, content)
def test_check_in_reconciliation_requires_explicit_published_state(monkeypatch):
"""Matching bytes alone cannot prove a lost-response check-in completed."""
content = _docx_bytes(lambda d: d.add_paragraph("committed"))
responses = iter(
[
requests.ConnectionError("check-in response lost"),
MockResponse(content=content),
MockResponse({}),
]
)
def request(*args, **kwargs):
response = next(responses)
if isinstance(response, Exception):
raise response
return response
monkeypatch.setattr(word.requests, "request", Mock(side_effect=request))
snapshot = word._EditSnapshot(
"/drives/drive-1/items/item-1", '"before"', "generation"
)
with pytest.raises(RuntimeError, match="did not confirm"):
word._check_in_edit_snapshot(snapshot, content)
def test_upload_document_rejects_stale_etag_at_session_creation(monkeypatch):
"""A 412 at createUploadSession means someone else changed the file
since it was downloaded for this edit -- surfaced as a clear conflict,
not the generic upload-failure message."""
_bypass_edit_checkout(monkeypatch)
mock_request = Mock(
return_value=MockResponse({"error": {"code": "..."}}, status_code=412)
)
monkeypatch.setattr(word.requests, "request", mock_request)
with pytest.raises(ValueError, match="changed by someone else"):
word._upload_document(
Document(),
"Report.docx",
_snapshot_for(Document(), '"stale"'),
)
def test_upload_document_rejects_stale_etag_at_content_put(monkeypatch):
"""Graph can also reject the conditional write at the content PUT step
rather than session creation, depending on timing -- both paths must
surface the same clear conflict message."""
_bypass_edit_checkout(monkeypatch)
mock_request = Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
)
monkeypatch.setattr(word.requests, "request", mock_request)
mock_put = Mock(return_value=MockResponse({}, status_code=412))
monkeypatch.setattr(word.requests, "put", mock_put)
with pytest.raises(ValueError, match="changed by someone else"):
word._upload_document(
Document(),
"Report.docx",
_snapshot_for(Document(), '"stale"'),
)
@pytest.mark.parametrize(
"put_outcome",
[
pytest.param(
requests.ConnectionError("connection dropped"), id="connection-dropped"
),
pytest.param(MockResponse({}, status_code=416), id="stale-content-range"),
],
)
def test_upload_document_reconciles_ambiguous_commit(monkeypatch, put_outcome):
"""A dropped response or stale Content-Range can hide a committed upload."""
_bypass_edit_checkout(monkeypatch)
document = Document()
put = Mock(side_effect=[put_outcome])
responses = iter(
[
MockResponse({"uploadUrl": "https://upload.example/session"}),
MockResponse({"id": "item-1", "eTag": '"new"'}),
]
)
def request(*args, **kwargs):
if kwargs["url"].endswith("/content"):
# Echo the committed PUT bytes. Saving the same document again
# can produce different ZIP timestamps despite identical content.
return MockResponse(content=put.call_args.kwargs["data"])
return next(responses)
mock_request = Mock(side_effect=request)
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(word.requests, "put", put)
result = word._upload_document(
document,
"Report.docx",
_snapshot_for(document),
)
assert result["id"] == "item-1"
assert result["eTag"] == '"new"'
put.assert_called_once()
assert mock_request.call_count == 3
def test_upload_document_resumes_from_server_offset(monkeypatch):
_bypass_edit_checkout(monkeypatch)
monkeypatch.setattr(
word.requests,
"request",
Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
),
)
put = Mock(
side_effect=[
MockResponse({"nextExpectedRanges": ["10-"]}, status_code=202),
MockResponse({"id": "item-1"}, status_code=201),
]
)
monkeypatch.setattr(word.requests, "put", put)
word._upload_document(
Document(),
"Report.docx",
_snapshot_for(Document()),
)
assert (
put.call_args_list[1].kwargs["headers"]["Content-Range"].startswith("bytes 10-")
)
assert (
put.call_args_list[1].kwargs["data"]
== put.call_args_list[0].kwargs["data"][10:]
)
def test_upload_document_reports_unresolved_ambiguous_outcome(monkeypatch):
_bypass_edit_checkout(monkeypatch)
monkeypatch.setattr(
word.requests,
"request",
Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
),
)
monkeypatch.setattr(
word.requests, "put", Mock(side_effect=requests.ConnectionError("dropped"))
)
monkeypatch.setattr(word, "_reconcile_uploaded_document", Mock(return_value=None))
sleep = Mock()
monkeypatch.setattr(word.time, "sleep", sleep)
monkeypatch.setattr(
word.requests, "get", Mock(side_effect=requests.ConnectionError("dropped"))
)
with pytest.raises(RuntimeError, match="outcome is unknown.*before retrying"):
word._upload_document(
Document(),
"Report.docx",
_snapshot_for(Document()),
)
assert [call.args[0] for call in sleep.call_args_list] == [1.0, 2.0]
def test_upload_document_backs_off_before_resuming_5xx(monkeypatch):
_bypass_edit_checkout(monkeypatch)
monkeypatch.setattr(
word.requests,
"request",
Mock(
return_value=MockResponse({"uploadUrl": "https://upload.example/session"})
),
)
put = Mock(
side_effect=[
MockResponse({}, status_code=503),
MockResponse({"id": "item-1"}, status_code=201),
]
)
monkeypatch.setattr(word.requests, "put", put)
monkeypatch.setattr(word, "_reconcile_uploaded_document", Mock(return_value=None))
monkeypatch.setattr(
word.requests,
"get",
Mock(return_value=MockResponse({"nextExpectedRanges": ["0-"]})),
)
sleep = Mock()
monkeypatch.setattr(word.time, "sleep", sleep)
result = word._upload_document(
Document(),
"Report.docx",
_snapshot_for(Document()),
)
assert result["id"] == "item-1"
sleep.assert_called_once_with(1.0)
def test_download_document_returns_etag_from_metadata(monkeypatch):
content = _docx_bytes()
responses = iter(
[MockResponse(_edit_metadata('"xyz"')), MockResponse(content=content)]
)
mock_request = Mock(side_effect=lambda *a, **k: next(responses))
monkeypatch.setattr(word.requests, "request", mock_request)
_document, snapshot, generation = word._download_document("Report.docx", None, None)
assert snapshot == word._EditSnapshot(
"/drives/drive-1/items/item-1", '"xyz"', generation
)
assert generation == hashlib.sha256(content).hexdigest()
metadata_call = mock_request.call_args_list[0]
assert metadata_call.kwargs["params"] == {
"$select": "id,eTag,parentReference,publication"
}
content_call = mock_request.call_args_list[1]
assert content_call.kwargs["url"].endswith("/drives/drive-1/items/item-1/content")
def test_download_document_refuses_to_adopt_existing_checkout(monkeypatch):
metadata = _edit_metadata()
metadata["publication"] = {"level": "checkout"}
mock_request = Mock(return_value=MockResponse(metadata))
monkeypatch.setattr(word.requests, "request", mock_request)
with pytest.raises(word._WordEditConflict, match="already checked out") as exc_info:
word._download_document("Report.docx", None, None)
assert exc_info.value.code == "resource_locked"
assert mock_request.call_count == 1
def test_parser_work_budget_is_materially_bounded():
assert word._MAX_DECOMPRESSED_BYTES <= 25_000_000
assert word._MAX_XML_ELEMENTS <= 50_000
assert word._MAX_DOCUMENT_PARAGRAPHS <= 2_000
assert word._MAX_DOCUMENT_TEXT_CHARS <= 400_000
assert word._DEFAULT_PARAGRAPH_PAGE_SIZE == word._MAX_PARAGRAPH_PAGE_SIZE
def test_append_rejects_document_already_at_paragraph_limit(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("at limit"))
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(word, "_MAX_DOCUMENT_PARAGRAPHS", 1)
result = json.loads(word.word_append_paragraph("Report.docx", "one too many"))
assert result["status"] == "error"
assert "paragraph limit" in result["message"]
assert mock_request.call_count == 2
def test_append_rejects_projected_text_growth_before_serializing(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("1234"))
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(word, "_MAX_DOCUMENT_TEXT_CHARS", 5)
result = json.loads(word.word_append_paragraph("Report.docx", "67"))
assert result["status"] == "error"
assert "safe main-body text limit" in result["message"]
assert mock_request.call_count == 2
def test_replace_rejects_excessive_generated_line_breaks_before_upload(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("needle"))
mock_request = _edit_download_mock(content)
monkeypatch.setattr(word.requests, "request", mock_request)
monkeypatch.setattr(word, "_MAX_MUTATION_CONTROL_ELEMENTS", 2)
result = json.loads(word.word_replace_text("Report.docx", "needle", "a\nb\nc\nd"))
assert result["status"] == "error"
assert "too many tabs or line breaks" in result["message"]
assert mock_request.call_count == 0
@pytest.mark.parametrize(
"metadata",
[
{},
{"id": "item-1", "parentReference": {"driveId": "drive-1"}},
{"id": "item-1", "eTag": '"abc"', "parentReference": {}},
],
)
def test_download_document_fails_closed_on_incomplete_edit_identity(
monkeypatch, metadata
):
mock_request = Mock(return_value=MockResponse(metadata))
monkeypatch.setattr(word.requests, "request", mock_request)
with pytest.raises(RuntimeError, match="concurrency-safe"):
word._download_document("Report.docx", None, None)
assert mock_request.call_count == 1
def test_download_document_skips_etag_metadata_when_not_needed(monkeypatch):
"""word_get_document_text/word_list_paragraphs never upload, so they
have no use for the etag -- need_etag=False must skip that extra Graph
round trip entirely rather than fetching and discarding it."""
content = _docx_bytes()
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
_document, etag, _generation = word._download_document(
"Report.docx", None, None, need_etag=False
)
assert etag is None
assert mock_request.call_count == 1
def test_get_document_text_does_not_fetch_etag(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("hello"))
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "success"
# Only the content GET happened -- no separate eTag metadata GET.
assert mock_request.call_count == 1
def test_list_paragraphs_does_not_fetch_etag(monkeypatch):
content = _docx_bytes(lambda d: d.add_paragraph("hello"))
mock_request = Mock(return_value=MockResponse(content=content))
monkeypatch.setattr(word.requests, "request", mock_request)
result = json.loads(word.word_list_paragraphs("Report.docx"))
assert result["status"] == "success"
assert mock_request.call_count == 1
# ---------------------------------------------------------------------------
# error propagation
# ---------------------------------------------------------------------------
def test_missing_auth_token_is_reported(monkeypatch):
monkeypatch.delenv("AUTH_TOKEN", raising=False)
result = json.loads(word.word_get_document_text("Report.docx"))
assert result["status"] == "error"
assert "AUTH_TOKEN" in result["message"]