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.
- test_base/__init__.py +20 -0
- test_base/adapters/__init__.py +354 -0
- test_base/adapters/base.py +263 -0
- test_base/adapters/canonical_json.py +1088 -0
- test_base/adapters/junit_xml.py +1272 -0
- test_base/api/__init__.py +0 -0
- test_base/api/app.py +314 -0
- test_base/api/deps.py +178 -0
- test_base/api/routes/__init__.py +0 -0
- test_base/api/routes/failures.py +104 -0
- test_base/api/routes/health.py +35 -0
- test_base/api/routes/imports.py +143 -0
- test_base/api/routes/queries.py +295 -0
- test_base/api/routes/retention.py +130 -0
- test_base/api/routes/runs.py +147 -0
- test_base/api/routes/server.py +65 -0
- test_base/api/routes/stream.py +117 -0
- test_base/api/schemas.py +390 -0
- test_base/api/security.py +183 -0
- test_base/cli/__init__.py +125 -0
- test_base/cli/commands/__init__.py +0 -0
- test_base/cli/commands/db.py +76 -0
- test_base/cli/commands/demo.py +103 -0
- test_base/cli/commands/formats.py +41 -0
- test_base/cli/commands/ingest.py +119 -0
- test_base/cli/commands/init.py +738 -0
- test_base/cli/commands/prune.py +146 -0
- test_base/cli/commands/publish.py +133 -0
- test_base/cli/commands/serve.py +118 -0
- test_base/cli/commands/token.py +97 -0
- test_base/cli/options.py +189 -0
- test_base/cli/render.py +223 -0
- test_base/config.py +519 -0
- test_base/demo/__init__.py +0 -0
- test_base/demo/evidence.py +447 -0
- test_base/demo/seed.py +628 -0
- test_base/domain/__init__.py +61 -0
- test_base/domain/events.py +422 -0
- test_base/domain/failures.py +327 -0
- test_base/domain/identity.py +205 -0
- test_base/domain/metrics.py +176 -0
- test_base/domain/models.py +947 -0
- test_base/domain/status.py +246 -0
- test_base/errors.py +136 -0
- test_base/logging.py +174 -0
- test_base/py.typed +0 -0
- test_base/sdk/__init__.py +28 -0
- test_base/sdk/client.py +607 -0
- test_base/service/__init__.py +0 -0
- test_base/service/bus.py +331 -0
- test_base/service/coalesce.py +133 -0
- test_base/service/imports.py +552 -0
- test_base/service/retention.py +640 -0
- test_base/service/runs.py +394 -0
- test_base/service/runtime.py +123 -0
- test_base/storage/__init__.py +41 -0
- test_base/storage/artifacts.py +347 -0
- test_base/storage/base.py +350 -0
- test_base/storage/db.py +595 -0
- test_base/storage/failures.py +321 -0
- test_base/storage/locks.py +104 -0
- test_base/storage/migrations/env.py +108 -0
- test_base/storage/migrations/script.py.mako +26 -0
- test_base/storage/migrations/versions/0001_initial.py +289 -0
- test_base/storage/migrations/versions/0002_retention_indexes.py +38 -0
- test_base/storage/migrations/versions/0003_postgresql_bigint.py +74 -0
- test_base/storage/migrations/versions/0004_run_shards.py +37 -0
- test_base/storage/migrations/versions/0005_failure_groups.py +206 -0
- test_base/storage/models.py +560 -0
- test_base/storage/repositories.py +2481 -0
- test_base/storage/uow.py +138 -0
- test_base/version.py +17 -0
- test_base/web/assets/css/app.css +3567 -0
- test_base/web/assets/favicon.svg +5 -0
- test_base/web/assets/js/00-util.js +829 -0
- test_base/web/assets/js/05-windows.js +551 -0
- test_base/web/assets/js/10-provider.js +396 -0
- test_base/web/assets/js/12-live-provider.js +804 -0
- test_base/web/assets/js/20-charts.js +715 -0
- test_base/web/assets/js/30-store.js +793 -0
- test_base/web/assets/js/40-components.js +2141 -0
- test_base/web/assets/js/42-timeline.js +629 -0
- test_base/web/assets/js/50-view-overview.js +747 -0
- test_base/web/assets/js/52-view-analytics.js +842 -0
- test_base/web/assets/js/53-view-suites.js +508 -0
- test_base/web/assets/js/54-view-metrics.js +438 -0
- test_base/web/assets/js/55-view-runs.js +244 -0
- test_base/web/assets/js/56-view-evidence.js +703 -0
- test_base/web/assets/js/57-view-failures.js +596 -0
- test_base/web/assets/js/60-view-run.js +788 -0
- test_base/web/assets/js/65-view-test.js +402 -0
- test_base/web/assets/js/70-view-settings.js +524 -0
- test_base/web/assets/js/75-view-help.js +554 -0
- test_base/web/assets/js/80-settings.js +99 -0
- test_base/web/assets/js/85-activity.js +727 -0
- test_base/web/assets/js/90-app.js +595 -0
- test_base/web/assets/manifest.json +70 -0
- test_base/web/index.html +210 -0
- test_base-0.1.1.dist-info/METADATA +285 -0
- test_base-0.1.1.dist-info/RECORD +103 -0
- test_base-0.1.1.dist-info/WHEEL +4 -0
- test_base-0.1.1.dist-info/entry_points.txt +6 -0
- 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
|
+
}
|