feat(template): add test_compat nox session, justfile command, and CI job

template/.github/{% if include_actions %}workflows{% endif %}/tests.yml.jinja

@@ -51,6 +51,36 @@ jobs:
       - name: Run fast tests (excluding slow/integration tests)
         run: nox -s test_fast --python {% raw %}${{ matrix.python-version }}{% endraw %}
 
+  # Compatibility test against oldest supported dependency versions
+  test-compat:
+    name: {% raw %}Compat tests (${{ matrix.pins }}){% endraw %}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        pins: []
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v6
+        with:
+          lfs: true
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          cache-dependency-glob: "pyproject.toml"
+
+      - name: Install nox
+        run: uv tool install nox
+
+      - name: Set up Python {{ min_python_version }}
+        run: uv python install {{ min_python_version }}
+
+      - name: Run compat tests
+        run: nox -s test_compat -- {% raw %}${{ matrix.pins }}{% endraw %}
+
   # Full test suite runs on Ubuntu when PR is not draft or on main branch
   test-full:
     name: {% raw %}Full test suite (Python ${{ matrix.python-version }}){% endraw %}

template/justfile.jinja

@@ -28,6 +28,10 @@ test-cov:
 # Run docstring examples
 test-docstrings:
     uv run pytest --doctest-modules --doctest-continue-on-failure --no-cov src/{{ package_name }}
+
+# Run fast tests after pinning dependency versions (e.g. just test-compat some-package==1.0.0)
+test-compat +PINS='':
+    uvx nox -s test_compat -- {% raw %}{{PINS}}{% endraw %}
 {% if include_examples %}
 # Run marimo example notebook interactively
 example file='':

template/noxfile.py.jinja

@@ -143,6 +143,53 @@ def test_slow(session: nox.Session) -> None:
         "-v",
         *session.posargs,
     )
+
+
+@nox.session(python=PYTHON_VERSIONS, venv_backend="uv")
+def test_compat(session: nox.Session) -> None:
+    """Run fast tests after pinning one or more dependency versions.
+
+    Usage::
+
+        uvx nox -s test_compat -- some-package==1.0.0
+        uvx nox -s test_compat -- some-package==1.0.0 other-package==2.0.0
+
+    Each positional argument must be a pip requirement specifier
+    (e.g. ``package==version``).  If none are given the session runs
+    with the default (latest compatible) versions.
+    """
+    # Install dependencies
+    session.run_install(
+        "uv",
+        "sync",
+        "--no-default-groups",
+        "--group",
+        "tests",
+        env={"UV_PROJECT_ENVIRONMENT": session.virtualenv.location},
+    )
+
+    # Downgrade / pin requested packages
+    if session.posargs:
+        session.run(
+            "uv",
+            "pip",
+            "install",
+            *session.posargs,
+            "--python",
+            session.virtualenv.location + "/bin/python",
+        )
+
+    # Run fast tests
+    session.run(
+        "pytest",
+        "tests",
+        "--no-cov",
+        "-m",
+        "not slow and not integration{% if include_examples %} and not example{% endif %}",
+        "-n",
+        "auto",
+        "-v",
+    )
 {% if include_examples %}
 
 @nox.session(venv_backend="uv")

tests/test_template.py

@@ -284,6 +284,10 @@ def test_github_workflows(copie_session_default):
     assert "test_docstrings:" in content, "test_docstrings job not found in tests workflow"
     assert "nox -s test_docstrings" in content, "test_docstrings nox session not run in CI"
 
+    # Check for test-compat job
+    assert "test-compat:" in content, "test-compat job not found in tests workflow"
+    assert "nox -s test_compat" in content, "test_compat nox session not run in CI"
+
     # Check PR title validation workflow
     pr_title_workflow = result.project_dir / ".github" / "workflows" / "pr-title.yml"
     assert pr_title_workflow.is_file(), "PR title validation workflow not found"

tests/test_template_options.py

@@ -236,6 +236,7 @@ def test_justfile_commands_comprehensive(copie):
         "test-slow:",
         "test-cov:",
         "test-docstrings:",
+        "test-compat ",
         "fix:",  # single command for format, lint, and type check
         "build:",
         "serve:",