test-base 0.1.1__py3-none-any.whl

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 (103) hide show
  1. test_base/__init__.py +20 -0
  2. test_base/adapters/__init__.py +354 -0
  3. test_base/adapters/base.py +263 -0
  4. test_base/adapters/canonical_json.py +1088 -0
  5. test_base/adapters/junit_xml.py +1272 -0
  6. test_base/api/__init__.py +0 -0
  7. test_base/api/app.py +314 -0
  8. test_base/api/deps.py +178 -0
  9. test_base/api/routes/__init__.py +0 -0
  10. test_base/api/routes/failures.py +104 -0
  11. test_base/api/routes/health.py +35 -0
  12. test_base/api/routes/imports.py +143 -0
  13. test_base/api/routes/queries.py +295 -0
  14. test_base/api/routes/retention.py +130 -0
  15. test_base/api/routes/runs.py +147 -0
  16. test_base/api/routes/server.py +65 -0
  17. test_base/api/routes/stream.py +117 -0
  18. test_base/api/schemas.py +390 -0
  19. test_base/api/security.py +183 -0
  20. test_base/cli/__init__.py +125 -0
  21. test_base/cli/commands/__init__.py +0 -0
  22. test_base/cli/commands/db.py +76 -0
  23. test_base/cli/commands/demo.py +103 -0
  24. test_base/cli/commands/formats.py +41 -0
  25. test_base/cli/commands/ingest.py +119 -0
  26. test_base/cli/commands/init.py +738 -0
  27. test_base/cli/commands/prune.py +146 -0
  28. test_base/cli/commands/publish.py +133 -0
  29. test_base/cli/commands/serve.py +118 -0
  30. test_base/cli/commands/token.py +97 -0
  31. test_base/cli/options.py +189 -0
  32. test_base/cli/render.py +223 -0
  33. test_base/config.py +519 -0
  34. test_base/demo/__init__.py +0 -0
  35. test_base/demo/evidence.py +447 -0
  36. test_base/demo/seed.py +628 -0
  37. test_base/domain/__init__.py +61 -0
  38. test_base/domain/events.py +422 -0
  39. test_base/domain/failures.py +327 -0
  40. test_base/domain/identity.py +205 -0
  41. test_base/domain/metrics.py +176 -0
  42. test_base/domain/models.py +947 -0
  43. test_base/domain/status.py +246 -0
  44. test_base/errors.py +136 -0
  45. test_base/logging.py +174 -0
  46. test_base/py.typed +0 -0
  47. test_base/sdk/__init__.py +28 -0
  48. test_base/sdk/client.py +607 -0
  49. test_base/service/__init__.py +0 -0
  50. test_base/service/bus.py +331 -0
  51. test_base/service/coalesce.py +133 -0
  52. test_base/service/imports.py +552 -0
  53. test_base/service/retention.py +640 -0
  54. test_base/service/runs.py +394 -0
  55. test_base/service/runtime.py +123 -0
  56. test_base/storage/__init__.py +41 -0
  57. test_base/storage/artifacts.py +347 -0
  58. test_base/storage/base.py +350 -0
  59. test_base/storage/db.py +595 -0
  60. test_base/storage/failures.py +321 -0
  61. test_base/storage/locks.py +104 -0
  62. test_base/storage/migrations/env.py +108 -0
  63. test_base/storage/migrations/script.py.mako +26 -0
  64. test_base/storage/migrations/versions/0001_initial.py +289 -0
  65. test_base/storage/migrations/versions/0002_retention_indexes.py +38 -0
  66. test_base/storage/migrations/versions/0003_postgresql_bigint.py +74 -0
  67. test_base/storage/migrations/versions/0004_run_shards.py +37 -0
  68. test_base/storage/migrations/versions/0005_failure_groups.py +206 -0
  69. test_base/storage/models.py +560 -0
  70. test_base/storage/repositories.py +2481 -0
  71. test_base/storage/uow.py +138 -0
  72. test_base/version.py +17 -0
  73. test_base/web/assets/css/app.css +3567 -0
  74. test_base/web/assets/favicon.svg +5 -0
  75. test_base/web/assets/js/00-util.js +829 -0
  76. test_base/web/assets/js/05-windows.js +551 -0
  77. test_base/web/assets/js/10-provider.js +396 -0
  78. test_base/web/assets/js/12-live-provider.js +804 -0
  79. test_base/web/assets/js/20-charts.js +715 -0
  80. test_base/web/assets/js/30-store.js +793 -0
  81. test_base/web/assets/js/40-components.js +2141 -0
  82. test_base/web/assets/js/42-timeline.js +629 -0
  83. test_base/web/assets/js/50-view-overview.js +747 -0
  84. test_base/web/assets/js/52-view-analytics.js +842 -0
  85. test_base/web/assets/js/53-view-suites.js +508 -0
  86. test_base/web/assets/js/54-view-metrics.js +438 -0
  87. test_base/web/assets/js/55-view-runs.js +244 -0
  88. test_base/web/assets/js/56-view-evidence.js +703 -0
  89. test_base/web/assets/js/57-view-failures.js +596 -0
  90. test_base/web/assets/js/60-view-run.js +788 -0
  91. test_base/web/assets/js/65-view-test.js +402 -0
  92. test_base/web/assets/js/70-view-settings.js +524 -0
  93. test_base/web/assets/js/75-view-help.js +554 -0
  94. test_base/web/assets/js/80-settings.js +99 -0
  95. test_base/web/assets/js/85-activity.js +727 -0
  96. test_base/web/assets/js/90-app.js +595 -0
  97. test_base/web/assets/manifest.json +70 -0
  98. test_base/web/index.html +210 -0
  99. test_base-0.1.1.dist-info/METADATA +285 -0
  100. test_base-0.1.1.dist-info/RECORD +103 -0
  101. test_base-0.1.1.dist-info/WHEEL +4 -0
  102. test_base-0.1.1.dist-info/entry_points.txt +6 -0
  103. test_base-0.1.1.dist-info/licenses/LICENSE +201 -0
