docx/page-break

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_page_break.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/page-break.docx``.

A minimal document exercising an explicit page break (``w:br
w:type="page"``). Two paragraphs separated by ``doc.add_page_break()``.
Designed to satisfy the assertions in ``features/docx/page-break.json``.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "page-break.docx"


def main() -> int:
    doc = Document()
    doc.add_paragraph("Before page break")
    doc.add_page_break()
    doc.add_paragraph("After page break")
    _OUT.parent.mkdir(parents=True, exist_ok=True)
    doc.save(_OUT, reproducible=True)
    print(_OUT)
    return 0


if __name__ == "__main__":
    raise SystemExit(main())

Manifest (expanded)

{
  "$schema": "../manifest.schema.json",
  "id": "docx/page-break",
  "title": "Page break",
  "format": "docx",
  "category": "page-layout",
  "summary": "Explicit page break between two paragraphs via <w:br w:type=\"page\"/>.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.1.4",
    "element": "w:br",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "A page break is encoded as <w:br w:type=\"page\"/> inside a <w:r>. Without an explicit @w:type the break is a line break, not a page break."
  },
  "fixtures": {
    "machine": "docx/page-break",
    "office": "docx/page-break"
  },
  "generator": {
    "python": "scripts/gen_page_break.py"
  },
  "assertions": [
    {
      "id": "page-break-element-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:br[@w:type='page']",
      "must": "exist",
      "description": "A <w:br> with @w:type='page' must exist in the body."
    },
    {
      "id": "page-break-before-text-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p/w:r/w:t[normalize-space()='Before page break']",
      "must": "exist",
      "description": "The text preceding the page break must be present."
    },
    {
      "id": "page-break-after-text-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p/w:r/w:t[normalize-space()='After page break']",
      "must": "exist",
      "description": "The text following the page break must be present."
    }
  ],
  "render_assertions": [
    {
      "id": "page-break-after-text-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper",
      "must": "match-text",
      "value": "After page break",
      "description": "Sanity: the text following the page break must appear in the rendered DOM."
    },
    {
      "id": "page-break-marker-present",
      "kind": "css_selector",
      "selector": ".docx-wrapper .page-break, .docx-wrapper [data-page-break], .docx-wrapper hr.page-break, .docx-wrapper br.page-break",
      "must": "exist",
      "description": "A renderer-specific page-break marker element (.page-break, [data-page-break], hr.page-break, br.page-break) must be present."
    },
    {
      "id": "page-break-paragraph-pair-present",
      "kind": "css_selector",
      "selector": ".docx-wrapper p:nth-of-type(2)",
      "must": "exist",
      "description": "At least two rendered paragraphs must be present (one before the break, one after). Catches renderers that drop the paragraph after a page break."
    }
  ]
}