behave-priority 1.2.0__tar.gz → 1.2.1__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 (58) hide show
  1. {behave_priority-1.2.0 → behave_priority-1.2.1}/PKG-INFO +8 -8
  2. {behave_priority-1.2.0 → behave_priority-1.2.1}/README.md +7 -7
  3. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/__init__.py +1 -1
  4. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/config.py +39 -9
  5. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/hooks.py +55 -19
  6. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/parallel.py +143 -20
  7. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/parser.py +72 -12
  8. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/report.py +33 -11
  9. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/sorter.py +21 -15
  10. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/index.rst +1 -1
  11. {behave_priority-1.2.0 → behave_priority-1.2.1}/pyproject.toml +1 -5
  12. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/test_config.py +64 -0
  13. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/test_hooks.py +216 -2
  14. behave_priority-1.2.1/tests/unit/test_parallel.py +438 -0
  15. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/test_parser.py +52 -0
  16. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/test_report.py +162 -0
  17. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/test_smoke.py +1 -1
  18. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/test_sorter.py +35 -0
  19. behave_priority-1.2.0/tests/unit/test_parallel.py +0 -191
  20. {behave_priority-1.2.0 → behave_priority-1.2.1}/.gitignore +0 -0
  21. {behave_priority-1.2.0 → behave_priority-1.2.1}/LICENSE +0 -0
  22. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/exceptions.py +0 -0
  23. {behave_priority-1.2.0 → behave_priority-1.2.1}/behave_priority/py.typed +0 -0
  24. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/conf.py +0 -0
  25. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/guides/configuration.rst +0 -0
  26. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/guides/gherkin_v6.rst +0 -0
  27. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/guides/integration.rst +0 -0
  28. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/guides/reports.rst +0 -0
  29. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/modules/config.rst +0 -0
  30. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/modules/exceptions.rst +0 -0
  31. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/modules/hooks.rst +0 -0
  32. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/modules/parallel.rst +0 -0
  33. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/modules/parser.rst +0 -0
  34. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/modules/report.rst +0 -0
  35. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/modules/sorter.rst +0 -0
  36. {behave_priority-1.2.0 → behave_priority-1.2.1}/docs/requirements.txt +0 -0
  37. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/__init__.py +0 -0
  38. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/conftest.py +0 -0
  39. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/__init__.py +0 -0
  40. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/environment.py +0 -0
  41. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/features/critical.feature +0 -0
  42. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/features/failfast.feature +0 -0
  43. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/features/feature_priority.feature +0 -0
  44. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/features/outline.feature +0 -0
  45. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/features/priority_order.feature +0 -0
  46. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/features/rule_priority.feature +0 -0
  47. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/features/smoke_tag.feature +0 -0
  48. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/steps/steps.py +0 -0
  49. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/e2e/test_e2e.py +0 -0
  50. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/integration/__init__.py +0 -0
  51. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/integration/conftest.py +0 -0
  52. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/integration/test_failfast.py +0 -0
  53. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/integration/test_no_config.py +0 -0
  54. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/integration/test_order.py +0 -0
  55. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/integration/test_report.py +0 -0
  56. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/integration/test_smoke_tag.py +0 -0
  57. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/__init__.py +0 -0
  58. {behave_priority-1.2.0 → behave_priority-1.2.1}/tests/unit/test_exceptions.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: behave-priority
3
- Version: 1.2.0
3
+ Version: 1.2.1
4
4
  Summary: Priority-based execution for Behave BDD
5
5
  Project-URL: Homepage, https://github.com/MathiasPaulenko/behave-priority
6
6
  Project-URL: Repository, https://github.com/MathiasPaulenko/behave-priority
@@ -40,7 +40,7 @@ Description-Content-Type: text/markdown
40
40
 
