docx/run-shading

Metadata

XPath assertions

Render assertions

Generator source

scripts/gen_run_shading.py

#!/usr/bin/env python3
"""Generate ``fixtures/docx/run-shading.docx``.

A minimal document exercising the ``w:shd`` element on ``w:rPr`` — a
run-level background fill. Uses the python-docx fork's high-level
``Font.shading_color`` API (added in 2026.05.0), which emits
``w:shd w:val="clear" w:color="auto" w:fill="RRGGBB"`` on the run.
Satisfies the assertions in ``features/docx/run-shading.json``.
"""

from __future__ import annotations

from pathlib import Path

from docx import Document
from docx.shared import RGBColor

_REPO_ROOT = Path(__file__).resolve().parent.parent
_OUT = _REPO_ROOT / "fixtures" / "docx" / "run-shading.docx"


def main() -> int:
    doc = Document()
    paragraph = doc.add_paragraph()
    run = paragraph.add_run("Run with shading")
    run.font.shading_color = RGBColor(0x00, 0xFF, 0x00)  # green
    _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/run-shading",
  "title": "Run shading",
  "format": "docx",
  "category": "text-formatting",
  "summary": "Apply a solid background (shading) color to a single run via rPr/shd.",
  "spec": {
    "source": "ecma-376-5-part-1",
    "clause": "17.3.2.31",
    "element": "w:shd",
    "rnc_reference": "spec/ecma-376-5/part-1/rnc/WordprocessingML.rnc",
    "xsd_reference": "spec/ecma-376-5/part-1/xsd/wml.xsd",
    "notes": "When <w:shd> is placed on <w:rPr> it shades only the run's text box. w:val is an ST_Shd pattern ('clear' = solid fill), w:color is the pattern foreground (typically 'auto'), and w:fill is the RRGGBB background color. Distinct from <w:highlight>, which uses an enumerated palette; <w:shd> accepts arbitrary hex."
  },
  "fixtures": {
    "machine": "docx/run-shading",
    "office": "docx/run-shading"
  },
  "generator": {
    "python": "scripts/gen_run_shading.py"
  },
  "assertions": [
    {
      "id": "rpr-shd-element-present",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:r[w:t[normalize-space()='Run with shading']]/w:rPr/w:shd",
      "must": "exist",
      "description": "The run must have a <w:shd> child inside <w:rPr>."
    },
    {
      "id": "rpr-shd-fill-is-green",
      "part": "word/document.xml",
      "namespaces": {
        "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main"
      },
      "xpath": "//w:r[w:t[normalize-space()='Run with shading']]/w:rPr/w:shd/@w:fill",
      "must": "equal",
      "value": "00FF00",
      "description": "w:fill must equal '00FF00' (green)."
    }
  ],
  "render_assertions": [
    {
      "id": "run-shading-rendered",
      "kind": "css_selector",
      "selector": ".docx-wrapper [style*='background-color: rgb(0, 255, 0)'], .docx-wrapper [style*='background-color:rgb(0,255,0)'], .docx-wrapper [style*='background-color: #00FF00'], .docx-wrapper [style*='background-color:#00FF00'], .docx-wrapper [style*='background-color: #00ff00'], .docx-wrapper [style*='background-color:#00ff00'], .docx-wrapper [style*='background: #00FF00'], .docx-wrapper [style*='background:#00FF00'], .docx-wrapper [style*='background: #00ff00'], .docx-wrapper [style*='background:#00ff00'], .docx-wrapper [style*='background-color: lime'], .docx-wrapper [style*='background-color:lime']",
      "must": "match-text",
      "value": "Run with shading",
      "description": "A DOM node with a green background must contain the run text."
    },
    {
      "id": "run-shading-visible",
      "kind": "computed_style",
      "selector": ".docx-wrapper span:not(:has(*))",
      "style_property": "background-color",
      "value": "^(rgb\\(0,\\s*255,\\s*0\\)|#00ff00|#00FF00|lime)$",
      "description": "The computed background-color on the run span must resolve to green."
    }
  ]
}