test_base/__init__.py ADDED
@@ -0,0 +1,20 @@
1
+ """Test Base — universal test observability.
2
+
3
+ Test Base collects test results from any language, framework, team or pipeline,
4
+ normalizes them into one canonical model and shows them in one dashboard.
5
+
6
+ The package is layered, and the layers only point one way::
7
+
8
+ cli ──▶ api ──▶ service ──▶ storage
9
+ │ │ │
10
+ │ │ └──▶ domain ◀── adapters
11
+ └──▶ sdk ─(http)─▶ api
12
+
13
+ :mod:`test_base.domain` imports nothing else from the package: it is the contract.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from test_base.version import CLOUDEVENTS_SPEC_VERSION, SCHEMA_VERSION, __version__
19
+
20
+ __all__ = ["CLOUDEVENTS_SPEC_VERSION", "SCHEMA_VERSION", "__version__"]
@@ -0,0 +1,354 @@
1
+ """The adapter registry: how Test Base finds out which parser can read a file.
2
+
3
+ An adapter is discovered, never hard-wired. Every adapter — including the two
4
+ Test Base ships — is published through the ``test_base.adapters`` entry-point
5
+ group, so a third-party package that adds TRX or Allure support is exactly as
6
+ privileged as ``junit-xml`` is. This module is the only place that knows how to
7
+ find them, score them and hand the winner to the import service.
8
+
9
+ Discovery
10
+ ---------
11
+
12
+ ``importlib.metadata.entry_points(group="test_base.adapters")`` is the primary
13
+ path. It only works once the distribution has been installed, and Test Base is
14
+ very often run straight from a checkout with ``PYTHONPATH=src`` before anyone
15
+ has typed ``pip install -e .`` — in that state the group is empty and a naive
16
+ registry would report "no adapters installed" for a perfectly good JUnit file.
17
+ So when the group yields nothing (or yields something that does not include a
18
+ built-in), the built-ins are imported by module path instead. Which path was
19
+ taken is logged at ``debug`` level, because "why did it not see my adapter"
20
+ is the question this module exists to answer.
21
+
22
+ A third-party entry point that raises on import is *skipped with a warning*.
23
+ One broken plugin must not stop the process from parsing a JUnit file, and it
24
+ must not be silent either.
25
+
26
+ Detection
27
+ ---------
28
+
29
+ :meth:`AdapterRegistry.detect` asks every adapter to score the input, rewinding
30
+ the stream in between (an adapter is allowed to read the head of the stream and
31
+ sloppy about putting it back). The winner is the highest score at or above
32
+ :data:`~test_base.adapters.base.MIN_CONFIDENCE`; ties break on ``priority`` and
33
+ then on ``name``, so two adapters that both say 0.9 always resolve the same way
34
+ on every machine and in every process.
35
+
36
+ When nothing scores high enough the resulting
37
+ :class:`~test_base.errors.UnknownFormatError` carries the full installed-adapter
38
+ table — name, description, extensions. That error message *is* the
39
+ documentation for "what can I upload"; it is deliberately not a bare
40
+ "unsupported format".
41
+ """
42
+
43
+ from __future__ import annotations
44
+
45
+ import contextlib
46
+ import importlib
47
+ import threading
48
+ from importlib.metadata import EntryPoint, entry_points
49
+ from typing import IO, Any
50
+
51
+ from test_base.adapters.base import MIN_CONFIDENCE, ReportAdapter
52
+ from test_base.errors import UnknownFormatError
53
+ from test_base.logging import get_logger
54
+
55
+ __all__ = [
56
+ "ADAPTER_ENTRY_POINT_GROUP",
57
+ "BUILTIN_ADAPTERS",
58
+ "AdapterRegistry",
59
+ "get_registry",
60
+ "reset_registry",
61
+ "select_adapter",
62
+ ]
63
+
64
+ logger = get_logger(__name__)
65
+
66
+ #: The entry-point group every adapter publishes itself in.
67
+ ADAPTER_ENTRY_POINT_GROUP = "test_base.adapters"
68
+
69
+ #: ``name -> "module:attribute"`` for the adapters that live in this package.
70
+ #: Used only as the fallback when the entry-point group cannot see them, which
71
+ #: is the normal state of a source checkout.
72
+ BUILTIN_ADAPTERS: dict[str, str] = {
73
+ "testbase-json": "test_base.adapters.canonical_json:CanonicalJsonAdapter",
74
+ "junit-xml": "test_base.adapters.junit_xml:JUnitXmlAdapter",
75
+ }
76
+
77
+
78
+ def _instantiate(loaded: Any, label: str) -> ReportAdapter:
79
+ """Turn whatever an entry point pointed at into an adapter instance.
80
+
81
+ Entry points are allowed to name a class, a zero-argument factory or a
82
+ ready-made singleton; all three appear in the wild and all three are cheap
83
+ to support here rather than in every adapter package.
84
+ """
85
+ candidate = loaded() if isinstance(loaded, type) else loaded
86
+ looks_like_adapter = callable(getattr(candidate, "parse", None)) and callable(
87
+ getattr(candidate, "detect", None)
88
+ )
89
+ if not looks_like_adapter and callable(candidate):
90
+ candidate = candidate()
91
+ for attribute in ("name", "detect", "parse"):
92
+ if not hasattr(candidate, attribute):
93
+ raise TypeError(f"{label} is not a ReportAdapter: it has no {attribute!r}")
94
+ return candidate # type: ignore[no-any-return]
95
+
96
+
97
+ class AdapterRegistry:
98
+ """The set of adapters this process can use.
99
+
100
+ Not a global by construction: tests build their own, register a fake and
101
+ throw it away. :func:`get_registry` is the process-wide one that production
102
+ code uses.
103
+ """
104
+
105
+ def __init__(self) -> None:
106
+ self._adapters: dict[str, ReportAdapter] = {}
107
+
108
+ # ------------------------------------------------------------ mutation
109
+
110
+ def register(self, adapter: ReportAdapter) -> None:
111
+ """Add an adapter, replacing any earlier one with the same name.
112
+
113
+ Replacement is deliberate and logged: it is how an operator overrides a
114
+ built-in with a patched fork without uninstalling anything.
115
+ """
116
+ name = getattr(adapter, "name", "")
117
+ if not isinstance(name, str) or not name.strip():
118
+ raise ValueError(f"adapter {adapter!r} has no usable .name")
119
+ name = name.strip()
120
+ if name in self._adapters:
121
+ logger.warning(
122
+ "adapter %r replaces the previously registered %r",
123
+ type(adapter).__name__,
124
+ type(self._adapters[name]).__name__,
125
+ )
126
+ self._adapters[name] = adapter
127
+
128
+ # ------------------------------------------------------------- lookup
129
+
130
+ def get(self, name: str) -> ReportAdapter:
131
+ """The adapter registered under ``name``.
132
+
133
+ Raises :class:`~test_base.errors.UnknownFormatError` — not ``KeyError`` —
134
+ because this is what ``--format nonsense`` reaches, and the caller
135
+ deserves the list of formats that do exist.
136
+ """
137
+ key = (name or "").strip()
138
+ adapter = self._adapters.get(key)
139
+ if adapter is None:
140
+ raise UnknownFormatError(
141
+ f"unknown format {name!r}.\n{self._format_table()}",
142
+ adapters=self.describe(),
143
+ )
144
+ return adapter
145
+
146
+ def names(self) -> list[str]:
147
+ return sorted(self._adapters)
148
+
149
+ def describe(self) -> list[dict[str, Any]]:
150
+ """One row per installed adapter, for ``test-base formats`` and errors."""
151
+ rows: list[dict[str, Any]] = []
152
+ for name in self.names():
153
+ adapter = self._adapters[name]
154
+ describe = getattr(adapter, "describe", None)
155
+ row: dict[str, Any]
156
+ if callable(describe):
157
+ row = dict(describe())
158
+ else: # a Protocol-only adapter that never inherited BaseAdapter
159
+ row = {
160
+ "name": name,
161
+ "display_name": getattr(adapter, "display_name", name),
162
+ "description": getattr(adapter, "description", ""),
163
+ "extensions": list(getattr(adapter, "extensions", ())),
164
+ "content_types": list(getattr(adapter, "content_types", ())),
165
+ }
166
+ row.setdefault("name", name)
167
+ row["priority"] = int(getattr(adapter, "priority", 0))
168
+ rows.append(row)
169
+ return rows
170
+
171
+ def __contains__(self, name: object) -> bool:
172
+ return isinstance(name, str) and name in self._adapters
173
+
174
+ def __len__(self) -> int:
175
+ return len(self._adapters)
176
+
177
+ # ---------------------------------------------------------- detection
178
+
179
+ def detect(
180
+ self, stream: IO[bytes], filename: str | None, content_type: str | None
181
+ ) -> tuple[ReportAdapter, float]:
182
+ """Score every adapter and return the best one above the threshold."""
183
+ try:
184
+ origin = stream.tell()
185
+ except (OSError, AttributeError): # pragma: no cover - non-seekable input
186
+ origin = 0
187
+
188
+ def rewind() -> None:
189
+ with contextlib.suppress(OSError, AttributeError): # non-seekable input
190
+ stream.seek(origin)
191
+
192
+ scored: list[tuple[float, int, str, ReportAdapter]] = []
193
+ for name in self.names():
194
+ adapter = self._adapters[name]
195
+ rewind()
196
+ try:
197
+ score = float(adapter.detect(stream, filename, content_type))
198
+ except Exception: # a broken detector must not fail the whole import
199
+ logger.warning("adapter %r raised during detection; scoring it 0.0", name)
200
+ score = 0.0
201
+ if score != score: # NaN
202
+ score = 0.0
203
+ score = max(0.0, min(1.0, score))
204
+ logger.debug("adapter %s scored %.2f for %s", name, score, filename or "<stream>")
205
+ if score >= MIN_CONFIDENCE:
206
+ scored.append((score, int(getattr(adapter, "priority", 0)), name, adapter))
207
+ rewind()
208
+
209
+ if not scored:
210
+ raise UnknownFormatError(
211
+ "no installed adapter recognised this input"
212
+ f" ({_describe_input(filename, content_type)}).\n{self._format_table()}",
213
+ adapters=self.describe(),
214
+ )
215
+ # Highest score, then highest priority, then lowest name: total and stable.
216
+ score, _priority, name, adapter = min(scored, key=lambda row: (-row[0], -row[1], row[2]))
217
+ logger.debug("selected adapter %s with confidence %.2f", name, score)
218
+ return adapter, score
219
+
220
+ # ------------------------------------------------------------ helpers
221
+
222
+ def _format_table(self) -> str:
223
+ """The human half of every "I don't know this file" message."""
224
+ if not self._adapters:
225
+ return (
226
+ "No adapters are installed at all, which means the Test Base package is "
227
+ "broken or was imported from a partial checkout."
228
+ )
229
+ lines = ["Installed adapters:"]
230
+ for row in self.describe():
231
+ extensions = ", ".join(row.get("extensions") or ()) or "no extension hint"
232
+ description = row.get("description") or row.get("display_name") or ""
233
+ lines.append(f" {row['name']:<16} {extensions:<22} {description}")
234
+ lines.append("Pass --format <name> to skip detection and force one of these.")
235
+ return "\n".join(lines)
236
+
237
+
238
+ def _describe_input(filename: str | None, content_type: str | None) -> str:
239
+ parts = []
240
+ if filename:
241
+ parts.append(f"filename={filename!r}")
242
+ if content_type:
243
+ parts.append(f"content_type={content_type!r}")
244
+ return ", ".join(parts) or "no filename or content type given"
245
+
246
+
247
+ def _load_entry_points(registry: AdapterRegistry) -> list[str]:
248
+ """Register everything the ``test_base.adapters`` group advertises."""
249
+ try:
250
+ points: list[EntryPoint] = list(entry_points(group=ADAPTER_ENTRY_POINT_GROUP))
251
+ except Exception: # pragma: no cover - a corrupt metadata dir must not be fatal
252
+ logger.warning("could not read the %r entry-point group", ADAPTER_ENTRY_POINT_GROUP)
253
+ return []
254
+
255
+ loaded: list[str] = []
256
+ for point in points:
257
+ try:
258
+ adapter = _instantiate(point.load(), f"entry point {point.name!r} ({point.value})")
259
+ registry.register(adapter)
260
+ except Exception as exc:
261
+ # A third-party plugin with a bad import must cost that plugin, not
262
+ # the process. The name and the reason are both in the log.
263
+ logger.warning(
264
+ "skipping adapter entry point %r (%s): %s: %s",
265
+ point.name,
266
+ point.value,
267
+ type(exc).__name__,
268
+ exc,
269
+ )
270
+ continue
271
+ loaded.append(point.name)
272
+ return loaded
273
+
274
+
275
+ def _load_builtin(registry: AdapterRegistry, spec: str) -> bool:
276
+ module_name, _, attribute = spec.partition(":")
277
+ try:
278
+ module = importlib.import_module(module_name)
279
+ registry.register(_instantiate(getattr(module, attribute), spec))
280
+ except Exception:
281
+ # Losing a built-in is a packaging bug, not a user error; log it loudly
282
+ # and let the unknown-format message show which adapters survived.
283
+ logger.exception("built-in adapter %s failed to load", spec)
284
+ return False
285
+ return True
286
+
287
+
288
+ def _build_registry() -> AdapterRegistry:
289
+ registry = AdapterRegistry()
290
+ discovered = _load_entry_points(registry)
291
+ if discovered:
292
+ logger.debug(
293
+ "loaded %d adapter(s) from the %r entry-point group: %s",
294
+ len(discovered),
295
+ ADAPTER_ENTRY_POINT_GROUP,
296
+ ", ".join(sorted(discovered)),
297
+ )
298
+ else:
299
+ logger.debug(
300
+ "the %r entry-point group is empty (the package is probably running from "
301
+ "source without `pip install -e .`); importing the built-in adapters directly",
302
+ ADAPTER_ENTRY_POINT_GROUP,
303
+ )
304
+ missing = [name for name in BUILTIN_ADAPTERS if name not in registry]
305
+ if missing and discovered:
306
+ logger.debug("entry points did not provide built-in adapter(s): %s", ", ".join(missing))
307
+ for name in missing:
308
+ _load_builtin(registry, BUILTIN_ADAPTERS[name])
309
+ return registry
310
+
311
+
312
+ _registry: AdapterRegistry | None = None
313
+ _registry_lock = threading.Lock()
314
+
315
+
316
+ def get_registry() -> AdapterRegistry:
317
+ """The process-wide registry, built once on first use."""
318
+ global _registry
319
+ if _registry is None:
320
+ with _registry_lock:
321
+ if _registry is None:
322
+ _registry = _build_registry()
323
+ return _registry
324
+
325
+
326
+ def reset_registry() -> None:
327
+ """Forget the process-wide registry so the next call rebuilds it.
328
+
329
+ Exists for tests that install a fake adapter or manipulate the entry-point
330
+ environment; nothing in production should need it.
331
+ """
332
+ global _registry
333
+ with _registry_lock:
334
+ _registry = None
335
+
336
+
337
+ def select_adapter(
338
+ stream: IO[bytes],
339
+ *,
340
+ filename: str | None = None,
341
+ content_type: str | None = None,
342
+ explicit_format: str | None = None,
343
+ ) -> tuple[ReportAdapter, float]:
344
+ """Pick the adapter for one input, honouring ``--format`` above all else.
345
+
346
+ An explicit format always wins, even when the content plainly looks like
347
+ something else: the user asked for a specific parser and is entitled to the
348
+ specific parser's error message rather than a silent substitution. It is
349
+ reported with confidence ``1.0`` because there was nothing to guess.
350
+ """
351
+ registry = get_registry()
352
+ if explicit_format and explicit_format.strip():
353
+ return registry.get(explicit_format), 1.0
354
+ return registry.detect(stream, filename, content_type)
@@ -0,0 +1,263 @@
1
+ """The adapter protocol: how a report format becomes Test Base events.
2
+
3
+ An adapter's whole job is to turn bytes into a stream of
4
+ :class:`~test_base.domain.events.DomainEvent`. It does not touch the database, it
5
+ does not know about HTTP, and it does not decide what a run is called — that
6
+ comes in on the :class:`ParseContext`. Two consequences: an adapter is trivially
7
+ unit-testable against a fixture file, and the file-import path and the live
8
+ publishing path share every line of code after the adapter returns.
9
+
10
+ Writing one
11
+ -----------
12
+
13
+ Implement :class:`ReportAdapter` (a ``Protocol`` — no base class to inherit,
14
+ though :class:`BaseAdapter` is there if you want the helpers), then register it::
15
+
16
+ [project.entry-points."test_base.adapters"]
17
+ my-format = "my_package.adapter:MyAdapter"
18
+
19
+ Test Base's own two adapters are registered exactly this way. There is no
20
+ privileged built-in path — see ``docs/adapters.md`` for the full guide.
21
+
22
+ Detection
23
+ ---------
24
+
25
+ :meth:`ReportAdapter.detect` returns a confidence in ``[0.0, 1.0]``:
26
+
27
+ ====== ==========================================================
28
+ 0.0 definitely not mine
29
+ 0.3 the extension or content type fits, nothing else checked
30
+ 0.6 the content sniffs right (root element, required keys)
31
+ 0.9 the content is unmistakably mine (namespace, generator tag)
32
+ 1.0 the content declares itself as mine (``"kind": "test-base-..."``)
33
+ ====== ==========================================================
34
+
35
+ The registry picks the highest score above :data:`MIN_CONFIDENCE`; ties are
36
+ broken by ``priority`` and then by name, so the choice is deterministic. An
37
+ explicit ``--format`` skips detection entirely.
38
+
39
+ ``detect`` must not consume the stream: it is handed a seekable stream and the
40
+ registry rewinds between adapters, but an adapter that reads gigabytes to decide
41
+ will make every import slow. Read a few kilobytes.
42
+ """
43
+
44
+ from __future__ import annotations
45
+
46
+ import contextlib
47
+ import uuid
48
+ from collections.abc import Iterable, Iterator
49
+ from dataclasses import dataclass, field
50
+ from typing import IO, Any, Protocol, runtime_checkable
51
+
52
+ from test_base.domain.events import DomainEvent
53
+ from test_base.domain.models import (
54
+ ParserWarning,
55
+ RunContext,
56
+ TestType,
57
+ TriggerType,
58
+ WarningSeverity,
59
+ )
60
+
61
+ __all__ = [
62
+ "MIN_CONFIDENCE",
63
+ "SNIFF_BYTES",
64
+ "BaseAdapter",
65
+ "ParseContext",
66
+ "ReportAdapter",
67
+ "WarningCollector",
68
+ ]
69
+
70
+ #: A format must score at least this to be selected by auto-detection.
71
+ MIN_CONFIDENCE = 0.3
72
+
73
+ #: How much of the head of a file an adapter should look at in ``detect``.
74
+ SNIFF_BYTES = 8192
75
+
76
+
77
+ @dataclass(slots=True)
78
+ class ParseContext:
79
+ """Everything an adapter needs that is not in the file.
80
+
81
+ The metadata a user supplies on the command line or in the REST request —
82
+ which project this is, which team owns it, what environment it ran in. An
83
+ adapter merges what the file knows with what the context says; where they
84
+ conflict, the context wins, because the human typing it has more information
85
+ than the file does.
86
+ """
87
+
88
+ workspace_id: uuid.UUID
89
+ project_key: str
90
+ run_id: uuid.UUID = field(default_factory=uuid.uuid4)
91
+ name: str | None = None
92
+ team: str | None = None
93
+ component: str | None = None
94
+ test_type: TestType = TestType.OTHER
95
+ trigger: TriggerType = TriggerType.UNKNOWN
96
+ context: RunContext = field(default_factory=RunContext)
97
+ tags: list[str] = field(default_factory=list)
98
+ metadata: dict[str, Any] = field(default_factory=dict)
99
+ source: str = "urn:test-base:import"
100
+ filename: str | None = None
101
+ #: Longest text kept per field before truncation; mirrors
102
+ #: ``Settings.max_text_field_bytes`` so adapters never build a 40 MB string.
103
+ max_text_bytes: int = 256 * 1024
104
+ #: Collects everything the adapter could not represent exactly.
105
+ warnings: WarningCollector = field(default_factory=lambda: WarningCollector())
106
+ #: Per-run sequence counter. Private; use :meth:`next_sequence`.
107
+ _sequence: int = field(default=0, repr=False)
108
+
109
+ def next_sequence(self) -> int:
110
+ """Hand out the next per-run sequence number.
111
+
112
+ Adapters call this instead of counting themselves, so events emitted by
113
+ nested generators still come out strictly increasing, and a sub-parser
114
+ handed the same context cannot restart the numbering.
115
+ """
116
+ self._sequence += 1
117
+ return self._sequence
118
+
119
+
120
+ class WarningCollector:
121
+ """Accumulates :class:`ParserWarning` s during a parse.
122
+
123
+ Bounded, because a pathological file should produce a bounded response: past
124
+ the cap it counts what it drops and says so in a final warning.
125
+ """
126
+
127
+ MAX = 500
128
+
129
+ def __init__(self) -> None:
130
+ self._warnings: list[ParserWarning] = []
131
+ self._dropped = 0
132
+
133
+ def add(
134
+ self,
135
+ code: str,
136
+ message: str,
137
+ *,
138
+ location: str | None = None,
139
+ severity: WarningSeverity = WarningSeverity.WARNING,
140
+ **detail: Any,
141
+ ) -> None:
142
+ if len(self._warnings) >= self.MAX:
143
+ self._dropped += 1
144
+ return
145
+ self._warnings.append(
146
+ ParserWarning(
147
+ code=code,
148
+ message=message[:512],
149
+ severity=severity,
150
+ location=location,
151
+ detail=detail,
152
+ )
153
+ )
154
+
155
+ def info(self, code: str, message: str, **kwargs: Any) -> None:
156
+ self.add(code, message, severity=WarningSeverity.INFO, **kwargs)
157
+
158
+ def to_list(self) -> list[ParserWarning]:
159
+ out = list(self._warnings)
160
+ if self._dropped:
161
+ out.append(
162
+ ParserWarning(
163
+ code="warnings_truncated",
164
+ message=f"{self._dropped} further warnings were not recorded.",
165
+ severity=WarningSeverity.INFO,
166
+ )
167
+ )
168
+ return out
169
+
170
+ def __len__(self) -> int:
171
+ return len(self._warnings) + self._dropped
172
+
173
+ def __bool__(self) -> bool:
174
+ return bool(self._warnings) or bool(self._dropped)
175
+
176
+
177
+ @runtime_checkable
178
+ class ReportAdapter(Protocol):
179
+ """What every report adapter implements.
180
+
181
+ ``name`` must be unique across installed adapters and stable — it is stored
182
+ on the run and shown to the user, and ``--format <name>`` selects it.
183
+ """
184
+
185
+ name: str
186
+ """Stable identifier, e.g. ``junit-xml``."""
187
+
188
+ def detect(self, stream: IO[bytes], filename: str | None, content_type: str | None) -> float:
189
+ """Score how likely it is that this adapter can parse the input.
190
+
191
+ Must leave the stream position where it found it or accept that the
192
+ registry will rewind. Must not raise: return ``0.0`` instead.
193
+ """
194
+ ...
195
+
196
+ def parse(self, stream: IO[bytes], context: ParseContext) -> Iterable[DomainEvent]:
197
+ """Turn the input into domain events.
198
+
199
+ May raise :class:`~test_base.errors.AdapterError` for input it recognised
200
+ but cannot parse. Anything it can parse but not represent exactly should
201
+ be a warning on ``context.warnings``, not an exception.
202
+ """
203
+ ...
204
+
205
+
206
+ class BaseAdapter:
207
+ """Optional convenience base with the boring parts already written.
208
+
209
+ Provides the extension/content-type half of detection and a safe stream
210
+ sniffer. Inheriting is not required — :class:`ReportAdapter` is structural.
211
+ """
212
+
213
+ name: str = "base"
214
+ display_name: str = "Base"
215
+ #: File extensions this adapter recognises, lowercase and dotted.
216
+ extensions: tuple[str, ...] = ()
217
+ #: MIME types this adapter recognises.
218
+ content_types: tuple[str, ...] = ()
219
+ #: Tie-break when two adapters score the same. Higher wins.
220
+ priority: int = 0
221
+ #: Shown by ``test-base formats`` and in the unknown-format error.
222
+ description: str = ""
223
+
224
+ def sniff(self, stream: IO[bytes], size: int = SNIFF_BYTES) -> bytes:
225
+ """Read the head of the stream and rewind."""
226
+ try:
227
+ position = stream.tell()
228
+ except (OSError, AttributeError): # pragma: no cover - non-seekable
229
+ position = 0
230
+ head = stream.read(size) or b""
231
+ with contextlib.suppress(OSError, AttributeError): # pragma: no cover - non-seekable
232
+ stream.seek(position)
233
+ return head
234
+
235
+ def hint_score(self, filename: str | None, content_type: str | None) -> float:
236
+ """The extension/content-type half of a detection score."""
237
+ score = 0.0
238
+ if filename:
239
+ lowered = filename.lower()
240
+ if any(lowered.endswith(extension) for extension in self.extensions):
241
+ score = 0.3
242
+ if content_type:
243
+ base = content_type.split(";", 1)[0].strip().lower()
244
+ if base in self.content_types:
245
+ score = max(score, 0.3)
246
+ return score
247
+
248
+ def detect(self, stream: IO[bytes], filename: str | None, content_type: str | None) -> float:
249
+ """Hint-only detection. Subclasses override to sniff the content."""
250
+ return self.hint_score(filename, content_type)
251
+
252
+ def parse(self, stream: IO[bytes], context: ParseContext) -> Iterator[DomainEvent]:
253
+ raise NotImplementedError # pragma: no cover - abstract
254
+
255
+ def describe(self) -> dict[str, Any]:
256
+ """The row this adapter contributes to ``test-base formats``."""
257
+ return {
258
+ "name": self.name,
259
+ "display_name": self.display_name,
260
+ "description": self.description,
261
+ "extensions": list(self.extensions),
262
+ "content_types": list(self.content_types),
263
+ }