feat: pluggable HTML themes via Jinja2 template inheritance

.github/workflows/tests.yml

@@ -87,20 +87,20 @@ jobs:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, windows-latest, macos-latest]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "pypy3.10"]
         include:
           - os: ubuntu-latest
             python-version: "3.10"
             with-coverage: true
 
           - os: ubuntu-latest
-            python-version: 3.13
+            python-version: 3.14
             tox-env: devel
           - os: windows-latest
-            python-version: 3.13
+            python-version: 3.14
             tox-env: devel
           - os: macos-latest
-            python-version: 3.13
+            python-version: 3.14
             tox-env: devel
 
     steps:
@@ -163,11 +163,11 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "pypy3.10"]
         include:
           - python-version: "3.10"
             with-coverage: true
-          - python-version: 3.13
+          - python-version: 3.14
             tox-env: devel
 
     steps:
@@ -233,9 +233,9 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.9"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "pypy3.10"]
         include:
-          - python-version: 3.13
+          - python-version: 3.14
             tox-env: devel
 
     steps:

.pre-commit-config.yaml

@@ -48,7 +48,7 @@ repos:
     rev: v3.21.2
     hooks:
       - id: pyupgrade
-        args: [--py39-plus]
+        args: [--py310-plus]
 
   - repo: https://github.com/pre-commit/mirrors-eslint
     rev: v10.0.0-beta.0

docs/user_guide.rst

@@ -51,10 +51,117 @@ The plugin will issue a warning when adding files or links to the standalone rep
 Enhancing reports
 -----------------
 
+Themes
+~~~~~~
+
+pytest-html supports pluggable themes via Jinja2 template inheritance. Two
+built-in themes are included: **classic** (the default, preserving the
+traditional appearance) and **modern** (a card-based dashboard style).
+
+Selecting a theme
+^^^^^^^^^^^^^^^^^
+
+Set the ``html_theme`` option in your pytest configuration:
+
+Using ``pyproject.toml``:
+
+.. code-block:: toml
+
+  [tool.pytest.ini_options]
+  html_theme = "modern"
+
+Using ``pytest.ini``:
+
+.. code-block:: ini
+
+  [pytest]
+  html_theme = modern
+
+Using a local theme directory
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can point to a custom theme directory using ``html_theme_path``. This
+overrides entry point-based theme discovery and does not require packaging:
+
+.. code-block:: toml
+
+  [tool.pytest.ini_options]
+  html_theme_path = "./my_theme"
+
+The theme directory must contain at least a ``layout.jinja2`` file that extends
+the base template:
+
+.. code-block:: jinja
+
+  {% extends "base.jinja2" %}
+
+  {% block header %}
+  <h1 id="title">{{ title }}</h1>
+  <p>Custom header content here</p>
+  {% endblock header %}
+
+Optionally include a ``style.css`` to replace the default stylesheet entirely.
+If no ``style.css`` is present, the classic theme's CSS is used as a fallback.
+
+The ``--css`` flag continues to work and appends additional CSS on top of
+whatever the theme provides.
+
+Creating a theme package
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Theme packages register via the ``pytest_html.themes`` entry point group. The
+entry point value must be a Python package (directory with ``__init__.py``)
+containing the theme resources.
+
+Example package structure:
+
+.. code-block:: text
+
+  pytest-html-dark/
+    src/
+      pytest_html_dark/
+        __init__.py
+        theme/
+          __init__.py
+          layout.jinja2
+          style.css
+    pyproject.toml
+
+Register the entry point in ``pyproject.toml``:
+
+.. code-block:: toml
+
+  [project.entry-points."pytest_html.themes"]
+  dark = "pytest_html_dark.theme"
+
+Users can then select the theme:
+
+.. code-block:: toml
+
+  [tool.pytest.ini_options]
+  html_theme = "dark"
+
+Available template blocks
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The base template (``base.jinja2``) provides the following overridable blocks:
+
+- ``styles`` -- CSS delivery (inline ``<style>`` or ``<link>``)
+- ``head_extra`` -- additional content in ``<head>``
+- ``header`` -- page title and generation info
+- ``environment`` -- environment table and its row template
+- ``summary`` -- run statistics, filters, controls, and row templates
+- ``results_table`` -- the results ``<table>`` with its ``<thead>``
+- ``footer`` -- data container and script include
+
+All template variables (``title``, ``date``, ``time``, ``version``, ``styles``,
+``run_count``, ``outcomes``, ``table_head``, ``test_data``, etc.) are available
+in every block.
+
 Appearance
 ~~~~~~~~~~
 
-Custom CSS (Cascasding Style Sheets) can be passed on the command line using
+Custom CSS (Cascading Style Sheets) can be passed on the command line using
 the :code:`--css` option. These will be applied in the order specified, and can
 be used to change the appearance of the report.
 

package.json

@@ -1,7 +1,9 @@
 {
   "scripts": {
     "build": "npm run build:css && npm run build:jsapp",
-    "build:css": "sass --no-source-map --no-error-css src/layout/css/style.scss src/pytest_html/resources/style.css",
+    "build:css": "npm run build:css:classic && npm run build:css:modern",
+    "build:css:classic": "sass --no-source-map --no-error-css src/layout/css/classic.scss src/pytest_html/resources/classic/style.css",
+    "build:css:modern": "sass --no-source-map --no-error-css src/layout/css/modern.scss src/pytest_html/resources/modern/style.css",
     "build:jsapp": "browserify ./src/pytest_html/scripts/index.js > ./src/pytest_html/resources/app.js",
     "lint": "eslint src/pytest_html/scripts/ testing/",
     "unit": "nyc mocha testing/**/unittest.js --require mock-local-storage",

pyproject.toml

@@ -19,7 +19,7 @@ authors = [
   { name = "Dave Hunt", email = "dhunt@mozilla.com" },
   { name = "Jim Brannlund", email = "jimbrannlund@fastmail.com" },
 ]
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Framework :: Pytest",
@@ -30,7 +30,6 @@ classifiers = [
   "Operating System :: Microsoft :: Windows",
   "Operating System :: POSIX",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
@@ -71,6 +70,8 @@ urls.Source = "https://github.com/pytest-dev/pytest-html"
 urls.Tracker = "https://github.com/pytest-dev/pytest-html/issues"
 entry-points.pytest11.html = "pytest_html.plugin"
 entry-points.pytest11.html_fixtures = "pytest_html.fixtures"
+entry-points."pytest_html.themes".classic = "pytest_html.resources.classic"
+entry-points."pytest_html.themes".modern = "pytest_html.resources.modern"
 
 [tool.hatch.envs.test]
 features = [

src/.gitattributes

@@ -1,3 +1,4 @@
 
 # see https://github.com/github/linguist#generated-code
-pytest_html/resources/style.css    linguist-generated
+pytest_html/resources/classic/style.css    linguist-generated
+pytest_html/resources/modern/style.css     linguist-generated