embeddedci-openhtf 2.1.0__tar.gz → 2.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/CHANGELOG.md +14 -0
  2. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/PKG-INFO +36 -9
  3. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/README.md +34 -7
  4. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/pyproject.toml +2 -2
  5. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/src/embeddedci_openhtf/plug.py +40 -15
  6. embeddedci_openhtf-2.3.0/tests/conftest.py +25 -0
  7. embeddedci_openhtf-2.3.0/tests/test_docs_coverage.py +62 -0
  8. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_persistent.py +37 -3
  9. embeddedci_openhtf-2.1.0/tests/conftest.py +0 -11
  10. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/.gitignore +0 -0
  11. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/LICENSE +0 -0
  12. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/examples/analog_loopback.py +0 -0
  13. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/examples/flash_and_boot.py +0 -0
  14. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/examples/serial_smoke.py +0 -0
  15. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/examples/station.py +0 -0
  16. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/src/embeddedci_openhtf/__init__.py +0 -0
  17. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/src/embeddedci_openhtf/analog.py +0 -0
  18. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/src/embeddedci_openhtf/measurements.py +0 -0
  19. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/src/embeddedci_openhtf/phases.py +0 -0
  20. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/src/embeddedci_openhtf/pins.py +0 -0
  21. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/src/embeddedci_openhtf/power.py +0 -0
  22. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/_fake.py +0 -0
  23. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_analog.py +0 -0
  24. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_e2e_openhtf.py +0 -0
  25. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_measurements.py +0 -0
  26. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_phases.py +0 -0
  27. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_pins.py +0 -0
  28. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_plug.py +0 -0
  29. {embeddedci_openhtf-2.1.0 → embeddedci_openhtf-2.3.0}/tests/test_power.py +0 -0
@@ -1,5 +1,19 @@
1
1
  # Changelog — `embeddedci-openhtf`
2
2
 
3
+ ## 2.3.0
4
+
5
+ - Needs `embeddedci` 2.12.0 or later (was 2.4), the SDK whose `usb` connection reaches the USB
6
+ network adapter these docs describe.
7
+ - Docs: connection `usb` reaches the pod's USB network adapter (full API) on firmware 3.9.0 and
8
+ later, through the `embeddedci` SDK of the same release; a serial device path stays the console.
9
+
10
+ ## 2.2.0
11
+
12
+ - Persistent plugs (`benchpod_plug(..., persistent=True)`) are pooled by their connection
13
+ settings (the connection and the `BenchPod` keyword arguments) instead of by plug class. Two
14
+ `benchpod_plug` calls for the same pod now share one connection (a pod serves one client at a
15
+ time), and a plug whose OpenHTF conf or environment changes gets a connection that matches.
16
+
3
17
  ## 2.1.0
4
18
 
5
19
  - 4-20 mA terminals: `current_out_phase` (and the `current_out` helper) holds a current on the
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: embeddedci-openhtf
3
- Version: 2.1.0
3
+ Version: 2.3.0
4
4
  Summary: OpenHTF plug for driving an EmbeddedCI BenchPod directly over TCP or serial (no cloud)
5
5
  Project-URL: Homepage, https://embeddedci.com
6
6
  Project-URL: Repository, https://github.com/embeddedci-com/embeddedci-python
@@ -18,7 +18,7 @@ Classifier: Programming Language :: Python :: 3.12
18
18
  Classifier: Programming Language :: Python :: 3.13
19
19
  Classifier: Topic :: Software Development :: Testing
20
20
  Requires-Python: >=3.10
21
- Requires-Dist: embeddedci<3,>=2.4
21
+ Requires-Dist: embeddedci<3,>=2.12.0
22
22
  Requires-Dist: openhtf>=1.6
23
23
  Provides-Extra: dev
24
24
  Requires-Dist: pytest>=7.0; extra == 'dev'
@@ -79,7 +79,8 @@ Connection forms (all **direct**, never cloud):
79
79
  | Form | Example |
80
80
  | --- | --- |
81
81
  | TCP `host[:port]` | `benchpod_plug("192.168.1.50:8080")` |
