Debian Codegraph @

pymeasure/generator.py

raw
1 #
2 # This file is part of the PyMeasure package.
3 #
4 # Copyright (c) 2013-2024 PyMeasure Developers
5 #
6 # Permission is hereby granted, free of charge, to any person obtaining a copy
7 # of this software and associated documentation files (the "Software"), to deal
8 # in the Software without restriction, including without limitation the rights
9 # to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 # copies of the Software, and to permit persons to whom the Software is
11 # furnished to do so, subject to the following conditions:
12 #
13 # The above copyright notice and this permission notice shall be included in
14 # all copies or substantial portions of the Software.
15 #
16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 # IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 # FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 # AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 # LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
22 # THE SOFTWARE.
23 #
24
25 import io
26 import logging
27
28 from pymeasure.adapters import VISAAdapter
29 from pymeasure.instruments import Channel
30
31 log = logging.getLogger(__name__)
32 log.addHandler(logging.NullHandler())
33
34
35 def write_generic_test(file, header_text, cls_name, comm_text,
36 test,
37 inkwargs=None):
38 """Write a generic test.
39
40 :param fileLike file: File to write to.
41 :param list[str] header_text: Text of the header (parametrization, test name etc.)
42 :param str cls_name: Name of the instrument class.
43 :param list[str] comm_text: List of str of communication pairs
44 :param str test: Test to assert for.
45 :param dict[str, Any] inkwargs: Dictionary of instrument instantiation kwargs.
46 """
47 if inkwargs is None:
48 args_text = "",
49 else:
50 args_text = [f' {key}={repr(value)},\n' for key, value in inkwargs.items()]
51 inst = " as inst" if "inst" in test else ""
52 # file.writelines([
53 # "\n",
54 # "\n",
55 # *header_text,
56 # " with expected_protocol(\n",
57 # f" {cls_name},\n",
58 # *comm_text,
59 # *args_text,
60 # f" ){inst}:\n",
61 # f" {test}\n"
62 # ])
63
64 file.write(
65 f"""
66
67 {''.join(header_text)}\
68 with expected_protocol(
69 {cls_name},
70 {''.join(comm_text)}\
71 {''.join(args_text)}\
72 ){inst}:
73 {test}
74 """
75 )
76
77
78 def write_test(file,
79 test_name,
80 cls_name,
81 comm_pairs,
82 test,
83 inkwargs=None,
84 ):
85 """Write a single test.
86
87 :param file: File to write to.
88 :param str test_name: Name of the test.
89 :param str cls_name: Name of the instrument class.
90 :param list[tuple[bytes | None, bytes | None]] comm_pairs_list: List of communication pairs.
91 :param str test: Test to assert for.
92 :param dict[str, Any] inkwargs: Dictionary of instrument instantiation kwargs.
93 """
94 write_generic_test(
95 file=file,
96 header_text=[f"def test_{test_name.replace('.', '_')}():\n"],
97 cls_name=cls_name,
98 comm_text=[f" {comm_pairs},\n".replace("), (", "),\n (")],
99 test=test,
100 inkwargs=inkwargs,
101 )
102
103
104 def write_parametrized_test(file,
105 test_name,
106 cls_name,
107 comm_pairs_list,
108 values_list,
109 test,
110 inkwargs=None,
111 ):
112 """Write a parametrized test for properties.
113
114 :param file: File to write to.
115 :param str test_name: Name of the test.
116 :param str cls_name: Name of the instrument class.
117 :param list[list[tuple[bytes | None, bytes | None]]] comm_pairs_list: List of communication
118 pairs list for each test.
119 :param list[Any] values_list: List of expected values.
120 :param str test: Test to assert for. :code:`'value'` is the expected parametrized value.
121 :param dict inkwargs: Dictionary of instrument instantiation kwargs.
122 """
123 params = [f" ({cp},\n {v}),\n".replace(
124 "), (", "),\n (") for cp, v in zip(comm_pairs_list, values_list)]
125 header_text = ['@pytest.mark.parametrize("comm_pairs, value", (\n',
126 *params,
127 "))\n",
128 f"def test_{test_name.replace('.', '_')}(comm_pairs, value):\n",
129 ]
130 write_generic_test(file=file,
131 header_text=header_text,
132 cls_name=cls_name,
133 comm_text=[" comm_pairs,\n"],
134 test=test,
135 inkwargs=inkwargs,
136 )
137
138
139 def write_parametrized_method_test(file,
140 test_name,
141 cls_name,
142 comm_pairs_list,
143 args_list,
144 kwargs_list,
145 values_list,
146 test,
147 inkwargs=None,
148 ):
149 """Write a parametrized test for a method, taking in account additional arguments.
150
151 :param file: File to write to.
152 :param str name: Name of the test.
153 :param str cls_name: Name of the instrument class.
154 :param list[list[tuple[bytes | None, bytes | None]]] comm_pairs_list: List of communication
155 pairs list for each test.
156 :param list[tuple[Any, ...]] args_list: List of arguments lists for the method.
157 :param list[dict[str, Any]] kwargs_list: List of keyword dictionaries for the method.
158 :param list[Any] values_list: List of expected values.
159 :param str test: Test to assert for. :code:`'value'` is the expected parametrized value.
160 :param dict inkwargs: Dictionary of instrument instantiation kwargs.
161 """
162 z = zip(comm_pairs_list, args_list, kwargs_list, values_list)
163 params = [f" ({cp},\n {a}, {k}, {v}),\n".replace(
164 "), (", "),\n (") for cp, a, k, v in z]
165 header_text = ['@pytest.mark.parametrize("comm_pairs, args, kwargs, value", (\n',
166 *params,
167 "))\n",
168 f"def test_{test_name.replace('.', '_')}(comm_pairs, args, kwargs, value):\n",
169 ]
170 write_generic_test(
171 file=file,
172 cls_name=cls_name,
173 header_text=header_text,
174 comm_text=[" comm_pairs,\n"],
175 test=test,
176 inkwargs=inkwargs
177 )
178
179
180 def parse_stream(stream):
181 """
182 Parse the data stream.
183
184 It is expected, that a message is always written in one write, while
185 reading may extend over several reads, e.g. reading bytes.
186
187 :return list[tuple[bytes | None, bytes | None]]: List of communication pairs
188 """
189 comm = []
190 lines = stream.readlines()
191 write = None
192 read = None
193 mode = None
194 for line in lines:
195 if line.startswith(b"WRITE:"):
196 # Store the last comm_pair unless there is none.
197 if write is not None or read is not None:
198 comm.append((write, read))
199 read = None
200 write = line[6:-1]
201 mode = "W"
202 elif line.startswith(b"READ:"):
203 if read is not None:
204 read += line[5:-1]
205 else:
206 read = line[5:-1]
207 mode = "R"
208 else:
209 # newline due to "\n" character in communication
210 if mode == "W":
211 write += b"\n" + line[:-1]
212 elif mode == "R":
213 read += b"\n" + line[:-1]
214 else:
215 raise ValueError("Very first line does not contain 'WRITE' or 'READ'!")
216 if read is not None or write is not None:
217 comm.append((write, read))
218 return comm
219
220
221 class ByteFormatter(logging.Formatter):
222 """Logging formatter with bytes values for the test generation."""
223
224 @staticmethod
225 def make_bytes(value):
226 if isinstance(value, (bytes, bytearray)):
227 return value
228 if isinstance(value, str):
229 return value.encode()
230 raise ValueError(f"value '{value}' is neither str nor bytes.")
231
232 def format(self, record):
233 return b"".join((record.msg.replace(r"%s", "").encode(),
234 *[self.make_bytes(arg) for arg in record.args])) # type: ignore
235
236
237 class ByteStreamHandler(logging.StreamHandler):
238 """Logging handler using bytes streams."""
239
240 terminator = b"\n" # type: ignore
241
242 def __init__(self, *args, **kwargs):
243 super().__init__(*args, **kwargs)
244 self.formatter = ByteFormatter()
245
246
247 class TestInstrument:
248 """A man-in-the-middle instrument, which logs property access and method calls.
249
250 :param instrument: The real instrument, given by the generator.
251 :param generator: The generator which writes the tests.
252 :param name: Name in case of a channel with trailing period, for example :code:`"ch_1."`.
253 """
254
255 def __init__(self, instrument, generator, name=""):
256 self._inst = instrument
257 self._generator = generator
258 self._name = name
259
260 def __getattr__(self, name):
261 if name.startswith("_"):
262 # return private and special attributes to prevent recursion
263 return super().__getattribute__(name)
264 elif name == "adapter":
265 # transparently return the instrument's adapter without writing tests
266 return self._inst.adapter
267 else:
268 # transparently get the attribute from the instrument and write an appropriate test
269 value = getattr(self._inst, name)
270 if callable(value):
271 # the attribute is a callable, we have to return a special method which writes the
272 # test while returning the value
273 def test_method(*args, **kwargs):
274 return self._generator._test_method(value, self._name + name, *args, **kwargs)
275 return test_method
276 elif isinstance(value, Channel):
277 # the attribute is not a property or method, but a Channel, return a TestInstrument
278 return TestInstrument(value, self._generator, f"{self._name}{name}.")
279 else:
280 # the attribute is a plain property, return the value and write a test
281 self._generator._store_property_getter_test(self._name + name, value)
282 return value
283
284 def __setattr__(self, name, value):
285 if name.startswith("_"):
286 # set private and special attributes to prevent recursion
287 super().__setattr__(name, value)
288 else:
289 # set an attribute transparently while writing a test
290 setattr(self._inst, name, value)
291 self._generator._store_property_setter_test(self._name + name, value)
292
293 def __dir__(self):
294 # To get autocompletion support for instrument members.
295 return super().__dir__() + dir(self._inst)
296
297
298 class Generator:
299 """
300 Generates tests from the communication with an instrument.
301
302 Example usage:
303
304 .. code::
305
306 g = Generator()
307 inst = g.instantiate(TC038, "COM5", 'hcp', adapter_kwargs={'baud_rate': 9600})
308 inst.information # returns the 'information' property and adds it to the tests
309 inst.setpoint = 20
310 inst.setpoint == 20 # should be True
311 g.write_file("test_tc038.py") # write the tests to a file
312 """
313
314 def __init__(self):
315 self._stream = io.BytesIO()
316 self._index = 0
317 self._init_comm_pairs = [] # Initializiation comm_pairs
318 # Dictionaries for parametrized tests
319 self._getters = {}
320 self._setters = {}
321 self._calls = {}
322
323 def write_init_test(self, file):
324 """Write the header and init test."""
325 file.write(self._header)
326 write_test(file, "init", self._class, self._init_comm_pairs,
327 "pass # Verify the expected communication.",
328 self._inkwargs,
329 )
330
331 def write_getter_test(self, file, property, parameters):
332 """Write a getter test."""
333 if len(parameters[0]) == 1:
334 v = parameters[1][0]
335 comparison = "is" if isinstance(v, bool) or v is None else "=="
336 write_test(file,
337 test_name=property.replace(".", "_") + "_getter",
338 cls_name=self._class,
339 comm_pairs=parameters[0][0],
340 test=f"assert inst.{property} {comparison} {v}",
341 inkwargs=self._inkwargs,
342 )
343 else:
344 write_parametrized_test(file,
345 test_name=property.replace(".", "_") + "_getter",
346 cls_name=self._class,
347 comm_pairs_list=parameters[0],
348 values_list=parameters[1],
349 test=f"assert inst.{property} == value",
350 inkwargs=self._inkwargs,
351 )
352
353 def write_setter_test(self, file, property, parameters):
354 """Write a setter test."""
355 if len(parameters[0]) == 1:
356 v = parameters[1][0]
357 write_test(file,
358 test_name=property.replace(".", "_") + "_setter",
359 cls_name=self._class,
360 comm_pairs=parameters[0][0],
361 test=f"inst.{property} = {v}",
362 # inkwargs=self._inkwargs, TODO
363 )
364 else:
365 write_parametrized_test(file,
366 test_name=property.replace(".", "_") + "_setter",
367 cls_name=self._class,
368 comm_pairs_list=parameters[0],
369 values_list=parameters[-1],
370 test=f"inst.{property} = value",
371 inkwargs=self._inkwargs,
372 )
373
374 def write_method_test(self, file, method, parameters):
375 """Write a test for a method."""
376 if len(parameters[0]) == 1:
377 v = parameters[-1][0]
378 comparison = "is" if isinstance(v, bool) or v is None else "=="
379 arg_string = f"*{parameters[1][0]}, " if parameters[1][0] else ""
380 kwarg_string = f"**{parameters[2][0]}" if parameters[2][0] else ""
381 write_test(file,
382 test_name=method.replace(".", "_"),
383 cls_name=self._class,
384 comm_pairs=parameters[0][0],
385 test=f"assert inst.{method}({arg_string}{kwarg_string}) {comparison} {v}",
386 inkwargs=self._inkwargs,
387 )
388 else:
389 write_parametrized_method_test(file,
390 test_name=method.replace(".", "_"),
391 cls_name=self._class,
392 comm_pairs_list=parameters[0],
393 args_list=parameters[1],
394 kwargs_list=parameters[2],
395 values_list=parameters[-1],
396 test=f"assert inst.{method}(*args, **kwargs) == value",
397 inkwargs=self._inkwargs,
398 )
399
400 def write_property_tests(self, file):
401 """Write tests for properties in alphabetic order.
402
403 If getter and setter exist, the setter is the first test.
404 """
405 # Get a sorted list of all properties, without repeating them
406 property_names = sorted(set(self._getters.keys() | set(self._setters.keys())))
407 for property in property_names:
408 if property in self._setters:
409 self.write_setter_test(file, property, self._setters[property])
410 if property in self._getters:
411 # new condition (not elif), as properties can be in setters and in getters tests.
412 self.write_getter_test(file, property, self._getters[property])
413
414 def write_method_tests(self, file):
415 """Write all parametrized method tests in alphabetic order."""
416 for method in sorted(self._calls.keys()):
417 self.write_method_test(file, method, self._calls[method])
418
419 def write_file(self, filename="tests.py"):
420 """Write the tests into the file.
421
422 :param filename: Name to save the tests to, may contain the path, e.g. "/tests/test_abc.py".
423 """
424 file = filename if isinstance(filename, io.StringIO) else open(filename, "w")
425 self.write_init_test(file)
426 self.write_property_tests(file)
427 self.write_method_tests(file)
428 file.close()
429
430 def parse_stream(self):
431 """Parse the stream not yet read."""
432 self._stream.seek(self._index)
433 comm = parse_stream(self._stream)
434 self._index = self._stream.tell()
435 return self._init_comm_pairs + comm
436
437 def instantiate(self, instrument_class, adapter, manufacturer, adapter_kwargs=None, **kwargs):
438 """
439 Instantiate the instrument and store the instantiation communication.
440
441 ..note::
442
443 You have to give all keyword arguments necessary for adapter instantiation in
444 `adapter_kwargs`, even those, which are defined somewhere in the instrument's
445 ``__init__`` method, be it as a default value, be it directly in the
446 ``Instrument.__init__()`` call.
447
448 :param instrument_class: Class of the instrument to test.
449 :param adapter: Adapter (instance or str) for the instrument instantiation.
450 :param manufacturer: Module from which to import the instrument, e.g. 'hcp' if
451 instrument_class is 'pymeasure.hcp.tc038'.
452 :param adapter_kwargs: Keyword arguments for the adapter instantiation (see note above).
453 :param \\**kwargs: Keyword arguments for the instrument instantiation.
454 :return: A man-in-the-middle instrument, which can be used like a normal instrument.
455 """
456 self._class = instrument_class.__name__
457 log.info(f"Instantiate {self._class}.")
458 self._header = (
459 "import pytest\n\n"
460 "from pymeasure.test import expected_protocol\n"
461 f"from pymeasure.instruments.{manufacturer} import {self._class}\n")
462 if isinstance(adapter, (int, str)):
463 if adapter_kwargs is None:
464 adapter_kwargs = {}
465 try:
466 adapter = VISAAdapter(adapter, **adapter_kwargs)
467 except ImportError:
468 raise Exception("Invalid Adapter provided for Instrument since"
469 " PyVISA is not present")
470 adapter.log.addHandler(ByteStreamHandler(self._stream))
471 adapter.log.setLevel(logging.DEBUG)
472 self.inst = instrument_class(adapter, **kwargs)
473 self._init_comm_pairs = self.parse_stream() # communication of instantiation.
474 self._inkwargs = kwargs # instantiation kwargs
475 self.test_inst = TestInstrument(self.inst, self)
476 return self.test_inst
477
478 def _store_property_getter_test(self, property, value):
479 """Store the property getter test with returned `value`."""
480 comm = self.parse_stream()
481 if property not in self._getters:
482 self._getters[property] = [], []
483 c, v = self._getters[property]
484 c.append(comm)
485 v.append(f"\'{value}\'" if isinstance(value, str) else value)
486 return value
487
488 def test_property_getter(self, property):
489 """Test getting the `property` of the instrument, adding it to the list."""
490 log.info(f"Test property {property} getter.")
491 value = getattr(self.inst, property)
492 self._store_property_getter_test(property, value)
493 return value
494
495 def _store_property_setter_test(self, property, value):
496 """Store the property setter test with `value`."""
497 comm = self.parse_stream()
498 if property not in self._setters:
499 self._setters[property] = [], []
500 c, v = self._setters[property]
501 c.append(comm)
502 v.append(f"\'{value}\'" if isinstance(value, str) else value)
503
504 def test_property_setter(self, property, value):
505 """Test setting the `property` of the instrument to `value`, adding it to the list."""
506 log.info(f"Test property {property} setter.")
507 setattr(self.inst, property, value)
508 self._store_property_setter_test(property, value)
509
510 def _test_method(self, method, method_name, *args, **kwargs):
511 """Test calling `method` with the full `method_name` and `args` and `kwargs`."""
512 value = method(*args, **kwargs)
513 comm = self.parse_stream()
514 if method_name not in self._calls:
515 self._calls[method_name] = [], [], [], []
516 c, a, k, v = self._calls[method_name]
517 c.append(comm)
518 a.append(args)
519 k.append(kwargs)
520 v.append(f"\'{value}\'" if isinstance(value, str) else value)
521 return value
522
523 def test_method(self, method_name, *args, **kwargs):
524 """Test calling the `method_name` of the instruments with `args` and `kwargs`."""
525 log.info(f"Test method {method_name}.")
526 method = getattr(self.inst, method_name)
527 return self._test_method(method, method_name, *args, **kwargs)
528
529 # batch tests
530 def test_property_setter_batch(self, property, values):
531 """Test setting `property` to each element in `values`."""
532 for value in values:
533 self.test_property_setter(property, value)