pytest-httpchain 0.16.1__tar.gz → 0.17.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/PKG-INFO +1 -1
  2. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/pyproject.toml +3 -2
  3. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/pyproject.toml.orig +4 -2
  4. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/cli.py +4 -4
  5. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/dataflow.py +18 -13
  6. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/scoping.py +152 -7
  7. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/validation/semantic.py +34 -17
  8. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/LICENSE +0 -0
  9. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/README.md +0 -0
  10. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/__init__.py +0 -0
  11. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/body_schema.py +0 -0
  12. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/carrier.py +0 -0
  13. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/constants.py +0 -0
  14. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/errors.py +0 -0
  15. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/factory.py +0 -0
  16. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/har_writer.py +0 -0
  17. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/importers/__init__.py +0 -0
  18. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/importers/builder.py +0 -0
  19. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/importers/curl.py +0 -0
  20. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/importers/har.py +0 -0
  21. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/__init__.py +0 -0
  22. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/equality.py +0 -0
  23. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/exceptions.py +0 -0
  24. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/jsonc.py +0 -0
  25. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/loader.py +0 -0
  26. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/plumbing/__init__.py +0 -0
  27. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/plumbing/circular.py +0 -0
  28. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/plumbing/path.py +0 -0
  29. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/jsonref/plumbing/reference.py +0 -0
  30. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/models/__init__.py +0 -0
  31. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/models/entities.py +0 -0
  32. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/models/types.py +0 -0
  33. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/parallel_stats.py +0 -0
  34. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/plugin.py +0 -0
  35. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/py.typed +0 -0
  36. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/redaction.py +0 -0
  37. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/report_formatter.py +0 -0
  38. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/request_builder.py +0 -0
  39. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/response_steps.py +0 -0
  40. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/schema.py +0 -0
  41. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/templates/__init__.py +0 -0
  42. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/templates/exceptions.py +0 -0
  43. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/templates/expressions.py +0 -0
  44. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/templates/functions.py +0 -0
  45. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/templates/substitution.py +0 -0
  46. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/userfunc.py +0 -0
  47. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/utils.py +0 -0
  48. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/validation/__init__.py +0 -0
  49. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/validation/deep.py +0 -0
  50. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/validation/diagnostics.py +0 -0
  51. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/validation/discovery.py +0 -0
  52. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/validation/loader.py +0 -0
  53. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/validation/validate.py +0 -0
  54. {pytest_httpchain-0.16.1 → pytest_httpchain-0.17.0}/src/pytest_httpchain/warnings.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: pytest-httpchain
3
- Version: 0.16.1
3
+ Version: 0.17.0
4
4
  Summary: pytest plugin for HTTP testing using JSON files
5
5
  Keywords: testing,pytest,httpx,http,api,integration-testing
6
6
  Author: Alexander Eresov
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pytest-httpchain"
3
- version = "0.16.1"
3
+ version = "0.17.0"
4
4
  description = "pytest plugin for HTTP testing using JSON files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.13"