82
- | Serial device path | `benchpod_plug("/dev/ttyACM0")` / `benchpod_plug("COM5")` |
82
+ | USB, auto-detected | `benchpod_plug("usb")` (the pod's USB network adapter on firmware 3.9.0+, else its console) |
83
+ | Serial device path | `benchpod_plug("/dev/ttyACM0")` / `benchpod_plug("COM5")` (the console only) |
83
84
  | `BENCHPOD_CONNECTION` env | `benchpod_plug()` (unbound) |
84
85
  | OpenHTF config | `htf.conf.load(benchpod_connection="...")` then `@htf.plug(bench=BenchPodPlug)` |
85
86
 
@@ -120,7 +121,7 @@ unset for analog-only tests that don't touch the LA bank.
120
121
 
121
122
  | Key | Default | Meaning |
122
123
  | --- | --- | --- |
123
- | `benchpod_connection` | `None` → `BENCHPOD_CONNECTION` | `host[:port]`, a serial device path, or `serial` |
124
+ | `benchpod_connection` | `None` → `BENCHPOD_CONNECTION` | `host[:port]`, a serial device path, `usb`, or `serial` |
124
125
  | `benchpod_timeout` | `30.0` | Transport timeout in seconds |
125
126
  | `benchpod_la_voltage` | `None` → `BENCHPOD_LA_VOLTAGE` | LA I/O-bank voltage in volts (`1.8` or `3.3`) |
126
127
 
@@ -183,6 +184,23 @@ def boot_and_rail(test, bench):
183
184
  test.measurements.rail_v = bench.power_status().rail(1).bus_voltage # volts
184
185
  ```
185
186
 
187
+ `flash_ok_measurement(name="flash_ok")` and `uart_matched_measurement(name="boot_ok")` are the
188
+ matching declarations, so a custom flash phase needs no hand-written measurement:
189
+
190
+ ```python
191
+ from embeddedci_openhtf import flash_ok_measurement, record_flash
192
+
193
+ @htf.measures(flash_ok_measurement())
194
+ @htf.plug(bench=bench)
195
+ def flash(test, bench):
196
+ result = bench.flash(file="fw.elf", target="target/stm32f4x.cfg",
197
+ swclk=11, swdio=12, nreset=True, check=False)
198
+ record_flash(test, result) # sets flash_ok and attaches openocd.log
199
+ ```
200
+
201
+ The recorders never raise on a bad result: they record the failing value, so the measurement (not
202
+ an exception) decides the phase outcome, and the OpenOCD or UART output is always attached.
203
+
186
204
  ### Analog steps
187
205
 
188
206
  The pod's DAC output and ADC input are exposed as phases (and low-level helpers).
@@ -245,9 +263,10 @@ Notes:
245
263
  `current_out_phase` switches them off, and a voltage waveform also moves the loop.
246
264
  `signal_generate_phase` and `dac_replay_phase` take `dac_path="current_out"` for a waveform in
247
265
  amps. Needs firmware 3.4.0.
248
- - Use a TCP connection. The STM32 pod's USB serial console is a text shell without a JSON
249
- mode, so over serial only `power_phase`, status and the LA voltage work; flashing, UART,
250
- analog and replay phases need TCP (or the cloud).
266
+ - Use a TCP connection, or `usb` on firmware 3.9.0 and later (it reaches the pod's USB network
267
+ adapter, which carries the full API, unless Wi-Fi is configured on the pod). The STM32 pod's
268
+ USB serial console is a text shell without a JSON mode, so over the console only `power_phase`,
269
+ status and the LA voltage work; flashing, UART, analog and replay phases need TCP (or the cloud).
251
270
 
252
271
  The low-level helpers take a connected `BenchPod` or the injected plug:
253
272
  `signal_generate`, `signal_stop`, `analog_path`, `dac_output`, `current_out`, `adc_read`,
@@ -321,8 +340,10 @@ def ripple_under_load(test, bench):
321
340
  By default the plug opens a connection per `Test.execute()` and closes it at
322
341
  teardown. On a station cycling many DUTs back-to-back, pass `persistent=True` to
323
342
  keep **one** connection open across executions (re-checked with a ping each run,
324
- reconnected if it dropped). Reuse the *same* plug class for every execution, and
325
- close it once at the end:
343
+ reconnected if it dropped). Persistent plugs are pooled by their connection settings (the
344
+ connection and the `BenchPod` keyword arguments), so two `benchpod_plug(..., persistent=True)`
345
+ calls for the same pod share one connection, and a plug whose OpenHTF conf or environment changes
346
+ gets a connection that matches. Close them once at the end:
326
347
 
327
348
  ```python
328
349
  import openhtf as htf
@@ -341,6 +362,12 @@ finally:
341
362
  close_persistent_benchpods() # also runs automatically at process exit
342
363
  ```
343
364
 
365
+ `benchpod_plug(connection=None, *, persistent=False, health_check=True, **pod_kwargs)` returns a
366
+ `BenchPodPlug` subclass with those values as class attributes (`connection`, `persistent`,
367
+ `health_check`, `pod_kwargs`). `health_check=False` skips the ping before a pooled connection is
368
+ reused. Inside a phase, `bench.pod` is the connected `BenchPod`; any other attribute the plug does
369
+ not have is looked up on it, which is why `bench.power_on()` works.
370
+
344
371
  ## Examples
345
372
 
346
373
  * [`examples/flash_and_boot.py`](examples/flash_and_boot.py) — flash over SWD then
@@ -53,7 +53,8 @@ Connection forms (all **direct**, never cloud):
53
53
  | Form | Example |
54
54
  | --- | --- |
55
55
  | TCP `host[:port]` | `benchpod_plug("192.168.1.50:8080")` |
56
- | Serial device path | `benchpod_plug("/dev/ttyACM0")` / `benchpod_plug("COM5")` |
56
+ | USB, auto-detected | `benchpod_plug("usb")` (the pod's USB network adapter on firmware 3.9.0+, else its console) |
57
+ | Serial device path | `benchpod_plug("/dev/ttyACM0")` / `benchpod_plug("COM5")` (the console only) |
57
58
  | `BENCHPOD_CONNECTION` env | `benchpod_plug()` (unbound) |
58
59
  | OpenHTF config | `htf.conf.load(benchpod_connection="...")` then `@htf.plug(bench=BenchPodPlug)` |
59
60
 
@@ -94,7 +95,7 @@ unset for analog-only tests that don't touch the LA bank.
94
95
 
95
96
  | Key | Default | Meaning |
96
97
  | --- | --- | --- |
97
- | `benchpod_connection` | `None` → `BENCHPOD_CONNECTION` | `host[:port]`, a serial device path, or `serial` |
98
+ | `benchpod_connection` | `None` → `BENCHPOD_CONNECTION` | `host[:port]`, a serial device path, `usb`, or `serial` |
98
99
  | `benchpod_timeout` | `30.0` | Transport timeout in seconds |
99
100
  | `benchpod_la_voltage` | `None` → `BENCHPOD_LA_VOLTAGE` | LA I/O-bank voltage in volts (`1.8` or `3.3`) |
100
101
 
@@ -157,6 +158,23 @@ def boot_and_rail(test, bench):
157
158
  test.measurements.rail_v = bench.power_status().rail(1).bus_voltage # volts
158
159
  ```
159
160
 
161
+ `flash_ok_measurement(name="flash_ok")` and `uart_matched_measurement(name="boot_ok")` are the
162
+ matching declarations, so a custom flash phase needs no hand-written measurement:
163
+
164
+ ```python
165
+ from embeddedci_openhtf import flash_ok_measurement, record_flash
166
+
167
+ @htf.measures(flash_ok_measurement())
168
+ @htf.plug(bench=bench)
169
+ def flash(test, bench):
170
+ result = bench.flash(file="fw.elf", target="target/stm32f4x.cfg",
171
+ swclk=11, swdio=12, nreset=True, check=False)
172
+ record_flash(test, result) # sets flash_ok and attaches openocd.log
173
+ ```
174
+
175
+ The recorders never raise on a bad result: they record the failing value, so the measurement (not
176
+ an exception) decides the phase outcome, and the OpenOCD or UART output is always attached.
177
+
160
178
  ### Analog steps
161
179
 
162
180
  The pod's DAC output and ADC input are exposed as phases (and low-level helpers).
@@ -219,9 +237,10 @@ Notes:
219
237
  `current_out_phase` switches them off, and a voltage waveform also moves the loop.
220
238
  `signal_generate_phase` and `dac_replay_phase` take `dac_path="current_out"` for a waveform in
221
239
  amps. Needs firmware 3.4.0.
222
- - Use a TCP connection. The STM32 pod's USB serial console is a text shell without a JSON
223
- mode, so over serial only `power_phase`, status and the LA voltage work; flashing, UART,
224
- analog and replay phases need TCP (or the cloud).
240
+ - Use a TCP connection, or `usb` on firmware 3.9.0 and later (it reaches the pod's USB network
241
+ adapter, which carries the full API, unless Wi-Fi is configured on the pod). The STM32 pod's
242
+ USB serial console is a text shell without a JSON mode, so over the console only `power_phase`,
243
+ status and the LA voltage work; flashing, UART, analog and replay phases need TCP (or the cloud).
225
244
 
226
245
  The low-level helpers take a connected `BenchPod` or the injected plug:
227
246
  `signal_generate`, `signal_stop`, `analog_path`, `dac_output`, `current_out`, `adc_read`,
@@ -295,8 +314,10 @@ def ripple_under_load(test, bench):
295
314
  By default the plug opens a connection per `Test.execute()` and closes it at
296
315
  teardown. On a station cycling many DUTs back-to-back, pass `persistent=True` to
297
316
  keep **one** connection open across executions (re-checked with a ping each run,
298
- reconnected if it dropped). Reuse the *same* plug class for every execution, and
299
- close it once at the end:
317
+ reconnected if it dropped). Persistent plugs are pooled by their connection settings (the
318
+ connection and the `BenchPod` keyword arguments), so two `benchpod_plug(..., persistent=True)`
319
+ calls for the same pod share one connection, and a plug whose OpenHTF conf or environment changes
320
+ gets a connection that matches. Close them once at the end:
300
321
 
