Add expect_parse() helper for SCM property assertions

Replace string-based version assertions with property-based ones
to better distinguish between parsing (SCM extraction) and
formatting (version scheme application) tests.

Key changes:
- Add VersionExpectations TypedDict for type-safe property matching
- Add ScmVersion.matches() method to compare parsed properties
- Add WorkDir.expect_parse() helper for test assertions
- Add mismatches class for detailed error reporting
- Refactor tests to use expect_parse() for parsing validation
- Keep string assertions only for formatting/version scheme tests

This improves test clarity by making explicit what is being tested:
parsing correctness vs formatting behavior.

Note: The linter renamed MissMatches to mismatches following Python
conventions for factory-like classes used in boolean contexts.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: RonnyPfannschmidt

src/setuptools_scm/version.py

@@ -28,6 +28,11 @@
         from typing_extensions import Concatenate
         from typing_extensions import ParamSpec
 
+    if sys.version_info >= (3, 11):
+        from typing import Unpack
+    else:
+        from typing_extensions import Unpack
+
     _P = ParamSpec("_P")
 
 from typing import TypedDict
@@ -51,6 +56,52 @@ class _TagDict(TypedDict):
     suffix: str
 
 
+class VersionExpectations(TypedDict, total=False):
+    """Expected properties for ScmVersion matching."""
+
+    tag: str | _VersionT
+    distance: int
+    dirty: bool
+    node_prefix: str  # Prefix of the node/commit hash
+    branch: str | None
+    exact: bool
+    preformatted: bool
+    node_date: date | None
+    time: datetime | None
+
+
+@dataclasses.dataclass
+class mismatches:
+    """Represents mismatches between expected and actual ScmVersion properties."""
+
+    expected: dict[str, Any]
+    actual: dict[str, Any]
+
+    def __bool__(self) -> bool:
+        """mismatches is falsy to allow `if not version.matches(...)`."""
+        return False
+
+    def __str__(self) -> str:
+        """Format mismatches for error reporting."""
+        lines = []
+        for key, exp_val in self.expected.items():
+            if key == "node_prefix":
+                # Special handling for node prefix matching
+                actual_node = self.actual.get("node")
+                if not actual_node or not actual_node.startswith(exp_val):
+                    lines.append(
+                        f"  node: expected prefix '{exp_val}', got '{actual_node}'"
+                    )
+            else:
+                act_val = self.actual.get(key)
+                if str(exp_val) != str(act_val):
+                    lines.append(f"  {key}: expected {exp_val!r}, got {act_val!r}")
+        return "\n".join(lines)
+
+    def __repr__(self) -> str:
+        return f"mismatches(expected={self.expected!r}, actual={self.actual!r})"
+
+
 def _parse_version_tag(
     tag: str | object, config: _config.Configuration
 ) -> _TagDict | None:
