docx/border-around-paragraph

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_border_around_paragraph.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/border-around-paragraph.docx``.

A minimal document exercising the ``w:pBdr`` element — four solid
single-line borders around one paragraph. Uses the python-docx fork's
high-level ``ParagraphFormat.borders`` API (added in 2026.05.0), which
emits ``w:pBdr`` with the correct schema-ordered child edges.
Satisfies the assertions in ``features/docx/border-around-paragraph.json``.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document
from docx.enum.text import WD_BORDER_STYLE
from docx.shared import Pt

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "border-around-paragraph.docx"


def main() -> int:
    doc = Document()
    paragraph = doc.add_paragraph("Bordered paragraph")
    borders = paragraph.paragraph_format.borders
    for side in (borders.top, borders.left, borders.bottom, borders.right):
        side.style = WD_BORDER_STYLE.SINGLE
        side.width = Pt(1)  # 1pt = 8 eighths-of-a-point => w:sz="8"
        side.space = Pt(1)
    _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/border-around-paragraph",
  "title": "Border around paragraph",
  "format": "docx",
  "category": "paragraph-layout",
  "summary": "Draw a single-line border on all four sides of a paragraph via pPr/pBdr.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.1.6",
    "element": "w:pBdr",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "<w:pBdr> on <w:pPr> holds up to six child edges (top, left, bottom, right, between, bar). Each edge element has w:val (ST_Border style), w:sz (eighths of a point), w:space (points of padding), and w:color. Children MUST appear in the schema order top, left, bottom, right, between, bar."
  },
  "fixtures": {
    "machine": "docx/border-around-paragraph",
    "office": "docx/border-around-paragraph"
  },
  "generator": {
    "python": "scripts/gen_border_around_paragraph.py"
  },
  "assertions": [
    {
      "id": "pbdr-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Bordered paragraph']]/w:pPr/w:pBdr",
      "must": "exist",
      "description": "The paragraph must have a <w:pBdr> child inside <w:pPr>."
    },
    {
      "id": "pbdr-top-single",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Bordered paragraph']]/w:pPr/w:pBdr/w:top[@w:val='single']",
      "must": "exist",
      "description": "The top edge must be a single-line border."
    },
    {
      "id": "pbdr-bottom-single",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Bordered paragraph']]/w:pPr/w:pBdr/w:bottom[@w:val='single']",
      "must": "exist",
      "description": "The bottom edge must be a single-line border."
    },
    {
      "id": "pbdr-left-single",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Bordered paragraph']]/w:pPr/w:pBdr/w:left[@w:val='single']",
      "must": "exist",
      "description": "The left edge must be a single-line border."
    },
    {
      "id": "pbdr-right-single",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:p[w:r/w:t[normalize-space()='Bordered paragraph']]/w:pPr/w:pBdr/w:right[@w:val='single']",
      "must": "exist",
      "description": "The right edge must be a single-line border."
    }
  ],
  "render_assertions": [
    {
      "id": "paragraph-border-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper [style*='border'], .docx-wrapper .docx-paragraph-border, .docx-wrapper p, .docx-wrapper div[class*='paragraph']",
      "must": "match-text",
      "value": "Bordered paragraph",
      "description": "A DOM node carrying a border must contain the paragraph text."
    },
    {
      "id": "paragraph-border-visible",
      "kind": "computed_style",
      "selector": ".docx-wrapper p, .docx-wrapper .docx-paragraph, .docx-wrapper div[class*='paragraph']",
      "style_property": "border-top-width",
      "value": "^[1-9]",
      "description": "The computed border-top-width on the paragraph element must be non-zero."
    }
  ]
}