301
322
  ```python
302
323
  import openhtf as htf
@@ -315,6 +336,12 @@ finally:
315
336
  close_persistent_benchpods() # also runs automatically at process exit
316
337
  ```
317
338
 
339
+ `benchpod_plug(connection=None, *, persistent=False, health_check=True, **pod_kwargs)` returns a
340
+ `BenchPodPlug` subclass with those values as class attributes (`connection`, `persistent`,
341
+ `health_check`, `pod_kwargs`). `health_check=False` skips the ping before a pooled connection is
342
+ reused. Inside a phase, `bench.pod` is the connected `BenchPod`; any other attribute the plug does
343
+ not have is looked up on it, which is why `bench.power_on()` works.
344
+
318
345
  ## Examples
319
346
 
320
347
  * [`examples/flash_and_boot.py`](examples/flash_and_boot.py) — flash over SWD then
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "embeddedci-openhtf"
7
- version = "2.1.0"
7
+ version = "2.3.0"
8
8
  description = "OpenHTF plug for driving an EmbeddedCI BenchPod directly over TCP or serial (no cloud)"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -23,7 +23,7 @@ classifiers = [
23
23
  "Topic :: Software Development :: Testing",
24
24
  ]
25
25
  dependencies = [
26
- "embeddedci>=2.4,<3",
26
+ "embeddedci>=2.12.0,<3",
27
27
  "openhtf>=1.6",
28
28
  ]