@@ -220,6 +271,58 @@ def format_next_version(
         guessed = guess_next(self, *k, **kw)
         return self.format_with(fmt, guessed=guessed)
 
+    def matches(self, **expectations: Unpack[VersionExpectations]) -> bool | mismatches:
+        """Check if this ScmVersion matches the given expectations.
+
+        Returns True if all specified properties match, or a mismatches
+        object (which is falsy) containing details of what didn't match.
+
+        Args:
+            **expectations: Properties to check, using VersionExpectations TypedDict
+        """
+        # Map expectation keys to ScmVersion attributes
+        attr_map: dict[str, Callable[[], Any]] = {
+            "tag": lambda: str(self.tag),
+            "node_prefix": lambda: self.node,
+            "distance": lambda: self.distance,
+            "dirty": lambda: self.dirty,
+            "branch": lambda: self.branch,
+            "exact": lambda: self.exact,
+            "preformatted": lambda: self.preformatted,
+            "node_date": lambda: self.node_date,
+            "time": lambda: self.time,
+        }
+
+        # Build actual values dict
+        actual: dict[str, Any] = {
+            key: attr_map[key]() for key in expectations if key in attr_map
+        }
+
+        # Process expectations
+        expected = {
+            "tag" if k == "tag" else k: str(v) if k == "tag" else v
+            for k, v in expectations.items()
+        }
+
+        # Check for mismatches
+        def has_mismatch() -> bool:
+            for key, exp_val in expected.items():
+                if key == "node_prefix":
+                    act_val = actual.get("node_prefix")
+                    if not act_val or not act_val.startswith(exp_val):
+                        return True
+                else:
+                    if str(exp_val) != str(actual.get(key)):
+                        return True
+            return False
+
+        if has_mismatch():
+            # Rename node_prefix back to node for actual values in mismatch reporting
+            if "node_prefix" in actual:
+                actual["node"] = actual.pop("node_prefix")
+            return mismatches(expected=expected, actual=actual)
+        return True
+
 
 def _parse_tag(
     tag: _VersionT | str, preformatted: bool, config: _config.Configuration

testing/conftest.py

@@ -5,6 +5,8 @@
 import shutil
 import sys
 
+from datetime import datetime
+from datetime import timezone
 from pathlib import Path
 from types import TracebackType
 from typing import Any
@@ -21,10 +23,18 @@
 
 from .wd_wrapper import WorkDir
 
+# Test time constants: 2009-02-13T23:31:30+00:00
+TEST_SOURCE_DATE = datetime(2009, 2, 13, 23, 31, 30, tzinfo=timezone.utc)
+TEST_SOURCE_DATE_EPOCH = int(TEST_SOURCE_DATE.timestamp())
+TEST_SOURCE_DATE_FORMATTED = "20090213"  # As used in node-and-date local scheme
+TEST_SOURCE_DATE_TIMESTAMP = (
+    "20090213233130"  # As used in node-and-timestamp local scheme
+)
+
 
 def pytest_configure(config: pytest.Config) -> None:
     # 2009-02-13T23:31:30+00:00
-    os.environ["SOURCE_DATE_EPOCH"] = "1234567890"
+    os.environ["SOURCE_DATE_EPOCH"] = str(TEST_SOURCE_DATE_EPOCH)
     os.environ["SETUPTOOLS_SCM_DEBUG"] = "1"
 
 

testing/test_expect_parse.py

@@ -0,0 +1,180 @@
+"""Test the expect_parse and matches functionality."""
+
+from __future__ import annotations
+
+from datetime import date
+from datetime import datetime
+from datetime import timezone
+from pathlib import Path
+
+import pytest
+
+from setuptools_scm import Configuration
+from setuptools_scm.version import ScmVersion
+from setuptools_scm.version import meta
+from setuptools_scm.version import mismatches
+
+from .conftest import TEST_SOURCE_DATE
+from .wd_wrapper import WorkDir
+
+
+def test_scm_version_matches_basic() -> None:
+    """Test the ScmVersion.matches method with various combinations."""
+    c = Configuration()
+
+    # Create test version with all properties set
+    version = meta(
+        "1.2.3",
+        distance=5,
+        dirty=True,
+        node="abc123def456",
+        branch="main",
+        config=c,
+    )
+
+    # Test individual matches
+    assert version.matches(tag="1.2.3")
+    assert version.matches(distance=5)
+    assert version.matches(dirty=True)
+    assert version.matches(branch="main")
+    assert version.matches(exact=False)
+
+    # Test combined matches
+    assert version.matches(tag="1.2.3", distance=5, dirty=True, branch="main")
+
+    # Test node prefix matching
+    assert version.matches(node_prefix="a")
+    assert version.matches(node_prefix="abc")
+    assert version.matches(node_prefix="abc123")
+    assert version.matches(node_prefix="abc123def456")
+
+    # Test mismatches are falsy
+    assert not version.matches(tag="1.2.4")
+    assert not version.matches(node_prefix="xyz")
+    assert not version.matches(distance=10)
+    assert not version.matches(dirty=False)
+
+
+def test_scm_version_matches_exact() -> None:
+    """Test exact matching."""
+    c = Configuration()
+
+    # Exact version
+    exact_version = meta("2.0.0", distance=0, dirty=False, config=c)
+    assert exact_version.matches(exact=True)
+
+    # Non-exact due to distance
+    with_distance = meta("2.0.0", distance=1, dirty=False, config=c)
+    assert not with_distance.matches(exact=True)
+
+    # Non-exact due to dirty
+    dirty_version = meta("2.0.0", distance=0, dirty=True, config=c)
+    assert not dirty_version.matches(exact=True)
+
+
+def test_expect_parse_calls_matches(tmp_path: Path) -> None:
+    """Test that expect_parse correctly parses and calls matches."""
+    wd = WorkDir(tmp_path)
+
+    # Create a mock parse function that returns a predefined ScmVersion
+    c = Configuration()
+    mock_version = meta(
+        "3.0.0",
+        distance=2,
+        dirty=False,
+        node="fedcba987654",
+        branch="develop",
+        config=c,
+    )
+
+    def mock_parse(root: Path, config: Configuration) -> ScmVersion | None:
+        return mock_version
+
+    wd.parse = mock_parse
+
+    # Test successful match
+    wd.expect_parse(tag="3.0.0", distance=2, dirty=False)
+    wd.expect_parse(node_prefix="fed")
+    wd.expect_parse(branch="develop")
+
+    # Test that mismatches raise AssertionError
+    with pytest.raises(AssertionError, match="Version mismatch"):
+        wd.expect_parse(tag="3.0.1")
+
+    with pytest.raises(AssertionError, match="Version mismatch"):
+        wd.expect_parse(dirty=True)
+
+    with pytest.raises(AssertionError, match="Version mismatch"):
+        wd.expect_parse(node_prefix="abc")
+
+
+def test_expect_parse_without_parse_function(tmp_path: Path) -> None:
+    """Test that expect_parse raises error when parse is not configured."""
+    wd = WorkDir(tmp_path)
+
+    with pytest.raises(RuntimeError, match="No SCM configured"):
+        wd.expect_parse(tag="1.0.0")
+
+
+def test_expect_parse_with_none_result(tmp_path: Path) -> None:
+    """Test that expect_parse handles None result from parse."""
+    wd = WorkDir(tmp_path)
+
+    def mock_parse_none(root: Path, config: Configuration) -> ScmVersion | None:
+        return None
+
+    wd.parse = mock_parse_none
+
+    with pytest.raises(AssertionError, match="Failed to parse version"):
+        wd.expect_parse(tag="1.0.0")
+
+
+def test_missmatches_string_formatting() -> None:
+    """Test mismatches string representation for good error messages."""
+    mismatch_obj = mismatches(
+        expected={"tag": "1.0.0", "distance": 0, "dirty": False},
+        actual={"tag": "2.0.0", "distance": 5, "dirty": True},
+    )
+
+    # Test that mismatches is falsy
+    assert not mismatch_obj
+
+    # Test string representation
+    str_repr = str(mismatch_obj)
+    assert "tag: expected '1.0.0', got '2.0.0'" in str_repr
+    assert "distance: expected 0, got 5" in str_repr
+    assert "dirty: expected False, got True" in str_repr
+
+
+def test_missmatches_node_prefix_formatting() -> None:
+    """Test mismatches formatting for node prefix mismatches."""
+    mismatch_obj = mismatches(
+        expected={"node_prefix": "abc"},
+        actual={"node": "def123456"},
+    )
+
+    str_repr = str(mismatch_obj)
+    assert "node: expected prefix 'abc', got 'def123456'" in str_repr
+
+
+def test_scm_version_matches_datetime() -> None:
+    """Test that ScmVersion.matches works with datetime fields."""
+    c = Configuration()
+
+    # Create version with specific datetime
+    version = meta(
+        "1.0.0",
+        distance=0,
+        dirty=False,
+        node_date=date(2023, 6, 15),
+        time=TEST_SOURCE_DATE,
+        config=c,
+    )
+
+    # Test date matching
+    assert version.matches(node_date=date(2023, 6, 15))
+    assert not version.matches(node_date=date(2023, 6, 16))
+
+    # Test time matching
+    assert version.matches(time=TEST_SOURCE_DATE)
+    assert not version.matches(time=datetime(2023, 1, 1, tzinfo=timezone.utc))