ci: test output of examples

.github/workflows/rust.yml

@@ -126,7 +126,7 @@ jobs:
 
 ####################################################################################################
 # STEP 2: INTERMEDIATE
-# ["Test", "Package", "MSRV"]
+# ["Test", "Package", "Example", "MSRV"]
 ####################################################################################################
 
   Test:
@@ -175,6 +175,27 @@ jobs:
       - run: cd ${{ matrix.package }} && cargo nextest run --no-tests=warn
       - run: cd ${{ matrix.package }} && cargo clippy --all-targets -- -D warnings
 
+  Example:
+    needs: ["Rustfmt", "Docs", "Audit", "Book", "Typos", "Jinja2-Assumptions", "DevSkim", "CargoSort"]
+    strategy:
+      matrix:
+        package: [actix-web, axum, poem, rocket, salvo, warp]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - uses: astral-sh/setup-uv@v5
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo build
+        working-directory: examples/${{ matrix.package }}-app
+      - run: uv sync
+        working-directory: examples
+      - run: uv run pytest --verbose tests/test_${{ matrix.package }}.py
+        working-directory: examples
+
   MSRV:
     needs: ["Rustfmt", "Docs", "Audit", "Book", "Typos", "Jinja2-Assumptions", "DevSkim", "CargoSort"]
     runs-on: ubuntu-latest
@@ -191,7 +212,7 @@ jobs:
 ####################################################################################################
 
   Fuzz:
-    needs: ["Test", "Package", "MSRV"]
+    needs: ["Test", "Package", "Example", "MSRV"]
     strategy:
       matrix:
         fuzz_target:
@@ -217,7 +238,7 @@ jobs:
           RUSTFLAGS: '-Ctarget-feature=-crt-static'
 
   Cluster-Fuzz:
-    needs: ["Test", "Package", "MSRV"]
+    needs: ["Test", "Package", "Example", "MSRV"]
     runs-on: ubuntu-latest
     permissions:
       security-events: write

examples/test-examples/.gitignore

@@ -0,0 +1,173 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# PyPI configuration file
+.pypirc
+
+uv.lock

examples/test-examples/.python-version

@@ -0,0 +1 @@
+3.13

examples/test-examples/README.md

@@ -0,0 +1,14 @@
+This folder contains tests that ensure that our example applications generate the expected
+HTML code.
+
+* Ensure that `uv` is installed: <https://docs.astral.sh/uv/#getting-started>,
+* then compile all examples in debug mode,
+* then execute:
+
+    ```bash
+    ./test.sh
+
+    # OR
+
+    uv sync && uv run pytest --verbose
+    ```

examples/test-examples/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "test-examples"
+version = "0.1.0"
+description = "This folder contains tests that ensure that our example applications generate the expected HTML code."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "pexpect >= 4.9, == 4.*",
+    "pytest >= 8.3, == 8.*",
+    "requests >= 2.32, == 2.*",
+]
+license.text = "MIT OR Apache-2.0"
+classifiers = ["Private :: Do Not Upload"]
+
+[build-system]
+requires = ["setuptools >= 75"]
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+pythonpath = ["."]

examples/test-examples/test.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+set -euo pipefail
+
+if ! which uv > /dev/null; then
+    echo 'Please install `uv` first: <https://docs.astral.sh/uv/#getting-started>'
+    exit 1
+fi > /dev/stderr
+
+cd "$(dirname "$0")"
+uv sync
+exec uv run pytest --verbose

examples/test-examples/tests/common.py

@@ -0,0 +1,37 @@
+from functools import wraps
+from pathlib import Path
+from signal import SIGINT
+
+from pexpect.popen_spawn import PopenSpawn
+from requests import Session
+
+
+__all__ = ["with_server_and_session", "read"]
+
+
+def with_server_and_session(name):
+    def inner(fn):
+        @wraps(fn)
+        def wrapped(self):
+            server = PopenSpawn(
+                ["cargo", "+stable", "run"],
+                timeout=30.0,
+                cwd=Path(__file__).parent.parent.parent / f"{name}-app",
+                encoding="UTF-8",
+            )
+            try:
+                with Session() as session:
+                    return fn(self, server, session)
+            finally:
+                server.sendeof()
+                server.kill(SIGINT)
+                server.wait()
+
+        return wrapped
+
+    return inner
+
+
+def read(name):
+    with open(Path(__file__).parent / "expected" / name) as f:
+        return f.read()

examples/test-examples/tests/expected/.gitattributes

@@ -0,0 +1 @@
+*.html -text binary diff

examples/test-examples/tests/expected/404.html

@@ -0,0 +1,73 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+<title>404: Not Found
+        </title>
+
+        <meta http-equiv="expires" content="Sat, 01 Dec 2001 00:00:00 GMT" />
+        <meta http-equiv="cache-control" content="no-cache, no-store, must-revalidate" />
+        <meta http-equiv="pragma" content="no-cache" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta name="robots" content="noindex, nofollow" />
+<style>
+        /*<![CDATA[*/
+html {
+    background-color: #eee;
+    color: #111;
+    font-size: 62.5%;
+    min-height: 100vh;
+    color-scheme: light;
+}
+* {
+    line-height: 1.2em;
+}
+body {
+    background-color: #fff;
+    font-size: 1.8rem;
+    max-width: 40em;
+    margin: 1em auto;
+    padding: 2em;
+}
+h1 { font-size: 2.4rem; }
+h2 { font-size: 2.2rem; }
+h3 { font-size: 2.0rem; }
+a:link, a:visited {
+    color: #36c;
+    text-decoration: none;
+}
+a:active, a:hover, a:focus {
+    text-decoration: underline;
+    text-underline-offset: 0.3em;
+}
+#lang-select {
+    font-size: 80%;
+    width: max-content;
+    margin: 2em 0 0 auto;
+    display: flex;
+    flex-direction: row;
+    flex-wrap: wrap;
+}
+#lang-select li {
+    flex-grow: 1;
+    flex-basis: auto;
+    margin: .25em 0 0 0;
+    padding: 0 1em;
+    text-align: center;
+    list-style-type: none;
+    border-left: 0.1rem solid currentColor;
+}
+#lang-select li:first-of-type {
+    border-left: 0 none transparent;
+}
+#lang-select li:last-of-type {
+    padding-right: 0;
+}
+/*]]>*/
+        </style>
+    </head>
+    <body>
+<h1>404: Not Found
+            </h1><h2><a href="/">Back to the first page.</a></h2>
+</body>
+</html>