Add property, contract, and benchmark test layers

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: derek73

pyproject.toml

@@ -44,6 +44,7 @@ dev = [
   "ruff (>=0.15)",
   "pytest-timeout>=2.4.0",
   "pytest-cov>=6",
+  "hypothesis",
 ]
 
 [tool.mypy]

tests/v2/test_benchmark.py

@@ -0,0 +1,15 @@
+"""Perf smoke (core spec §7 tail): parse cost stays v1-comparable
+(microseconds per name). Deliberately generous bound -- guards against
+order-of-magnitude regressions, does not gate normal variance."""
+import time
+
+from nameparser import parse
+
+
+def test_parse_thousand_names_under_a_second() -> None:
+    parse("warm up the default parser cache")
+    start = time.perf_counter()
+    for i in range(1000):
+        parse(f"Dr. Juan{i} de la Vega III")
+    elapsed = time.perf_counter() - start
+    assert elapsed < 1.0, f"1000 parses took {elapsed:.2f}s"

tests/v2/test_contracts.py

@@ -0,0 +1,67 @@
+"""Stable-string contract tests (core spec §7.4): every enum member and
+stable tag has a canonical triggering input, parametrized by iterating
+the registries -- a new member without an entry here fails loudly."""
+import pytest
+
+from nameparser import Parser, Policy, parse
+from nameparser._policy import PatronymicRule
+from nameparser._types import STABLE_TAGS, AmbiguityKind
+
+_AMBIGUITY_TRIGGERS: dict[AmbiguityKind, str | None] = {
+    AmbiguityKind.PARTICLE_OR_GIVEN: "Van Johnson",
+    AmbiguityKind.UNBALANCED_DELIMITER: 'Jon "Nick Smith',
+    AmbiguityKind.COMMA_STRUCTURE: "Smith, John, Extra, Jr.",
+    # no emitter yet -- arrives with locale-pack order detection (2.x)
+    AmbiguityKind.ORDER: None,
+    # no emitter yet -- arrives with suffix/nickname refinement (2.x)
+    AmbiguityKind.SUFFIX_OR_NICKNAME: None,
+}
+
+
+@pytest.mark.parametrize("kind", [
+    pytest.param(k, marks=pytest.mark.xfail(
+        strict=True, reason=f"{k.value}: emitter not yet implemented"))
+    if k in _AMBIGUITY_TRIGGERS and _AMBIGUITY_TRIGGERS[k] is None else k
+    for k in AmbiguityKind
+])
+def test_every_ambiguity_kind_has_a_registered_trigger(
+        kind: AmbiguityKind) -> None:
+    assert kind in _AMBIGUITY_TRIGGERS, (
+        f"new AmbiguityKind {kind.value!r} needs a canonical trigger "
+        f"(or an explicit None with its planned emitter)")
+    trigger = _AMBIGUITY_TRIGGERS[kind]
+    assert trigger is not None  # None triggers are strict-xfail marked
+    kinds = {a.kind for a in parse(trigger).ambiguities}
+    assert kind in kinds
+
+
+_PATRONYMIC_TRIGGERS: dict[PatronymicRule, tuple[str, str]] = {
+    # rule -> (input, expected given)
+    PatronymicRule.EAST_SLAVIC: ("Сидоров Иван Петрович", "Иван"),
+    PatronymicRule.TURKIC: ("Mammadova Aygun Ali kizi", "Aygun"),
+}
+
+
+@pytest.mark.parametrize("rule", list(PatronymicRule))
+def test_every_patronymic_rule_has_a_trigger(rule: PatronymicRule) -> None:
+    assert rule in _PATRONYMIC_TRIGGERS
+    text, expected_given = _PATRONYMIC_TRIGGERS[rule]
+    p = Parser(policy=Policy(patronymic_rules=frozenset({rule})))
+    assert p.parse(text).given == expected_given
+
+
+_TAG_TRIGGERS: dict[str, tuple[str, str]] = {
+    # tag -> (input, token text carrying the tag)
+    "particle": ("Juan de la Vega", "de"),
+    "conjunction": ("Mr. and Mrs. John Smith", "and"),
+    "initial": ("John A. Smith", "A."),
+}
+
+
+@pytest.mark.parametrize("tag", sorted(STABLE_TAGS))
+def test_every_stable_tag_has_a_trigger(tag: str) -> None:
+    assert tag in _TAG_TRIGGERS
+    text, token_text = _TAG_TRIGGERS[tag]
+    pn = parse(text)
+    tagged = next(t for t in pn.tokens if t.text == token_text)
+    assert tag in tagged.tags

tests/v2/test_properties.py

@@ -0,0 +1,52 @@
+"""Property layer (core spec §7.3). Hypothesis is a dev dependency only.
+
+The alphabet is punctuation-heavy on purpose: plain st.text() spreads
+over all of Unicode, so commas, quotes, and delimiters almost never
+appear and the interesting planes go unexercised. derandomize=True
+keeps runs reproducible on shared CI runners -- this layer guards
+against regressions; exploratory fuzzing happened during review.
+"""
+from hypothesis import given, settings
+from hypothesis import strategies as st
+
+from nameparser import parse
+
+_ALPHABET = st.sampled_from(
+    'abcdefgh ABC .,،，\'"()«»‏‏\U0001f600éñßЖ-')
+
+
+@given(st.text(alphabet=_ALPHABET, max_size=200))
+@settings(max_examples=300, deadline=None, derandomize=True)
+def test_parse_never_raises_on_str(text: str) -> None:
+    parse(text)
+
+
+@given(st.text(alphabet=_ALPHABET, max_size=200))
+@settings(max_examples=300, deadline=None, derandomize=True)
+def test_provenance_for_parser_produced_names(text: str) -> None:
+    pn = parse(text)
+    for t in pn.tokens:
+        assert t.span is not None
+        assert t.text == pn.original[t.span.start:t.span.end]
+
+
+@given(st.text(alphabet=_ALPHABET, max_size=100))
+@settings(max_examples=200, deadline=None, derandomize=True)
+def test_capitalized_idempotent(text: str) -> None:
+    once = parse(text).capitalized()
+    assert once.capitalized() == once
+
+
+@given(st.text(alphabet=_ALPHABET, max_size=100))
+@settings(max_examples=200, deadline=None, derandomize=True)
+def test_render_reparse_reaches_fixpoint(text: str) -> None:
+    # render/reparse legitimately takes several rounds to stabilize on
+    # comma-heavy input (each round can re-segment); the invariant is
+    # BOUNDED CONVERGENCE, not one-step idempotence
+    s = str(parse(text))
+    for _ in range(10):
+        nxt = str(parse(s))
+        if nxt == s:
+            break
+        s = nxt
+    assert str(parse(s)) == s, f"no fixpoint within 10 rounds: {s!r}"