41
41
  [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
42
42
  [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
43
- [![Tests](https://img.shields.io/badge/tests-409%20passed-brightgreen.svg)]()
43
+ [![Tests](https://img.shields.io/badge/tests-512%20passed-brightgreen.svg)]()
44
44
  [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)]()
45
45
  [![mypy: strict](https://img.shields.io/badge/mypy-strict-blue.svg)]()
46
46
  [![ruff](https://img.shields.io/badge/ruff-passing-brightgreen.svg)]()
@@ -80,7 +80,7 @@ In CI, if critical tests fail, you waste time waiting for the full regression su
80
80
 
81
81
  ### Fail-fast
82
82
 
83
- - `stop_after_failures=N` — stops execution after N failed scenarios
83
+ - `stop_after_failures=N` — stops execution after N failed or errored scenarios
84
84
  - `stop_on_critical=True` — stops if any `@critical` scenario fails
85
85
  - `@critical` also works at `Feature` and `Rule` level, marking all scenarios inside
86
86
  - Combines with `order=True`: run critical first, stop if they fail, skip regression
@@ -214,7 +214,7 @@ Configuration can be passed explicitly or via environment variables when argumen
214
214
  | `order` | `bool \| None` | `None` (`False`) | Sort scenarios by priority | `BEHAVE_PRIORITY_ORDER` (0/1) |
215
215
  | `reverse` | `bool \| None` | `None` (`False`) | Reverse sort order (lowest priority first) | `BEHAVE_PRIORITY_REVERSE` (0/1) |
216
216
  | `priority_tag` | `str \| None` | `None` | Tag name to run first (e.g. `"smoke"`) | — |
217
- | `stop_after_failures` | `int \| None` | `None` (disabled) | Stop after N failures | `BEHAVE_PRIORITY_STOP_AFTER` |
217
+ | `stop_after_failures` | `int \| None` | `None` (disabled) | Stop after N failed or errored scenarios | `BEHAVE_PRIORITY_STOP_AFTER` |
218
218
  | `stop_on_critical` | `bool \| None` | `None` (`False`) | Stop if any `@critical` scenario fails | `BEHAVE_PRIORITY_FAIL_FAST` (0/1) |
219
219
  | `critical_tag` | `str` | `"critical"` | Tag name for critical scenarios | — |
220
220
  | `default_priority` | `int` | `999` | Priority for untagged scenarios | — |
@@ -249,12 +249,12 @@ Returns the `PriorityReport` for the run (or `None` if `setup_priority` wasn't c
249
249
  def after_all(context):
250
250
  report = get_report(context)
251
251
  if report:
252
- data = report.to_dict() # dict: {"entries": [...], "summary": {...}}
252
+ data = report.to_dict() # dict: {"entries": [...], "summary": {...}}
253
253
  json_str = report.to_json() # same as to_dict, as JSON string
254
- csv_str = report.to_csv() # one row per scenario (no summary)
255
- for entry in report.entries: # tuple of ReportEntry, in execution order
254
+ csv_str = report.to_csv() # one row per scenario (no summary)
255
+ for entry in report.entries: # tuple of ReportEntry, in execution order
256
256
  print(entry.scenario_name, entry.status)
257
- summary = report.summary() # ReportSummary with aggregates
257
+ summary = report.summary() # ReportSummary with aggregates
258
258
  ```
259
259
 
260
260
  ### `PriorityConfig`
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
4
4
  [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
5
- [![Tests](https://img.shields.io/badge/tests-409%20passed-brightgreen.svg)]()
5
+ [![Tests](https://img.shields.io/badge/tests-512%20passed-brightgreen.svg)]()
6
6
  [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)]()
7
7
  [![mypy: strict](https://img.shields.io/badge/mypy-strict-blue.svg)]()
8
8
  [![ruff](https://img.shields.io/badge/ruff-passing-brightgreen.svg)]()
@@ -42,7 +42,7 @@ In CI, if critical tests fail, you waste time waiting for the full regression su
42
42
 
43
43
  ### Fail-fast
44
44
 
45
- - `stop_after_failures=N` — stops execution after N failed scenarios
45
+ - `stop_after_failures=N` — stops execution after N failed or errored scenarios
46
46
  - `stop_on_critical=True` — stops if any `@critical` scenario fails
47
47
  - `@critical` also works at `Feature` and `Rule` level, marking all scenarios inside
48
48
  - Combines with `order=True`: run critical first, stop if they fail, skip regression
@@ -176,7 +176,7 @@ Configuration can be passed explicitly or via environment variables when argumen
176
176
  | `order` | `bool \| None` | `None` (`False`) | Sort scenarios by priority | `BEHAVE_PRIORITY_ORDER` (0/1) |
177
177
  | `reverse` | `bool \| None` | `None` (`False`) | Reverse sort order (lowest priority first) | `BEHAVE_PRIORITY_REVERSE` (0/1) |
178
178
  | `priority_tag` | `str \| None` | `None` | Tag name to run first (e.g. `"smoke"`) | — |
179
- | `stop_after_failures` | `int \| None` | `None` (disabled) | Stop after N failures | `BEHAVE_PRIORITY_STOP_AFTER` |
179
+ | `stop_after_failures` | `int \| None` | `None` (disabled) | Stop after N failed or errored scenarios | `BEHAVE_PRIORITY_STOP_AFTER` |
180
180
  | `stop_on_critical` | `bool \| None` | `None` (`False`) | Stop if any `@critical` scenario fails | `BEHAVE_PRIORITY_FAIL_FAST` (0/1) |
181
181
  | `critical_tag` | `str` | `"critical"` | Tag name for critical scenarios | — |
182
182
  | `default_priority` | `int` | `999` | Priority for untagged scenarios | — |
@@ -211,12 +211,12 @@ Returns the `PriorityReport` for the run (or `None` if `setup_priority` wasn't c
211
211
  def after_all(context):
212
212
  report = get_report(context)
213
213
  if report:
214
- data = report.to_dict() # dict: {"entries": [...], "summary": {...}}
214
+ data = report.to_dict() # dict: {"entries": [...], "summary": {...}}
215
215
  json_str = report.to_json() # same as to_dict, as JSON string
216
- csv_str = report.to_csv() # one row per scenario (no summary)
217
- for entry in report.entries: # tuple of ReportEntry, in execution order
216
+ csv_str = report.to_csv() # one row per scenario (no summary)
217
+ for entry in report.entries: # tuple of ReportEntry, in execution order
218
218
  print(entry.scenario_name, entry.status)
219
- summary = report.summary() # ReportSummary with aggregates
219
+ summary = report.summary() # ReportSummary with aggregates
220
220
  ```
221
221
 
222
222
  ### `PriorityConfig`
@@ -31,7 +31,7 @@ from behave_priority.sorter import ScenarioSorter
31
31
 
32
32
  logging.getLogger(__name__).addHandler(logging.NullHandler())
33
33
 
34
- __version__ = "1.2.0"
34
+ __version__ = "1.2.1"
35
35
 
36
36
  __all__ = [
37
37
  "PriorityConfig",
@@ -10,6 +10,11 @@ ReportFormat = Literal["text", "json", "csv"]
10
10
  _VALID_FORMATS: frozenset[str] = frozenset({"text", "json", "csv"})
11
11
 
12
12
 
13
+ def _clean_tag(tag: str) -> str:
14
+ """Return the tag without surrounding whitespace or ``@`` prefix."""
15
+ return tag.strip().removeprefix("@").strip()
16
+
17
+
13
18
  @dataclass(frozen=True, slots=True)
14
19
  class PriorityConfig:
15
20
  """Immutable configuration for priority execution.
@@ -20,7 +25,8 @@ class PriorityConfig:
20
25
  order: Sort scenarios by priority (highest first).
21
26
  reverse: Reverse sort order (lowest priority first).
22
27
  priority_tag: Tag name to run first (e.g. ``"smoke"``).
23
- stop_after_failures: Stop after N failed scenarios, or None to disable.
28
+ stop_after_failures: Stop after N failed or errored scenarios,
29
+ or None to disable.
24
30
  stop_on_critical: Stop if any critical scenario fails.
25
31
  critical_tag: Tag name that marks a scenario as critical.
26
32
  default_priority: Priority for scenarios without a priority tag.
@@ -33,8 +39,11 @@ class PriorityConfig:
33
39
 
34
40
  Raises:
35
41
  ValueError: If ``stop_after_failures`` is not a positive integer
36
- (or None), if ``critical_tag`` or ``priority_tag`` is an empty
37
- string, if ``default_priority`` is negative, or if
42
+ (or None), if ``critical_tag`` or ``priority_tag`` is not a
43
+ string that normalizes to a non-empty tag name, if
44
+ ``default_priority`` is not a non-negative integer, if any
45
+ flag field (``order``, ``reverse``, ``stop_on_critical``,
46
+ ``report``, ``parallel_coord``) is not a bool, or if
38
47
  ``report_format`` is not one of ``"text"``, ``"json"``, ``"csv"``.
39
48
  """
40
49
 
@@ -60,12 +69,33 @@ class PriorityConfig:
60
69
  f"stop_after_failures must be a positive integer or None, "
61
70
  f"got {self.stop_after_failures!r}"
62
71
  )
63
- if not self.critical_tag:
64
- raise ValueError("critical_tag must not be empty")
65
- if self.priority_tag is not None and not self.priority_tag:
66
- raise ValueError("priority_tag must not be empty if provided")
67
- if self.default_priority < 0:
68
- raise ValueError(f"default_priority must be non-negative, got {self.default_priority}")
72
+ if (
73
+ not isinstance(self.default_priority, int)
74
+ or isinstance(self.default_priority, bool)
75
+ or self.default_priority < 0
76
+ ):
77
+ raise ValueError(
78
+ f"default_priority must be a non-negative integer, got {self.default_priority!r}"
79
+ )
80
+ if not isinstance(self.critical_tag, str) or not _clean_tag(self.critical_tag):
81
+ raise ValueError(
82
+ f"critical_tag must be a non-empty tag name, got {self.critical_tag!r}"
83
+ )
84
+ if self.priority_tag is not None and (
85
+ not isinstance(self.priority_tag, str) or not _clean_tag(self.priority_tag)
86
+ ):
87
+ raise ValueError(
88
+ f"priority_tag must be a non-empty tag name if provided, got {self.priority_tag!r}"
89
+ )
90
+ for flag in (
91
+ "order",
92
+ "reverse",
93
+ "stop_on_critical",
94
+ "report",
95
+ "parallel_coord",
96
+ ):
97
+ if not isinstance(getattr(self, flag), bool):
98
+ raise ValueError(f"{flag} must be a bool, got {getattr(self, flag)!r}")
69
99
  if self.report_format not in _VALID_FORMATS:
70
100
  raise ValueError(
71
101
  f"report_format must be one of 'text', 'json', 'csv', got {self.report_format!r}"
@@ -13,11 +13,20 @@ from behave_priority.parallel import (
13
13
  ParallelCoordinator,
14
14
  cleanup_coordinator,
15
15
  create_coordinator,
16
+ get_coord_dir,
16
17
  )
17
18
  from behave_priority.parser import is_critical, resolve_priority
18
19
  from behave_priority.report import PriorityReport
19
20
  from behave_priority.sorter import ScenarioSorter
20
21
 
22
+ # Statuses that count toward fail-fast thresholds. Behave maps
23
+ # hook/cleanup/step errors and undefined steps to a failed run, so
24
+ # counting only literal "failed" would let a broken suite run to
25
+ # completion without ever triggering fail-fast.
26
+ _FAILURE_STATUSES = frozenset(
27
+ {"failed", "error", "hook_error", "cleanup_error", "undefined", "pending"}
28
+ )
29
+
21
30
 
22
31
  def _scenario_key(scenario: Any) -> str:
23
32
  """Build a deterministic key for a scenario.
@@ -68,7 +77,10 @@ def _map_scenario(
68
77
  for example in expanded:
69
78
  key = _scenario_key(example)
70
79
  state.priority_map[key] = resolve_priority(
71
- example.tags, feature_tags, config, effective_rule_tags
80
+ getattr(example, "tags", None) or [],
81
+ feature_tags,
82
+ config,
83
+ effective_rule_tags,
72
84
  )
73
85
  state.feature_map[key] = feature_name
74
86
  state.rule_tag_map[key] = effective_rule_tags
@@ -76,7 +88,10 @@ def _map_scenario(
76
88
  else:
77
89
  key = _scenario_key(scenario)
78
90
  state.priority_map[key] = resolve_priority(
79
- scenario.tags, feature_tags, config, effective_rule_tags
91
+ getattr(scenario, "tags", None) or [],
92
+ feature_tags,
93
+ config,
94
+ effective_rule_tags,
80
95
  )
81
96
  state.feature_map[key] = feature_name
82
97
  state.rule_tag_map[key] = effective_rule_tags
@@ -100,7 +115,7 @@ class PriorityState:
100
115
  sorter: The scenario sorter instance.
101
116
  coordinator: Optional parallel coordinator for cross-process
102
117
  fail-fast. None when ``parallel_coord`` is disabled.
103
- failed_count: Number of failed scenarios so far.
118
+ failed_count: Number of failed or errored scenarios so far.
104
119
  critical_failed: Whether any critical scenario has failed.
105
120
  should_stop: Whether fail-fast conditions have been triggered.
106
121
  executed_count: Number of scenarios actually executed.
@@ -178,8 +193,9 @@ def setup_priority(
178
193
  reverse: Reverse sort order (lowest priority first). If ``None``,
179
194
  reads ``BEHAVE_PRIORITY_REVERSE`` (default ``0``).
180
195
  priority_tag: Tag name to run first (e.g. ``"smoke"``).
181
- stop_after_failures: Stop after N failed scenarios. If ``None``,
182
- reads ``BEHAVE_PRIORITY_STOP_AFTER`` (default disabled).
196
+ stop_after_failures: Stop after N failed or errored scenarios.
197
+ If ``None``, reads ``BEHAVE_PRIORITY_STOP_AFTER`` (default
198
+ disabled).
183
199
  stop_on_critical: Stop if any critical scenario fails. If ``None``,
184
200
  reads ``BEHAVE_PRIORITY_FAIL_FAST`` (default ``0``).
185
201
  critical_tag: Tag name that marks a scenario as critical.
@@ -238,8 +254,10 @@ def setup_priority(
238
254
  )
239
255
  return
240
256
 
257
+ features_attr = "features"
241
258
  features = getattr(runner, "features", None)
242
259
  if features is None:
260
+ features_attr = "feature_list"
243
261
  features = getattr(runner, "feature_list", None)
244
262
  if features is None:
245
263
  warnings.warn(
@@ -252,7 +270,19 @@ def setup_priority(
252
270
 
253
271
  sorter = ScenarioSorter(config)
254
272
  sorted_features = sorter.sort(features)
255
- features[:] = sorted_features
273
+ try:
274
+ features[:] = sorted_features
275
+ except TypeError:
276
+ # The runner's feature collection is not a mutable sequence
277
+ # (e.g. a tuple or a custom object): try replacing the attribute.
278
+ try:
279
+ setattr(runner, features_attr, sorted_features)
280
+ except AttributeError:
281
+ warnings.warn(
282
+ "runner's feature collection is not mutable. Scenarios will NOT be reordered.",
283
+ RuntimeWarning,
284
+ stacklevel=2,
285
+ )
256
286
 
257
287
  priority_report_obj = PriorityReport(config)
258
288
  state = PriorityState(
@@ -262,18 +292,19 @@ def setup_priority(
262
292
  )
263
293
 
264
294
  for feature in sorted_features:
265
- feature_name = feature.name or feature.filename
266
- items = getattr(feature, "run_items", None) or feature.scenarios
295
+ feature_name = str(getattr(feature, "name", None) or getattr(feature, "filename", ""))
296
+ feature_tags = getattr(feature, "tags", None) or []
297
+ items = getattr(feature, "run_items", None) or getattr(feature, "scenarios", None) or []
267
298
  for item in items:
268
299
  if hasattr(item, "run_items"):
269
- rule_tags: list[str] = getattr(item, "tags", [])
300
+ rule_tags: list[str] = getattr(item, "tags", None) or []
270
301
  inner_items: Any = getattr(item, "run_items", None) or getattr(
271
302
  item, "scenarios", []
272
303
  )
273
304
  for scenario in inner_items:
274
- _map_scenario(state, scenario, feature.tags, feature_name, config, rule_tags)
305
+ _map_scenario(state, scenario, feature_tags, feature_name, config, rule_tags)
275
306
  else:
276
- _map_scenario(state, item, feature.tags, feature_name, config)
307
+ _map_scenario(state, item, feature_tags, feature_name, config)
277
308
 
278
309
  context._priority_state = state
279
310
 
@@ -282,7 +313,9 @@ def setup_priority(
282
313
  if coordinator is not None:
283
314
  state.coordinator = coordinator
284
315
  context._priority_coordinator = coordinator
285
- else:
316
+ elif get_coord_dir() is None:
317
+ # create_coordinator() already warns when the dir is set
318
+ # but unusable; only warn here when it is missing entirely.
286
319
  warnings.warn(
287
320
  "parallel_coord=True but BEHAVE_PRIORITY_COORD_DIR "
288
321
  "env var is not set. Cross-process coordination "
@@ -311,9 +344,9 @@ def before_scenario_hook(context: Any, scenario: Any) -> None:
311
344
  state.should_stop = state.check_fail_fast()
312
345
 
313
346
  if state.should_stop:
314
- state.skipped_count += 1
315
- if hasattr(scenario, "skip"):
347
+ if callable(getattr(scenario, "skip", None)):
316
348
  scenario.skip("fail-fast triggered")
349
+ state.skipped_count += 1
317
350
  elif not state.missing_skip_warned:
318
351
  state.missing_skip_warned = True
319
352
  warnings.warn(
@@ -348,8 +381,8 @@ def after_scenario_hook(context: Any, scenario: Any) -> None:
348
381
 
349
382
  rule_tags = state.rule_tag_map.get(key, [])
350
383
  feature_tags = state.feature_tag_map.get(key, [])
351
- scenario_tags = getattr(scenario, "tags", [])
352
- combined_tags = list(scenario_tags) + rule_tags + feature_tags
384
+ scenario_tags = getattr(scenario, "tags", None) or []
385
+ combined_tags = list(scenario_tags) + list(rule_tags) + list(feature_tags)
353
386
  is_crit = is_critical(combined_tags, state.config.critical_tag)
354
387
 
355
388
  state.report.record(
@@ -361,20 +394,23 @@ def after_scenario_hook(context: Any, scenario: Any) -> None:
361
394
  is_critical=is_crit,
362
395
  )
363
396
 
397
+ # should_stop is a sticky latch: once fail-fast triggers it must not
398
+ # un-trigger, even if the aggregated global state transiently shrinks
399
+ # (e.g. a finished worker already removed its coordination file).
364
400
  if status == "skipped":
365
- state.should_stop = state.check_fail_fast()
401
+ state.should_stop = state.should_stop or state.check_fail_fast()
366
402
  return
367
403
 
368
404
  state.executed_count += 1
369
405
 
370
- if status == "failed":
406
+ if status in _FAILURE_STATUSES:
371
407
  state.failed_count += 1
372
408
  if is_crit:
373
409
  state.critical_failed = True
374
410
  if state.coordinator is not None:
375
411
  state.coordinator.report_failure(is_critical=is_crit)
376
412
 
377
- state.should_stop = state.check_fail_fast()
413
+ state.should_stop = state.should_stop or state.check_fail_fast()
378
414
 
379
415
 
380
416
  def get_report(context: Any) -> PriorityReport | None:
@@ -22,8 +22,11 @@ from __future__ import annotations
22
22
 
23
23
  import contextlib
24
24
  import json
25
+ import math
25
26
  import os
27
+ import re
26
28
  import time
29
+ import warnings
27
30
  from pathlib import Path
28
31
 
29
32
  _COORD_DIR_ENV = "BEHAVE_PRIORITY_COORD_DIR"
@@ -33,6 +36,67 @@ _COORD_DIR_ENV = "BEHAVE_PRIORITY_COORD_DIR"
33
36
  # and are ignored when aggregating global state.
34
37
  _CLOCK_SKEW_S = 120.0
35
38
 
39
+ # Worker IDs are interpolated into a filename inside the coordination
40
+ # directory. Restricting the charset prevents path traversal and special
41
+ # filenames from escaping or corrupting the directory.
42
+ _WORKER_ID_RE = re.compile(r"[A-Za-z0-9_.-]+")
43
+
44
+ # Retries for the final replace step of the atomic write. On Windows the
45
+ # rename can fail transiently when a peer process holds the destination
46
+ # file open for reading.
47
+ _REPLACE_RETRIES = 5
48
+ _REPLACE_DELAY_S = 0.01
49
+
50
+
51
+ def _read_worker_state(path: Path) -> tuple[float, int, bool] | None:
52
+ """Read and validate a worker state file.
53
+
54
+ Files are only produced by this library, but they may be truncated by
55
+ a crashed writer or corrupted externally. Any malformed file is
56
+ ignored rather than aborting the aggregation.
57
+
58
+ Args:
59
+ path: Path to a ``worker_*.json`` file.
60
+
61
+ Returns:
62
+ ``(created_at, failed_count, critical_failed)`` when the file is
63
+ valid, otherwise None.
64
+ """
65
+ try:
66
+ data = json.loads(path.read_text(encoding="utf-8"))
67
+ except (json.JSONDecodeError, OSError, UnicodeDecodeError):
68
+ return None
69
+ if not isinstance(data, dict):
70
+ return None
71
+
72
+ # bool is an int subclass and must be rejected explicitly.
73
+ # float() conversion may raise OverflowError on absurdly large ints.
74
+ created_at = data.get("created_at")
75
+ if isinstance(created_at, bool) or not isinstance(created_at, int | float):
76
+ return None
77
+ try:
78
+ created_at = float(created_at)
79
+ except OverflowError:
80
+ return None
81
+ if not math.isfinite(created_at):
82
+ return None
83
+
84
+ failed_count = data.get("failed_count")
85
+ if isinstance(failed_count, bool) or not isinstance(failed_count, int | float):
86
+ return None
87
+ try:
88
+ failed_count = float(failed_count)
89
+ except OverflowError:
90
+ return None
91
+ if not math.isfinite(failed_count) or failed_count < 0:
92
+ return None
93
+
94
+ critical_failed = data.get("critical_failed")
95
+ if not isinstance(critical_failed, bool):
96
+ return None
97
+
98
+ return created_at, int(failed_count), critical_failed
99
+
36
100
 
37
101
  class ParallelCoordinator:
38
102
  """File-based coordination for parallel workers.
@@ -57,14 +121,30 @@ class ParallelCoordinator:
57
121
  coord_dir: Path to the shared coordination directory.
58
122
  Will be created if it does not exist.
59
123
  worker_id: Unique identifier for this worker. If None,
60
- uses the process PID.
124
+ uses the process PID. Only letters, digits, ``_``,
125
+ ``-`` and ``.`` are allowed, since the value is
126
+ interpolated into a filename.
127
+
128
+ Raises:
129
+ ValueError: If ``worker_id`` contains characters outside the
130
+ allowed set, or ``coord_dir`` is empty.
131
+ OSError: If the coordination directory cannot be created or
132
+ written to.
61
133
  """
134
+ if not str(coord_dir).strip():
135
+ raise ValueError(f"coord_dir must not be empty, got {coord_dir!r}")
136
+ self.worker_id = worker_id or str(os.getpid())
137
+ if not isinstance(self.worker_id, str) or not _WORKER_ID_RE.fullmatch(self.worker_id):
138
+ raise ValueError(
139
+ f"worker_id must contain only letters, digits, '_', '-' "
140
+ f"and '.', got {self.worker_id!r}"
141
+ )
62
142
  self.coord_dir = Path(coord_dir)
63
143
  self.coord_dir.mkdir(parents=True, exist_ok=True)
64
- self.worker_id = worker_id or str(os.getpid())
65
144
  self._worker_file = self.coord_dir / f"worker_{self.worker_id}.json"
66
145
  self._failed_count = 0
67
146
  self._critical_failed = False
147
+ self._write_warned = False
68
148
  self._started_at = time.time()
69
149
  self._write_state()
70
150
 
@@ -79,7 +159,19 @@ class ParallelCoordinator:
79
159
  self._failed_count += 1
80
160
  if is_critical:
81
161
  self._critical_failed = True
82
- self._write_state()
162
+ try:
163
+ self._write_state()
164
+ except OSError:
165
+ # A failing worker must not abort the test run; fail-fast
166
+ # degrades to per-worker state until writes succeed again.
167
+ if not self._write_warned:
168
+ self._write_warned = True
169
+ warnings.warn(
170
+ f"parallel coordinator: cannot write {self._worker_file}; "
171
+ "shared fail-fast state may be stale",
172
+ RuntimeWarning,
173
+ stacklevel=2,
174
+ )
83
175
 
84
176
  def should_stop(
85
177
  self,
@@ -104,17 +196,22 @@ class ParallelCoordinator:
104
196
  global_critical = False
105
197
  min_created_at = self._started_at - _CLOCK_SKEW_S
106
198
 
107
- for f in self.coord_dir.glob("worker_*.json"):
108
- try:
109
- data = json.loads(f.read_text(encoding="utf-8"))
110
- except (json.JSONDecodeError, OSError):
111
- continue
112
- created_at = data.get("created_at")
113
- if not isinstance(created_at, int | float) or created_at < min_created_at:
114
- continue
115
- global_failed += data.get("failed_count", 0)
116
- if data.get("critical_failed", False):
117
- global_critical = True
199
+ try:
200
+ worker_files = self.coord_dir.glob("worker_*.json")
201
+ for f in worker_files:
202
+ state = _read_worker_state(f)
203
+ if state is None:
204
+ continue
205
+ created_at, failed_count, critical_failed = state
206
+ if created_at < min_created_at:
207
+ continue
208
+ global_failed += failed_count
209
+ if critical_failed:
210
+ global_critical = True
211
+ except OSError:
212
+ # An unreadable coordination directory cannot abort the run;
213
+ # with no readable state, global conditions are not met.
214
+ pass
118
215
 
119
216
  if stop_after_failures is not None and global_failed >= stop_after_failures:
120
217
  return True
@@ -124,6 +221,7 @@ class ParallelCoordinator:
124
221
  """Remove this worker's file from the coordination directory."""
125
222
  with contextlib.suppress(OSError):
126
223
  self._worker_file.unlink(missing_ok=True)
224
+ self._worker_file.with_suffix(".tmp").unlink(missing_ok=True)
127
225
 
128
226
  def _write_state(self) -> None:
129
227
  """Atomically write this worker's state to its file."""
@@ -134,16 +232,28 @@ class ParallelCoordinator:
134
232
  }
135
233
  tmp = self._worker_file.with_suffix(".tmp")
136
234
  tmp.write_text(json.dumps(data), encoding="utf-8")
137
- tmp.replace(self._worker_file)
235
+ for attempt in range(_REPLACE_RETRIES):
236
+ try:
237
+ tmp.replace(self._worker_file)
238
+ return
239
+ except OSError:
240
+ if attempt == _REPLACE_RETRIES - 1:
241
+ raise
242
+ time.sleep(_REPLACE_DELAY_S)
138
243
 
139
244
 
140
245
  def get_coord_dir() -> str | None:
141
246
  """Get the coordination directory from the environment variable.
142
247
 
143
248
  Returns:
144
- The path from ``BEHAVE_PRIORITY_COORD_DIR`` env var, or None.
249
+ The path from ``BEHAVE_PRIORITY_COORD_DIR`` env var, or None when
250
+ the variable is unset, empty, or whitespace-only.
145
251
  """
146
- return os.environ.get(_COORD_DIR_ENV)
252
+ value = os.environ.get(_COORD_DIR_ENV)
253
+ if value is None:
254
+ return None
255
+ value = value.strip()
256
+ return value or None
147
257
 
148
258
 
149
259
  def create_coordinator(worker_id: str | None = None) -> ParallelCoordinator | None:
@@ -153,13 +263,26 @@ def create_coordinator(worker_id: str | None = None) -> ParallelCoordinator | No
153
263
  worker_id: Optional worker identifier. Defaults to PID.
154
264
 
155
265
  Returns:
156
- A ``ParallelCoordinator`` if ``BEHAVE_PRIORITY_COORD_DIR`` is set,
157
- otherwise None.
266
+ A ``ParallelCoordinator`` if ``BEHAVE_PRIORITY_COORD_DIR`` is set
267
+ and usable, otherwise None. A warning is emitted when the
268
+ directory exists in the env var but cannot be used.
269
+
270
+ Raises:
271
+ ValueError: If ``worker_id`` is invalid.
158
272
  """
159
273
  coord_dir = get_coord_dir()
160
274
  if coord_dir is None:
161
275
  return None
162
- return ParallelCoordinator(coord_dir, worker_id=worker_id)
276
+ try:
277
+ return ParallelCoordinator(coord_dir, worker_id=worker_id)
278
+ except OSError as e:
279
+ warnings.warn(
280
+ f"BEHAVE_PRIORITY_COORD_DIR={coord_dir!r} is not usable: {e}. "
281
+ "Cross-process coordination is disabled.",
282
+ RuntimeWarning,
283
+ stacklevel=2,
284
+ )
285
+ return None
163
286
 
164
287
 
165
288
  def cleanup_coordinator(context: object) -> None: