pytest-given 0.1.0__py3-none-any.whl

pytest_given/lint/runtime_rules.py

@@ -0,0 +1,212 @@
+"""Runtime-surface rules: pure inspection of the recorded report model, no
+source access needed."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+from ..model import (
+    ActivityTermRef,
+    Glossary,
+    Narration,
+    NarrationTermRef,
+    NodeId,
+    Phase,
+    Scenario,
+    Step,
+    Story,
+    TermId,
+    case_suffix,
+    id_derive,
+    node_base,
+)
+from .base import RULES_BY_ID, Finding, RuleId, iter_steps, location_suffix
+
+
+def run_runtime_rules(
+    grouped: list[Scenario],
+    per_case: list[Scenario],
+    glossary: Glossary | None,
+    stories: list[Story],
+) -> list[Finding]:
+    """Run the runtime-surface rules over the recorded report model.
+
+    `missing-phase` and the glossary rules evaluate the grouped scenario list
+    (one evaluation per logical scenario); `divergent-case-structure` needs
+    the pre-grouping per-case list — the only place per-case step structure
+    exists, since grouping collapses every case onto case 1's tree.
+    """
+    findings: list[Finding] = []
+    findings.extend(_missing_phase_findings(grouped))
+    findings.extend(_divergent_case_findings(per_case))
+    if glossary is not None:
+        findings.extend(_tag_shadows_term_findings(grouped, glossary))
+        findings.extend(_dead_term_findings(grouped, glossary, stories))
+    return findings
+
+
+# Canonical Given/When/Then order, used both to test completeness and to
+# report missing phases in reading order rather than alphabetically.
+_PHASE_ORDER: tuple[Phase, ...] = ('given', 'when', 'then')
+
+# A step tree reduced to nested phase tuples — narration text and values
+# ignored. Two cases with equal signatures render truthfully in the merged
+# parameter-table view.
+type _StepSignature = tuple[tuple[Phase, _StepSignature], ...]
+
+
+def _missing_phase_findings(grouped: list[Scenario]) -> list[Finding]:
+    """Rule `missing-phase`: a passed scenario lacks a Given, When, or Then.
+
+    Non-passed scenarios are skipped — a skipped one records no steps and a
+    failed one may be missing a phase only because it aborted mid-body.
+    """
+    findings: list[Finding] = []
+    for scenario in grouped:
+        if scenario.status != 'passed':
+            continue
+        present = {step.phase for step in iter_steps(scenario.steps)}
+        missing = [phase for phase in _PHASE_ORDER if phase not in present]
+        if missing:
+            findings.append(
+                _scenario_finding(
+                    RuleId('missing-phase'),
+                    scenario,
+                    f'missing: {", ".join(missing)}',
+                )
+            )
+    return findings
+
+
+def _divergent_case_findings(per_case: list[Scenario]) -> list[Finding]:
+    """Rule `divergent-case-structure`: a parametrize case records a
+    different step structure than case 1.
+
+    Groups the pre-grouping cases by node-id base. Non-passed cases are
+    exempt (skipped cases record no steps; failed cases abort mid-tree), so
+    the baseline is the first passed case. One finding per scenario, naming
+    the diverging case ids.
+    """
+    groups: dict[str, list[Scenario]] = {}
+    for scenario in per_case:
+        if '[' in scenario.id:
+            groups.setdefault(node_base(scenario.id), []).append(scenario)
+    findings: list[Finding] = []
+    for base, cases in groups.items():
+        passed = [case for case in cases if case.status == 'passed']
+        if len(passed) < 2:
+            continue
+        baseline = _structure_signature(passed[0].steps)
+        diverging = [
+            case_suffix(case.id)
+            for case in passed[1:]
+            if _structure_signature(case.steps) != baseline
+        ]
+        if diverging:
+            findings.append(
+                Finding(
+                    rule=RuleId('divergent-case-structure'),
+                    severity=RULES_BY_ID[RuleId('divergent-case-structure')].default,
+                    subject=base,
+                    node_id=NodeId(base),
+                    location=passed[0].source,
+                    message=(
+                        f'cases {", ".join(diverging)} record a different step '
+                        f'structure than case {case_suffix(passed[0].id)}'
+                    ),
+                )
+            )
+    return findings
+
+
+def _structure_signature(steps: list[Step]) -> _StepSignature:
+    return tuple((step.phase, _structure_signature(step.children)) for step in steps)
+
+
+def _tag_shadows_term_findings(
+    grouped: list[Scenario], glossary: Glossary
+) -> list[Finding]:
+    """Rule `tag-shadows-term`: a scenario tag duplicates a glossary term.
+
+    One finding per unique tag (subject = tag slug) — the fix is renaming the
+    tag once, and per-scenario findings would be pure repetition.
+    """
+    counts: dict[TermId, tuple[str, NodeId, int]] = {}
+    for scenario in grouped:
+        for tag in scenario.tags:
+            slug = id_derive(tag)
+            if glossary.get(slug) is None:
+                continue
+            if slug in counts:
+                first_tag, first_id, count = counts[slug]
+                counts[slug] = (first_tag, first_id, count + 1)
+            else:
+                counts[slug] = (tag, scenario.id, 1)
+    findings: list[Finding] = []
+    for slug, (tag, node_id, count) in counts.items():
+        term = glossary.get(slug)
+        assert term is not None
+        noun = 'scenario' if count == 1 else 'scenarios'
+        findings.append(
+            Finding(
+                rule=RuleId('tag-shadows-term'),
+                severity=RULES_BY_ID[RuleId('tag-shadows-term')].default,
+                subject=slug,
+                node_id=node_id,
+                location=None,
+                message=(
+                    f'tag {tag!r} duplicates glossary term {term.canonical!r} '
+                    f'({count} {noun}, e.g. {node_id})'
+                ),
+            )
+        )
+    return findings
+
+
+def _dead_term_findings(
+    grouped: list[Scenario], glossary: Glossary, stories: list[Story]
+) -> list[Finding]:
+    """Rule `dead-term`: a glossary term is referenced by no step and no
+    story. Default `off`: for a file-backed glossary, unreferenced terms are
+    often intentionally present (documented behaviour)."""
+    referenced: set[TermId] = set()
+    for scenario in grouped:
+        for narration in _iter_narrations(scenario):
+            for part in narration.parts:
+                if isinstance(part, NarrationTermRef):
+                    referenced.add(part.term_id)
+    for story in stories:
+        for activity in story.activities:
+            for path in activity.paths:
+                for ref in path.parts:
+                    if isinstance(ref, ActivityTermRef):
+                        referenced.add(ref.term_id)
+    return [
+        Finding(
+            rule=RuleId('dead-term'),
+            severity=RULES_BY_ID[RuleId('dead-term')].default,
+            subject=term.id,
+            node_id=None,
+            location=term.source,
+            message=f'term {term.canonical!r} is referenced by no step and no story',
+        )
+        for term in glossary.terms
+        if term.id not in referenced
+    ]
+
+
+def _iter_narrations(scenario: Scenario) -> Iterator[Narration]:
+    yield scenario.narration
+    for step in iter_steps(scenario.steps):
+        yield step.narration
+
+
+def _scenario_finding(rule: RuleId, scenario: Scenario, text: str) -> Finding:
+    return Finding(
+        rule=rule,
+        severity=RULES_BY_ID[rule].default,
+        subject=scenario.id,
+        node_id=scenario.id,
+        location=scenario.source,
+        message=f'{text}{location_suffix(scenario.source)}',
+    )

pytest_given/model/__init__.py

@@ -0,0 +1,84 @@
+from .errors import PytestGivenError
+from .ids import case_suffix, id_derive, node_base
+from .schema import (
+    Activity,
+    ActivityId,
+    ActivityPart,
+    ActivityPath,
+    ActivityTermRef,
+    ActivityWord,
+    Attachment,
+    ContentType,
+    ErrorInfo,
+    FixtureRecording,
+    Glossary,
+    GlossaryTerm,
+    Metadata,
+    Narration,
+    NarrationLiteral,
+    NarrationPart,
+    NarrationPlaceholder,
+    NarrationTermRef,
+    NarrationValue,
+    NodeId,
+    ParameterCase,
+    ParameterTable,
+    ParamInfo,
+    ParamSpec,
+    ParamValue,
+    Phase,
+    RecordingState,
+    ReportData,
+    Scenario,
+    SourceLocation,
+    Step,
+    Story,
+    StoryId,
+    TermId,
+    TracebackFrame,
+)
+from .serde import report_from_dict, report_to_dict
+
+__all__ = [
+    'Activity',
+    'ActivityId',
+    'ActivityPart',
+    'ActivityPath',
+    'ActivityTermRef',
+    'ActivityWord',
+    'Attachment',
+    'ContentType',
+    'ErrorInfo',
+    'FixtureRecording',
+    'Glossary',
+    'GlossaryTerm',
+    'Metadata',
+    'Narration',
+    'NarrationLiteral',
+    'NarrationPart',
+    'NarrationPlaceholder',
+    'NarrationTermRef',
+    'NarrationValue',
+    'NodeId',
+    'ParamInfo',
+    'ParamSpec',
+    'ParamValue',
+    'ParameterCase',
+    'ParameterTable',
+    'Phase',
+    'PytestGivenError',
+    'RecordingState',
+    'ReportData',
+    'Scenario',
+    'SourceLocation',
+    'Step',
+    'Story',
+    'StoryId',
+    'TermId',
+    'TracebackFrame',
+    'case_suffix',
+    'id_derive',
+    'node_base',
+    'report_from_dict',
+    'report_to_dict',
+]

pytest_given/model/errors.py

@@ -0,0 +1,2 @@
+class PytestGivenError(RuntimeError):
+    """Raised when given/when/then/attach is called in an invalid lifecycle context."""

pytest_given/model/ids.py

@@ -0,0 +1,32 @@
+"""Pure-function id derivation, shared by capture and report layers."""
+
+import re
+
+from .errors import PytestGivenError
+from .schema import TermId
+
+_NON_ALNUM = re.compile(r'[^a-z0-9]+')
+
+
+def id_derive(name: str) -> TermId:
+    slug = _NON_ALNUM.sub('-', name.lower()).strip('-')
+    if not slug:
+        raise PytestGivenError(
+            f'derived id is empty for {name!r}; provide a name with at least '
+            f'one ASCII alphanumeric character.'
+        )
+    return TermId(slug)
+
+
+def node_base(node_id: str) -> str:
+    """A node id (or a bare function segment) without its parametrize tail:
+    ``'f.py::t[1-2]' -> 'f.py::t'``, ``'t[1-2]' -> 't'``. Two cases of one
+    parametrized function share this; two different functions never do."""
+    return node_id.split('[', 1)[0]
+
+
+def case_suffix(node_id: str) -> str:
+    """The parametrize tail of a node id, brackets included, or ``''`` when it
+    has none: ``'f.py::t[1-2]' -> '[1-2]'``, ``'f.py::t' -> ''``."""
+    _, bracket, rest = node_id.partition('[')
+    return f'{bracket}{rest}'

pytest_given/model/schema.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, NamedTuple, NewType
+
+if TYPE_CHECKING:
+    from ..capture.glossary import Actor, DeferredTermHandle, Verb, WorkObject
+
+
+@dataclass(frozen=True, kw_only=True)
+class NarrationLiteral:
+    value: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class NarrationValue:
+    """A t-string interpolation — value already known at construction time."""
+
+    rendered: str
+    expression: str
+    format_spec: str = ''
+    conversion: str | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class NarrationPlaceholder:
+    """A deferred placeholder — resolved at render time from a per-case mapping."""
+
+    name: str
+    format_spec: str = ''
+    conversion: str | None = None
+
+
+# Pytest node ID, e.g. "tests/test_billing.py::test_buy_coffee[1-2-3]"
+NodeId = NewType('NodeId', str)
+
+TermId = NewType('TermId', str)
+ActivityId = NewType('ActivityId', int)
+StoryId = NewType('StoryId', str)
+
+
+@dataclass(frozen=True, kw_only=True)
+class NarrationTermRef:
+    """Reference to a glossary term — kind resolved via glossary[term_id].kind."""
+
+    term_id: TermId
+    display: str
+    expression: str = ''
+    param_column: str | None = None
+
+
+type NarrationPart = (
+    NarrationLiteral | NarrationValue | NarrationPlaceholder | NarrationTermRef
+)
+
+
+@dataclass(frozen=True)
+class Narration:
+    """The text of a step or scenario, plus optional structured parts.
+
+    `text` is the rendered string for display. `parts` is empty for plain-string
+    inputs; non-empty when the source was a t-string or a `Template`, in which
+    case the parts reconstruct `text` and carry per-part highlighting metadata.
+    """
+
+    text: str
+    parts: list[NarrationPart] = field(default_factory=list)
+
+
+@dataclass(frozen=True, kw_only=True)
+class GlossaryTerm:
+    id: TermId
+    kind: Literal['actor', 'object', 'verb'] | None
+    canonical: str
+    definition: str | None = None
+    source: SourceLocation | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class ActivityTermRef:
+    """Reference to a glossary term in an activity path. Kind resolved via
+    glossary[term_id].kind — mirrors NarrationTermRef. Used for both
+    code-defined handles and file-glossary handles (whose kind may be
+    inferred post-collection)."""
+
+    term_id: TermId
+    display: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class ActivityWord:
+    """Bare-string connective (preposition, article, etc.). Carries no kind."""
+
+    text: str
+
+
+type ActivityPart = ActivityTermRef | ActivityWord
+
+
+@dataclass(frozen=True, kw_only=True)
+class ActivityPath:
+    parts: tuple[ActivityPart, ...]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Activity:
+    id: ActivityId
+    paths: tuple[ActivityPath, ...]
+
+
+@dataclass(frozen=True, kw_only=True)
+class Story:
+    id: StoryId
+    title: str
+    activities: tuple[Activity, ...]
+    source: SourceLocation | None = None
+    _by_id: dict[ActivityId, Activity] = field(
+        init=False, repr=False, compare=False, default_factory=dict
+    )
+
+    def __post_init__(self) -> None:
+        index: dict[ActivityId, Activity] = {}
+        for activity in self.activities:
+            index[activity.id] = activity
+        object.__setattr__(self, '_by_id', index)
+
+    def __getitem__(self, key: ActivityId) -> Activity:
+        return self._by_id[key]
+
+    def get(self, key: ActivityId) -> Activity | None:
+        return self._by_id.get(key)
+
+
+@dataclass
+class Glossary:
+    """Mutable container of glossary terms with an id-keyed index.
+
+    The user-facing registration methods (`actor` / `work_object` / `verb`)
+    live in `pytest_given.capture.glossary`; this class only owns storage
+    and atomic write-through. `_register` is the low-level primitive both
+    those methods and the deserializer call.
+    """
+
+    terms: list[GlossaryTerm] = field(default_factory=list)
+    _by_id: dict[TermId, GlossaryTerm] = field(
+        init=False, repr=False, compare=False, default_factory=dict
+    )
+
+    def __post_init__(self) -> None:
+        for term in self.terms:
+            self._by_id[term.id] = term
+
+    def get(self, key: TermId) -> GlossaryTerm | None:
+        return self._by_id.get(key)
+
+    def _register(self, term: GlossaryTerm) -> None:
+        if term.id in self._by_id:
+            raise ValueError(f'term id {term.id!r} already registered')
+        self.terms.append(term)
+        self._by_id[term.id] = term
+
+    if TYPE_CHECKING:
+
+        def __call__(
+            self, name: str, definition: str | None = None
+        ) -> DeferredTermHandle: ...
+        def __getitem__(self, name: str) -> DeferredTermHandle: ...
+        def actor(self, name: str, definition: str | None = None) -> Actor: ...
+        def work_object(
+            self, name: str, definition: str | None = None
+        ) -> WorkObject: ...
+        def verb(self, name: str, definition: str | None = None) -> Verb: ...
+
+
+# Step phase
+type Phase = Literal['given', 'when', 'then']
+
+# Lifecycle state of the collector — determines where push_step/attach route.
+type RecordingState = Literal['idle', 'test', 'fixture_setup', 'fixture_teardown']
+
+# A @pytest.mark.parametrize value as captured for the report: JSON primitives
+# pass through; anything else (dates, objects) is captured as its str(), since
+# parametrize values only feed display and the JSON sink must serialize them.
+type ParamValue = str | int | float | bool | None
+
+
+class ParamSpec(NamedTuple):
+    """Parameter names and values for a single parametrized test run."""
+
+    names: list[str]
+    values: list[ParamValue]
+
+
+# Maps node IDs to their parameter specification
+type ParamInfo = dict[NodeId, ParamSpec]
+
+
+type ContentType = Literal['text', 'json']
+
+
+@dataclass
+class Attachment:
+    label: str
+    content: str
+    content_type: ContentType = 'text'
+
+
+@dataclass(frozen=True)
+class SourceLocation:
+    """A file/line pointer to a scenario's test function.
+
+    `relpath` is POSIX-normalized and relative to pytest's rootdir; `line` is
+    1-indexed. Stored on Scenario; rootdir is never serialized to avoid
+    leaking local paths.
+    """
+
+    relpath: str
+    line: int
+
+
+@dataclass(frozen=True)
+class TracebackFrame:
+    """One frame from a parsed pytest short-style traceback.
+
+    `path` is POSIX-normalized (backslashes converted) so renderer logic
+    doesn't need per-OS branches. `code` may span multiple lines (caret
+    rows, multi-line statements); newlines are preserved verbatim.
+    `is_internal` flags pluggy/_pytest/decorator-wrapper frames that the
+    UI hides by default.
+    """
+
+    path: str
+    lineno: int
+    func: str
+    code: str
+    is_internal: bool
+
+
+@dataclass
+class ErrorInfo:
+    message: str
+    frames: list[TracebackFrame] = field(default_factory=list)
+    error_tail: str | None = None
+
+
+@dataclass
+class Step:
+    phase: Phase
+    narration: Narration
+    status: str = 'passed'
+    children: list[Step] = field(default_factory=list)
+    attachments: list[Attachment] = field(default_factory=list)
+    error: ErrorInfo | None = None
+    activity_ids: tuple[ActivityId, ...] = ()
+    fixture_name: str | None = None
+    # Anchor of the step's body for the narration lint; captured only when
+    # lint is enabled, and never serialized so report artifacts stay
+    # byte-identical either way.
+    source: SourceLocation | None = field(
+        default=None, metadata={'serde_exclude': True}
+    )
+
+
+@dataclass
+class FixtureRecording:
+    """A captured subtree of steps/attachments for one fixture instance.
+
+    `root` is the labeled step from @given/@when/@then on the fixture; its
+    `children` accumulate as the fixture body runs. `stack` mirrors the
+    collector's step stack while the recording is active, so nested
+    `with given(...)` inside the body works.
+    """
+
+    root: Step
+    stack: list[Step] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if not self.stack:
+            self.stack.append(self.root)
+
+
+@dataclass
+class ParameterCase:
+    values: list[Any]
+    status: str = 'passed'
+    error: ErrorInfo | None = None
+
+
+@dataclass
+class ParameterTable:
+    names: list[str]
+    cases: list[ParameterCase] = field(default_factory=list)
+
+
+@dataclass
+class Scenario:
+    id: NodeId
+    narration: Narration
+    module: str
+    tags: list[str] = field(default_factory=list)
+    status: str = 'passed'
+    duration_ms: int = 0
+    steps: list[Step] = field(default_factory=list)
+    parameters: ParameterTable | None = None
+    error: ErrorInfo | None = None
+    skip_reason: str | None = None
+    source: SourceLocation | None = None
+    story_id: StoryId | None = None
+    activity_ids: tuple[ActivityId, ...] = ()
+
+
+@dataclass
+class Metadata:
+    project: str
+    timestamp: str
+    pytest_version: str
+    plugin_version: str
+    commit_sha: str | None = None
+
+
+@dataclass
+class ReportData:
+    metadata: Metadata
+    scenarios: list[Scenario] = field(default_factory=list)
+    glossary: Glossary | None = None
+    stories: list[Story] = field(default_factory=list)