29
29
 
@@ -54,6 +54,7 @@ station that cycles many DUTs back-to-back, pass ``persistent=True`` to
54
54
  :func:`benchpod_plug` to keep one connection open across executions (re-checked
55
55
  with a ping each run and reconnected if it dropped); close it explicitly with
56
56
  :func:`close_persistent_benchpods` (also run automatically at process exit).
57
+ Persistent plugs with the same connection settings share one connection.
57
58
 
58
59
  Unknown attribute access proxies to the underlying
59
60
  :class:`~embeddedci.benchpod.BenchPod`, so ``bench.flash(...)`` /
@@ -67,7 +68,7 @@ import atexit
67
68
  import os
68
69
  import threading
69
70
  from types import MappingProxyType
70
- from typing import Any, Dict, Mapping, Optional
71
+ from typing import Any, Dict, Hashable, Mapping, Optional
71
72
 
72
73
  import openhtf as htf
73
74
  from openhtf.plugs import BasePlug
@@ -105,12 +106,36 @@ htf.conf.declare(
105
106
  default_value=None,
106
107
  )
107
108
 
108
- # Process-wide pool of persistent connections, keyed by the bound plug class (one
109
- # per benchpod_plug(persistent=True) call). Survives across test executions.
110
- _PERSISTENT_POOL: Dict[type, BenchPod] = {}
109
+ # Process-wide pool of persistent connections, keyed by the connection settings (the connection
110
+ # and the BenchPod keywords, see _pool_key). Plugs with the same settings share one connection,
111
+ # which a pod that serves one client at a time needs, and a plug whose settings change (an OpenHTF
112
+ # conf value, an env var) gets a connection that matches them. Survives across test executions.
113
+ _PERSISTENT_POOL: Dict[Hashable, BenchPod] = {}
111
114
  _PERSISTENT_LOCK = threading.Lock()