@@ -173,7 +173,8 @@ layers = [
173
173
  "carrier : dataflow : schema : importers",
174
174
  "validation : har_writer : report_formatter : request_builder : response_steps : parallel_stats",
175
175
  "body_schema",
176
- "utils : scoping : redaction",
176
+ "scoping",
177
+ "utils : redaction",
177
178
  "userfunc",
178
179
  "models",
179
180
  "templates : jsonref",
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "pytest-httpchain"
3
- version = "0.16.1"
3
+ version = "0.17.0"
4
4
  description = "pytest plugin for HTTP testing using JSON files"
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.13"
@@ -217,7 +217,9 @@ layers = [
217
217
  "carrier : dataflow : schema : importers",
218
218
  "validation : har_writer : report_formatter : request_builder : response_steps : parallel_stats",
219
219
  "body_schema",
220
- "utils : scoping : redaction",
220
+ # scoping reads stage marks with utils.make_marker (scoping.SkipCause).
221
+ "scoping",
222
+ "utils : redaction",
221
223
  "userfunc",
222
224
  "models",
223
225
  "templates : jsonref",
@@ -216,7 +216,7 @@ def _load_for_inspection(path: Path, depth: int, root_path: Path | None = None)
216
216
 
217
217
  def _render_show_text(path: Path, scenario: Scenario, flow: DataFlow) -> list[str]:
218
218
  # Listed nearest first: a name has several producers when the nearer ones
219
- # have a skip_if (analyze_dataflow), each read only when the nearer skipped.
219
+ # may skip (analyze_dataflow), each read only when the nearer skipped.
220
220
  producers_of: dict[tuple[int, str], list[int]] = {}
221
221
  for edge in flow.edges:
222
222
  for var_name in edge.vars:
@@ -285,9 +285,9 @@ def _to_mermaid(flow: DataFlow, direction: str = "TD") -> str:
285
285
  label = f"{s.index + 1} · {s.name}" if s.name else f"{s.index + 1}"
286
286
  lines.append(f' S{s.index}["{_mermaid_label(label)}"]')
287
287
  for edge in flow.edges:
288
- # Dotted from a stage that may skip (skip_if): the values may come from
289
- # an earlier producer instead (its own edge), or never.
290
- arrow = "-->" if flow.stages[edge.producer].skip_if is False else "-.->"
288
+ # Dotted from a stage that may skip (skip_if, or a skip or xfail mark):
289
+ # the values may come from an earlier producer instead (its own edge), or never.
290
+ arrow = "-.->" if flow.stages[edge.producer].may_skip else "-->"
291
291
  lines.append(f" S{edge.producer} {arrow}|{', '.join(edge.vars)}| S{edge.consumer}")
292
292
  return "\n".join(lines)
293
293
 
@@ -31,8 +31,8 @@ def _consumed(refs: set[str], earlier_saves: frozenset[str], shadows: frozenset[
31
31
  class DataFlowEdge(BaseModel):
32
32
  """A data dependency: ``vars`` saved by stage ``producer`` are referenced by
33
33
  stage ``consumer``. A name has more than one producer when its last writer
34
- before the consumer has a ``skip_if``: one edge from each writer back to the
35
- nearest that never skips (`analyze_dataflow`)."""
34
+ before the consumer may skip: one edge from each writer back to the nearest
35
+ that never skips (`analyze_dataflow`)."""
36
36
 
37
37
  producer: int
38
38
  consumer: int
@@ -40,9 +40,12 @@ class DataFlowEdge(BaseModel):
40
40
 
41
41
 
42
42
  class StageFlow(BaseModel):
43
- """Per-stage data-flow summary. ``skip_if`` is the stage's as declared:
44
- unless it is ``false``, the stage may skip, and a later stage then reads
45
- the value an earlier stage saved under the same name, or finds none."""
43
+ """Per-stage data-flow summary. ``skip_if`` is the stage's as declared.
44
+ ``may_skip`` says whether the stage may end without its saves while the
45
+ chain goes on: a ``skip_if`` other than ``false``, or a ``skip``,
46
+ ``skipif`` or ``xfail`` mark of its own (`scoping.SkipCause`). A later
47
+ stage then reads the value an earlier stage saved under the same name, or
48
+ finds none."""
46
49
 
47
50
  index: int
48
51
  name: str
@@ -51,6 +54,7 @@ class StageFlow(BaseModel):
51
54
  fixtures: list[str]
52
55
  marks: list[str]
53
56
  skip_if: bool | str
57
+ may_skip: bool
54
58
  saves: list[str]
55
59
  consumes: list[str]
56
60
 
@@ -67,13 +71,13 @@ class DataFlow(BaseModel):
67
71
  def _producers(writers: list[int], stages: list[StageFlow]) -> list[int]:
68
72
  """The stages a consumer may read a name from, given its earlier writers in
69
73
  stage order: the last writer, as a later save shadows an earlier one — and
70
- while that writer has a ``skip_if``, the writer before it too, since a
71
- skipped stage leaves the chain running on the earlier value. The walk stops
72
- at the nearest writer that never skips; nearest first."""
74
+ while that writer may skip, the writer before it too, since a skipped
75
+ stage leaves the chain running on the earlier value. The walk stops at the
76
+ nearest writer that never skips; nearest first."""
73
77
  producers: list[int] = []
74
78
  for index in reversed(writers):
75
79
  producers.append(index)
76
- if stages[index].skip_if is False:
80
+ if not stages[index].may_skip:
77
81
  break
78
82
  return producers
79
83
 
@@ -89,10 +93,10 @@ def analyze_dataflow(scenario: Scenario, test_data: dict[str, Any]) -> DataFlow:
89
93
  never saved values.
90
94
 
91
95
  A consumed name comes from its last writer before the consumer. When that
92
- writer has a ``skip_if`` it may have skipped with the chain going on, and
93
- the consumer then reads the writer before it: so the edges run from each
94
- writer back to, and including, the nearest one that never skips — ``graph``
95
- draws those from a stage with a ``skip_if`` dotted.
96
+ writer may skip (a ``skip_if``, or a skip or xfail mark) it may have skipped
97
+ with the chain going on, and the consumer then reads the writer before it:
98
+ so the edges run from each writer back to, and including, the nearest one
99
+ that never skips — ``graph`` draws those from a stage that may skip dotted.
96
100
  """
97
101
  raws = raw_stages(test_data)
98
102
  scopes = stage_scopes(scenario)
@@ -153,6 +157,7 @@ def analyze_dataflow(scenario: Scenario, test_data: dict[str, Any]) -> DataFlow:
153
157
  fixtures=sorted(stage.fixtures),
154
158
  marks=list(stage.marks),
155
159
  skip_if=stage.skip_if,
160
+ may_skip=scope.skip_cause is not None,
156
161
  saves=sorted(scope.saves),
157
162
  consumes=sorted(consumes),
158
163
  )
@@ -32,9 +32,11 @@ time against scenario substitutions only, which is why `StageScopes` exposes
32
32
 
33
33
  An earlier stage's saves are in scope because it passed: one that failed
34
34
  aborted the chain, so only an ``always_run`` stage runs without them. One
35
- that skipped (``skip_if``) leaves the chain healthy, so every later stage runs
36
- without them; `StageScopes.skippable_saves` holds the names only such stages
37
- save, and `StageScopes.when_skipped` the scope without them.
35
+ that skipped leaves the chain healthy, so every later stage runs without them:
36
+ a ``skip_if``, or a ``skip``, ``skipif`` or ``xfail`` mark of the stage's own
37
+ (a `SkipCause`; an expected failure is reported skipped too).
38
+ `StageScopes.skippable_saves` holds the names only such stages save, and
39
+ `StageScopes.when_skipped` the scope without them.
38
40
 
39
41
  The template built-ins (``now()``, ``len()``, ``true``, ...) are in scope in
40
42
  every phase, beneath the user's names: a user name shadows a built-in of the
@@ -43,12 +45,15 @@ built-in (see `extract_template_variables` and `extract_builtin_stand_ins`).
43
45
  """
44
46
 
45
47
  import ast
48
+ import warnings
46
49
  from collections import ChainMap
47
50
  from collections.abc import Iterable, Iterator, Mapping
48
51
  from collections.abc import Set as AbstractSet
49
52
  from dataclasses import dataclass, replace
50
53
  from typing import Any, NamedTuple
51
54
 
55
+ import pytest
56
+
52
57
  from pytest_httpchain.models import (
53
58
  CombinationsParameter,
54
59
  FunctionsSubstitution,
@@ -68,6 +73,7 @@ from pytest_httpchain.models import (
68
73
  normalize_list_input,
69
74
  )
70
75
  from pytest_httpchain.templates import CALL_ONLY_BUILTINS, CONTEXT_HELPERS, TEMPLATE_BUILTINS, TemplatesError, find_templates, parse_expression, template_form
76
+ from pytest_httpchain.utils import make_marker
71
77
 
72
78
  # The name under which response metadata is injected into response-step contexts.
73
79
  RESPONSE_META_NAME = "response"
@@ -567,6 +573,137 @@ def response_step_templates(stage: Stage, raw_response: Any) -> Iterator[tuple[A
567
573
  opaque_save_seen = True
568
574
 
569
575
 
576
+ # --------------------------------------------------------------------------- #
577
+ # Skip causes: which stages may end without their saves while the chain goes on.
578
+ # --------------------------------------------------------------------------- #
579
+
580
+
581
+ @dataclass(frozen=True, slots=True)
582
+ class SkipCause:
583
+ """Why a stage may end without committing its saves while the stages after
584
+ it still run: its ``skip_if``, or a ``skip``, ``skipif`` or ``xfail`` mark of
585
+ its own. pytest reports all of them skipped (an expected failure is a skip
586
+ carrying ``wasxfail``), which `plugin.pytest_runtest_makereport` leaves
587
+ chain-healthy."""
588
+
589
+ mark: str | None
590
+ """The mark as written; ``None`` for the stage's ``skip_if``."""
591
+ fails_as_expected: bool = False
592
+ """An ``xfail`` that runs the stage: its saves are lost when it fails as
593
+ expected, where the others' are lost when it skips."""
594
+ never_called: bool = False
595
+ """pytest never calls the stage: a skip at setup, or an ``xfail(run=False)``
596
+ (unless pytest runs with ``--runxfail``, which ignores xfail marks)."""
597
+
598
+
599
+ # The marks pytest's skipping plugin turns into an outcome.
600
+ _OUTCOME_MARKS = ("skip", "skipif", "xfail")
601
+
602
+
603
+ def _outcome_marks(marks: Iterable[str]) -> list[tuple[str, pytest.Mark]]:
604
+ """The ``skip``, ``skipif`` and ``xfail`` marks among ``marks``, in order,
605
+ each with the mark as written. A mark that does not parse is HTTPCHAIN019's
606
+ to report, and left out."""
607
+ parsed: list[tuple[str, pytest.Mark]] = []
608
+ for mark_str in marks:
609
+ try:
610
+ # Constructing an unregistered mark warns; only the parse matters here.
611
+ with warnings.catch_warnings():
612
+ warnings.simplefilter("ignore")
613
+ mark = make_marker(mark_str).mark
614
+ except Exception:
615
+ continue
616
+ if mark.name in _OUTCOME_MARKS:
617
+ parsed.append((mark_str, mark))
618
+ return parsed
619
+
620
+
621
+ def _conditions_apply(mark: pytest.Mark) -> bool | None:
622
+ """Whether a ``skipif``/``xfail`` mark applies, read as pytest's skipping
623
+ plugin reads it: with no condition it always does, otherwise when a
624
+ condition is true, tried in order. ``None`` is pytest's to decide at run
625
+ time: a string condition is an expression it evaluates, unless the string
626
+ is a literal. A non-string condition needs ``reason=``: without it pytest
627
+ fails the stage, true or not, and a failure aborts the chain, so from there
628
+ on the mark never skips it."""
629
+ conditions = (mark.kwargs["condition"],) if "condition" in mark.kwargs else mark.args
630
+ if not conditions:
631
+ return True
632
+ verdict: bool | None = False
633
+ for condition in conditions:
634
+ if isinstance(condition, str):
635
+ try:
636
+ condition = ast.literal_eval(condition)
637
+ except Exception:
638
+ # Broad on purpose: whatever literal_eval rejects is an
639
+ # expression only pytest can evaluate.
640
+ verdict = None
641
+ continue
642
+ elif mark.kwargs.get("reason") is None:
643
+ return verdict
644
+ if condition:
645
+ return True
646
+ return verdict
647
+
648
+
649
+ def marks_skip_cause(marks: Iterable[str]) -> SkipCause | None:
650
+ """The skip cause the marks on a stage give it, if any, read in the order
651
+ pytest's skipping plugin reads them.
652
+
653
+ At setup every ``skipif`` and ``skip`` is looked at before any ``xfail``:
654
+ one that certainly applies means pytest never calls the stage. Of the
655
+ ``xfail`` marks, the first that applies decides: with ``run=False`` pytest
656
+ never calls the stage, otherwise it runs, and an expected failure discards
657
+ its saves. One with ``raises=`` never fails as expected: a mark can give it
658
+ only a literal, never an exception type, so pytest reports every failure as
659
+ a real one. One pytest never calls is named first, then a ``skip``/``skipif``
660
+ that may apply, then the first ``xfail`` that may end the stage.
661
+ """
662
+ outcome_marks = _outcome_marks(marks)
663
+ may_skip: list[str] = []
664
+ for mark_str, mark in outcome_marks:
665
+ if mark.name == "xfail":
666
+ continue
667
+ applies = True if mark.name == "skip" else _conditions_apply(mark)
668
+ if applies:
669
+ return SkipCause(mark=mark_str, never_called=True)
670
+ if applies is None:
671
+ may_skip.append(mark_str)
672
+ xfail: SkipCause | None = None
673
+ for mark_str, mark in outcome_marks:
674
+ if mark.name != "xfail":
675
+ continue
676
+ applies = _conditions_apply(mark)
677
+ if applies is False:
678
+ continue
679
+ runs = bool(mark.kwargs.get("run", True))
680
+ if xfail is None and (not runs or mark.kwargs.get("raises") is None):
681
+ xfail = SkipCause(mark=mark_str, fails_as_expected=runs, never_called=applies is True and not runs)
682
+ if applies:
683
+ break # this one decides; pytest looks at none after it
684
+ if xfail is not None and xfail.never_called:
685
+ return xfail
686
+ return SkipCause(mark=may_skip[0]) if may_skip else xfail
687
+
688
+
689
+ def _stage_skip_cause(stage: Stage) -> SkipCause | None:
690
+ """Why ``stage`` may end without its saves, or ``None`` when it never does:
691
+ a mark that keeps pytest from calling it, else its ``skip_if``, else a mark
692
+ that may skip it (`marks_skip_cause`).
693
+
694
+ Scenario-level ``marks`` are not read. They apply to every stage, the one
695
+ that reads a save as much as the one that saves it: a scenario-wide
696
+ ``skipif`` skips both or neither, and under a scenario-wide ``xfail`` the
697
+ reader's failure is an expected one too.
698
+ """
699
+ cause = marks_skip_cause(stage.marks)
700
+ if cause is not None and cause.never_called:
701
+ return cause
702
+ if stage.skip_if is not False:
703
+ return SkipCause(mark=None)
704
+ return cause
705
+
706
+
570
707
  # --------------------------------------------------------------------------- #
571
708
  # Static scope model: per-stage, per-phase name availability.
572
709
  # --------------------------------------------------------------------------- #
@@ -635,12 +772,17 @@ class StageScopes:
635
772
  saves: frozenset[str]
636
773
  earlier_saves: frozenset[str]
637
774
  skippable_saves: frozenset[str]
638
- """The ``earlier_saves`` that only stages with a ``skip_if`` save: none
775
+ """The ``earlier_saves`` that only stages with a `SkipCause` save: none
639
776
  is there when those stages skipped."""
777
+ skip_cause: SkipCause | None
778
+ """This stage's own, if it may skip."""
779
+ never_called: bool
780
+ """pytest never calls this stage, by its own marks or the scenario's, which
781
+ apply to every stage (`marks_skip_cause`): it reads nothing."""
640
782
 
641
783
  @property
642
784
  def when_skipped(self) -> "StageScopes":
643
- """This scope as it is when every earlier stage with a ``skip_if``
785
+ """This scope as it is when every earlier stage with a `SkipCause`
644
786
  skipped: without `skippable_saves`. A name in a phase's scope here but
645
787
  not in the same phase of ``when_skipped`` is defined only when such a
646
788
  stage ran."""
@@ -703,7 +845,7 @@ class StageScopes:
703
845
  def stage_scopes(scenario: Scenario) -> list[StageScopes]:
704
846
  """Per-stage scopes in execution order. ``earlier_saves`` accumulates stage
705
847
  by stage, mirroring the runtime commit of saves after a stage passes, and
706
- ``skippable_saves`` holds those of them no stage without a ``skip_if``
848
+ ``skippable_saves`` holds those of them no stage without a `SkipCause`
707
849
  saves (``skip_if: false`` never skips)."""
708
850
  scenario_substitutions = frozenset(substitution_names(scenario.substitutions))
709
851
  scenario_fixtures = frozenset(scenario.fixtures)
@@ -713,6 +855,7 @@ def stage_scopes(scenario: Scenario) -> list[StageScopes]:
713
855
  unskippable_saves: frozenset[str] = frozenset()
714
856
  for stage in scenario.stages:
715
857
  saves = frozenset(saved_in_stage(stage))
858
+ skip_cause = _stage_skip_cause(stage)
716
859
  scopes.append(
717
860
  StageScopes(
718
861
  scenario_substitutions=scenario_substitutions,
@@ -724,10 +867,12 @@ def stage_scopes(scenario: Scenario) -> list[StageScopes]:
724
867
  saves=saves,
725
868
  earlier_saves=earlier_saves,
726
869
  skippable_saves=earlier_saves - unskippable_saves,
870
+ skip_cause=skip_cause,
871
+ never_called=(reader := marks_skip_cause([*stage.marks, *scenario.marks])) is not None and reader.never_called,
727
872
  )
728
873
  )
729
874
  earlier_saves |= saves
730
- if stage.skip_if is False:
875
+ if skip_cause is None:
731
876
  unskippable_saves |= saves
732
877
  return scopes
733
878
 
@@ -34,6 +34,8 @@ from pytest_httpchain.scoping import (
34
34
  SCENARIO_TEMPLATE_FIELDS,
35
35
  DefinedNames,
36
36
  NameUnion,
37
+ SkipCause,
38
+ StageScopes,
37
39
  defined_names,
38
40
  extract_builtin_stand_ins,
39
41
  extract_defined_variables,
@@ -44,7 +46,6 @@ from pytest_httpchain.scoping import (
44
46
  raw_stages,
45
47
  response_step_templates,
46
48
  saved_in_response,
47
- saved_in_stage,
48
49
  stage_scopes,
49
50
  stats_name,
50
51
  substitution_names,
@@ -350,16 +351,23 @@ def _parametrize_rendered_values(raw_parametrize: Any) -> Any:
350
351
  return raw_parametrize
351
352
 
352
353
 
353
- def _skippable_save_diagnostic(scenario: Scenario, i: int, where: str, name: str, location: str) -> Diagnostic:
354
+ def _skip_cause_text(cause: SkipCause) -> str:
355
+ return "skip_if" if cause.mark is None else f"the mark {cause.mark!r}"
356
+
357
+
358
+ def _skippable_save_diagnostic(scenario: Scenario, scopes: list[StageScopes], i: int, where: str, name: str, location: str) -> Diagnostic:
354
359
  """HTTPCHAIN003 for a reference to ``name`` that only earlier stages with a
355
- ``skip_if`` save (`scoping.StageScopes.skippable_saves`): a skip leaves the
356
- chain healthy, so stage ``i`` runs, and finds the name undefined, whenever
357
- those stages skipped. ``where`` is the phase that reads it."""
358
- savers = [f"'{stage.name}'" for stage in scenario.stages[:i] if name in saved_in_stage(stage)]
360
+ `scoping.SkipCause` save (`scoping.StageScopes.skippable_saves`): a skip
361
+ leaves the chain healthy, so stage ``i`` runs, and finds the name undefined,
362
+ whenever those stages skipped. Each saver is named with its cause, its
363
+ ``skip_if`` or the mark as written. ``where`` is the phase that reads it."""
364
+ savers = [(scenario.stages[j].name, cause) for j in range(i) if name in scopes[j].saves and (cause := scopes[j].skip_cause)]
359
365
  if len(savers) == 1:
360
- saved = f"which only stage {savers[0]} saves, and it has skip_if: when it skips"
366
+ [(saver, cause)] = savers
367
+ saved = f"which only stage '{saver}' saves, and it has {_skip_cause_text(cause)}: when it {'fails as expected' if cause.fails_as_expected else 'skips'}"
361
368
  else:
362
- saved = f"which only stages {', '.join(savers)} save, and each has skip_if: when they all skip"
369
+ listed = ", ".join(f"'{saver}' ({_skip_cause_text(cause)})" for saver, cause in savers)
370
+ saved = f"which only stages {listed} save: when none of them saves it"
363
371
  return diag(
364
372
  DiagnosticCode.UNDEFINED_VAR,
365
373
  f"Stage '{scenario.stages[i].name}': {where} references '{name}', {saved}, '{name}' is undefined here — read it with get('{name}', <default>){_builtin_fallback({name})}",
@@ -374,9 +382,12 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any], defined
374
382
  ``scoping.stage_scopes``. An unavailable reference is a FORWARD_REF when the
375
383
  name is saved later (by a later stage, or by a later step of this stage's
376
384
  own response) or defined by a later substitution step, else an UNDEFINED_VAR.
377
- An available one is an UNDEFINED_VAR too where only earlier stages with a
378
- ``skip_if`` save it, and nothing else of that name is in scope: a skipped
379
- stage, unlike a failed one, does not stop the stages after it. A built-in's
385
+ An available one is an UNDEFINED_VAR too where only earlier stages that may
386
+ skip (a ``skip_if``, or a ``skip``, ``skipif`` or ``xfail`` mark) save it,
387
+ and nothing else of that name is in scope: a skipped stage, unlike a failed
388
+ one, does not stop the stages after it. Not in a stage a mark keeps pytest
389
+ from ever calling, which reads nothing, nor past the always_run of one whose
390
+ skip_if is true. A built-in's
380
391
  name the scenario defines too, called or passed as a function where that
381
392
  definition is not in scope, gets the built-in instead: a BUILTIN_STANDS_IN.
382
393
  """
@@ -394,8 +405,14 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any], defined
394
405
  for i, stage in enumerate(scenario.stages):
395
406
  scope = scopes[i]
396
407
  phases = scope.phases()
397
- # The same phases, as they are when every earlier stage with a skip_if skipped.
398
- skipped = phases if scope.when_skipped is scope else scope.when_skipped.phases()
408
+ # The same phases, as they are when every earlier stage that may skip
409
+ # skipped. Unchanged where the stage reads nothing: pytest never calls
410
+ # it, or, past always_run, its skip_if is true (the carrier skips it
411
+ # right after always_run, before anything else renders).
412
+ skipped = phases if scope.when_skipped is scope or scope.never_called else scope.when_skipped.phases()
413
+ skipped_always_run = skipped.always_run
414
+ if stage.skip_if is True:
415
+ skipped = phases
399
416
  raw = raws[i] if i < len(raws) and isinstance(raws[i], dict) else {}
400
417
 
401
418
  parametrize_refs, parametrize_stand_ins = _template_refs(_parametrize_rendered_values(raw.get("parametrize")), defined)
@@ -419,8 +436,8 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any], defined
419
436
  always_run_refs, always_run_stand_ins = _template_refs(raw.get("always_run"), defined)
420
437
  for name in sorted(always_run_refs):
421
438
  if name in phases.always_run:
422
- if name not in skipped.always_run:
423
- yield _skippable_save_diagnostic(scenario, i, "always_run", name, f"stages[{i}].always_run")
439
+ if name not in skipped_always_run:
440
+ yield _skippable_save_diagnostic(scenario, scopes, i, "always_run", name, f"stages[{i}].always_run")
424
441
  continue
425
442
  if name in all_saved:
426
443
  j = first_save_stage[name]
@@ -441,7 +458,7 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any], defined
441
458
  yield _stand_in_diagnostic(f"Stage '{stage.name}': always_run", always_run_stand_ins, f"stages[{i}].always_run")
442
459
 
443
460
  # (phase, template text, names available to it, and those of them
444
- # still available when every earlier stage with a skip_if skipped).
461
+ # still available when every earlier stage that may skip skipped).
445
462
  # Each substitution and response step is checked against its own
446
463
  # scope, not the whole stage's: checking cumulatively is what catches
447
464
  # intra-list forward references. A name referenced by several steps is
@@ -474,7 +491,7 @@ def _dataflow_diagnostics(scenario: Scenario, test_data: dict[str, Any], defined
474
491
  for name in sorted(refs):
475
492
  if name in available:
476
493
  if name not in available_when_skipped:
477
- yield _skippable_save_diagnostic(scenario, i, phase, name, f"stages[{i}].{phase}")
494
+ yield _skippable_save_diagnostic(scenario, scopes, i, phase, name, f"stages[{i}].{phase}")
478
495
  continue
479
496
  if name in scope.stage_substitutions:
480
497
  yield diag(