112
115
 
113
116
 
117
+ def _key_part(value: Any) -> Hashable:
118
+ """A hashable stand-in for one setting: the value itself when hashable and plain, its
119
+ contents for a dict, list or set (a wiring map), and its identity for any other object (an
120
+ injected transport, a Wiring), which is the same pod only when it is the same object."""
121
+ if value is None or isinstance(value, (bool, int, float, str, bytes)):
122
+ return value
123
+ if isinstance(value, Mapping):
124
+ return ("map", tuple(sorted((str(k), _key_part(v)) for k, v in value.items())))
125
+ if isinstance(value, (list, tuple)):
126
+ return ("seq", tuple(_key_part(v) for v in value))
127
+ if isinstance(value, (set, frozenset)):
128
+ return ("set", tuple(sorted(repr(_key_part(v)) for v in value)))
129
+ if isinstance(value, os.PathLike):
130
+ return ("path", os.fspath(value))
131
+ return ("obj", id(value))
132
+
133
+
134
+ def _pool_key(conn: Optional[str], pod_kwargs: Mapping[str, Any]) -> Hashable:
135
+ """The pool key for a connection and its BenchPod keywords."""
136
+ return (conn, tuple(sorted((k, _key_part(v)) for k, v in pod_kwargs.items())))
137
+
138
+
114
139
  def _conf_value(name: str) -> Any:
115
140
  """The OpenHTF conf value for ``name``, or ``None`` when it has none."""
116
141
  try:
@@ -138,12 +163,13 @@ def close_persistent_benchpods() -> None:
138
163
  atexit.register(close_persistent_benchpods)
139
164
 
140
165
 
141
- def _acquire_persistent(cls: type, conn: Optional[str],
142
- pod_kwargs: Mapping[str, Any], health_check: bool) -> BenchPod:
143
- """Return the pooled connection for ``cls``, opening (or reopening, if a
166
+ def _acquire_persistent(conn: Optional[str], pod_kwargs: Mapping[str, Any],
167
+ health_check: bool) -> BenchPod:
168
+ """Return the pooled connection for these settings, opening (or reopening, if a
144
169
  health-check ping fails) it as needed."""
170
+ key = _pool_key(conn, pod_kwargs)
145
171
  with _PERSISTENT_LOCK:
146
- pod = _PERSISTENT_POOL.get(cls)
172
+ pod = _PERSISTENT_POOL.get(key)
147
173
  if pod is not None and health_check:
148
174
  try:
149
175
  pod.ping() # cheap liveness check; reconnect if the link died
@@ -153,10 +179,10 @@ def _acquire_persistent(cls: type, conn: Optional[str],
153
179
  except Exception:
154
180
  pass
155
181
  pod = None
156
- _PERSISTENT_POOL.pop(cls, None)
182
+ _PERSISTENT_POOL.pop(key, None)
157
183
  if pod is None:
158
184
  pod = BenchPod(conn, **pod_kwargs)
159
- _PERSISTENT_POOL[cls] = pod
185
+ _PERSISTENT_POOL[key] = pod
160
186
  return pod
161
187
 
162
188
 
@@ -214,8 +240,7 @@ class BenchPodPlug(BasePlug):
214
240
  pod_kwargs.setdefault("la_voltage", float(benchpod_la_voltage))
215
241
  if cls.persistent:
216
242
  #: The connected SDK client (shared, kept open across executions).
217
- self.pod: BenchPod = _acquire_persistent(
218
- cls, conn, pod_kwargs, cls.health_check)
243
+ self.pod: BenchPod = _acquire_persistent(conn, pod_kwargs, cls.health_check)
219
244
  else:
220
245
  # Direct TCP/serial connections never lease.
221
246
  self.pod = BenchPod(conn, **pod_kwargs)
@@ -258,9 +283,9 @@ def benchpod_plug(connection: Optional[str] = None, *, persistent: bool = False,
258
283
  @htf.plug(bench=benchpod_plug("/dev/ttyACM0"))
259
284
  def phase(test, bench): ...
260
285
 
261
- Set ``persistent=True`` to keep one connection open across test executions
262
- (reuse the *same* returned class for every ``Test.execute()`` so they share
263
- it); see :func:`close_persistent_benchpods`. Extra keyword args are forwarded
286
+ Set ``persistent=True`` to keep one connection open across test executions;
287
+ persistent plugs with the same connection and keyword arguments share it,
288
+ whichever ``benchpod_plug`` call made them. See :func:`close_persistent_benchpods`. Extra keyword args are forwarded
264
289
  to ``BenchPod(...)``: ``la_voltage=`` (volts), ``wiring=`` (a dict, a
265
290
  ``.json``/``.toml`` path or a :class:`~embeddedci.benchpod.Wiring`, which then
266
291
  supplies the channels, baud and power rail a phase leaves out), ``timeout=``
@@ -0,0 +1,25 @@
1
+ """Make the package importable when running the tests from a source checkout
2
+ without an editable install.
3
+
4
+ Set EMBEDDEDCI_TEST_INSTALLED=1 to test the installed package instead (e.g. a built wheel)."""
5
+
6
+ import os
7
+ import sys
8
+
9
+ import pytest
10
+
11
+ _SRC = os.path.join(os.path.dirname(os.path.dirname(__file__)), "src")
12
+ if os.environ.get("EMBEDDEDCI_TEST_INSTALLED") != "1" and _SRC not in sys.path:
13
+ sys.path.insert(0, _SRC)
14
+
15
+
16
+ @pytest.fixture(autouse=True)
17
+ def _isolated_benchpod_cli_config(request, tmp_path_factory, monkeypatch):
18
+ """Unit tests never see this machine's benchpod-cli config (its saved connection) or its
19
+ `benchpod login` session: both change what BenchPod() connects to and where its wiring comes
20
+ from. Hardware tests (e2e, examples) keep them."""
21
+ path = str(request.node.fspath)
22
+ if "e2e" in os.path.basename(path) or os.sep + "e2e" + os.sep in path \
23
+ or os.sep + "examples" + os.sep in path:
24
+ return
25
+ monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path_factory.mktemp("xdg")))
@@ -0,0 +1,62 @@
1
+ """Every public name of embeddedci-openhtf is documented in its README.
2
+
3
+ Covers ``embeddedci_openhtf.__all__``, the public attributes and methods of ``BenchPodPlug``, and
4
+ the OpenHTF conf keys the plug declares. Each must appear inside a code span or code block of
5
+ ``README.md``. A name left out on purpose goes in ``ALLOWLIST`` with the reason.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import inspect
11
+ import re
12
+ from pathlib import Path
13
+ from typing import Dict, List, Set
14
+
15
+ import embeddedci_openhtf
16
+ from embeddedci_openhtf import plug as plug_module
17
+
18
+ README = Path(__file__).resolve().parents[1] / "README.md"
19
+
20
+ #: name -> why it is not in the README.
21
+ ALLOWLIST: Dict[str, str] = {
22
+ "tearDown": "OpenHTF plug lifecycle hook, called by OpenHTF, not by users",
23
+ "__version__": "standard package metadata",
24
+ }
25
+
26
+
27
+ def _code_text() -> str:
28
+ text = README.read_text(encoding="utf-8")
29
+ fenced = re.compile(r"^```.*?^```", re.M | re.S)
30
+ return "\n".join(fenced.findall(text) + re.findall(r"`([^`\n]+)`", fenced.sub("", text)))
31
+
32
+
33
+ def public_names() -> Set[str]:
34
+ names = set(embeddedci_openhtf.__all__)
35
+ for name, value in vars(embeddedci_openhtf.BenchPodPlug).items():
36
+ if not name.startswith("_") and (inspect.isfunction(value) or not callable(value)):
37
+ names.add(name)
38
+ names.add("pod") # set per instance in __init__
39
+ source = inspect.getsource(plug_module)
40
+ names.update(re.findall(r"htf\.conf\.declare\(\s*\"(\w+)\"", source))
41
+ return names
42
+
43
+
44
+ def _missing() -> List[str]:
45
+ text = _code_text()
46
+ return sorted(n for n in public_names() if n not in ALLOWLIST
47
+ and not re.search(r"(?<!\w)" + re.escape(n) + r"(?!\w)", text))
48
+
49
+
50
+ def test_names_are_found():
51
+ assert {"BenchPodPlug", "benchpod_plug", "persistent", "benchpod_timeout"} <= public_names()
52
+
53
+
54
+ def test_every_public_name_is_documented():
55
+ missing = _missing()
56
+ assert not missing, ("names missing from packages/embeddedci-openhtf/README.md (document them "
57
+ "or add them to ALLOWLIST with a reason): " + ", ".join(missing))
58
+
59
+
60
+ def test_allowlist_is_still_needed():
61
+ stale = sorted(n for n in ALLOWLIST if n not in public_names())
62
+ assert not stale, "ALLOWLIST names that are no longer public: " + ", ".join(stale)
@@ -8,7 +8,7 @@ from embeddedci_openhtf import (
8
8
  close_persistent_benchpods,
9
9
  power_phase,
10
10
  )
11
- from embeddedci_openhtf.plug import _PERSISTENT_POOL
11
+ from embeddedci_openhtf.plug import _PERSISTENT_POOL, _pool_key
12
12
  from _fake import FakeTransport
13
13
 
14
14
 
@@ -47,14 +47,48 @@ def test_persistent_reconnects_after_drop():
47
47
  bench = benchpod_plug(transport=tx, persistent=True)
48
48
  try:
49
49
  _run(power_phase(bench, on=True))
50
- pod1 = _PERSISTENT_POOL[bench]
50
+ key = _pool_key(None, {"transport": tx, "timeout": 30.0})
51
+ pod1 = _PERSISTENT_POOL[key]
51
52
  # simulate the link dying: make the health-check ping fail
52
53
  def boom():
53
54
  raise OSError("link dropped")
54
55
  tx.ping = boom
55
56
  _run(power_phase(bench, on=True))
56
57
  # the dead connection was dropped and a fresh BenchPod opened
57
- pod2 = _PERSISTENT_POOL[bench]
58
+ pod2 = _PERSISTENT_POOL[key]
58
59
  assert pod2 is not pod1
59
60
  finally:
60
61
  close_persistent_benchpods()
62
+
63
+
64
+ def test_plugs_with_the_same_settings_share_one_connection():
65
+ tx = FakeTransport()
66
+ first = benchpod_plug(transport=tx, persistent=True, la_voltage=3.3)
67
+ second = benchpod_plug(transport=tx, persistent=True, la_voltage=3.3)
68
+ try:
69
+ _run(power_phase(first, efuse=1, on=True))
70
+ _run(power_phase(second, efuse=1, on=True))
71
+ assert len(_PERSISTENT_POOL) == 1
72
+ assert len(tx.power_calls) == 2
73
+ finally:
74
+ close_persistent_benchpods()
75
+
76
+
77
+ def test_different_settings_get_their_own_connection():
78
+ tx1, tx2 = FakeTransport(), FakeTransport()
79
+ try:
80
+ _run(power_phase(benchpod_plug(transport=tx1, persistent=True), on=True))
81
+ _run(power_phase(benchpod_plug(transport=tx2, persistent=True), on=True))
82
+ _run(power_phase(benchpod_plug(transport=tx1, persistent=True, timeout=5.0), on=True))
83
+ assert len(_PERSISTENT_POOL) == 3
84
+ finally:
85
+ close_persistent_benchpods()
86
+ assert tx1.closed and tx2.closed
87
+
88
+
89
+ def test_pool_key_reads_settings_by_value():
90
+ wiring = {"signals": {"READY": 5}, "uart": {"baud": 115200}}
91
+ assert _pool_key("10.0.0.5:8080", {"wiring": wiring, "la_voltage": 3.3}) == \
92
+ _pool_key("10.0.0.5:8080", {"la_voltage": 3.3, "wiring": dict(wiring)})
93
+ assert _pool_key("10.0.0.5:8080", {}) != _pool_key("10.0.0.6:8080", {})
94
+ assert _pool_key("x", {"la_voltage": 1.8}) != _pool_key("x", {"la_voltage": 3.3})
@@ -1,11 +0,0 @@
1
- """Make the package importable when running the tests from a source checkout
2
- without an editable install.
3
-
4
- Set EMBEDDEDCI_TEST_INSTALLED=1 to test the installed package instead (e.g. a built wheel)."""
5
-
6
- import os
7
- import sys
8
-
9
- _SRC = os.path.join(os.path.dirname(os.path.dirname(__file__)), "src")
10
- if os.environ.get("EMBEDDEDCI_TEST_INSTALLED") != "1" and _SRC not in sys.path:
11
- sys.path.insert(0, _SRC)