added release notes, and outputs of HW required examples (#40)

* - reduced logging for recursions, added results for hw necessary examples, and description in Readme * - added release notes
MarketSquare · Dec 7, 2024 · f23315c · f23315c
1 parent d0314fd
commit f23315c
Show file tree

Hide file tree

Showing 4 changed files with 244 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -17,6 +17,7 @@ uv sync --extra test --dev
 uv run xonsh tasks/baseQC.xsh 
 ```
 
+There are examples which require hardware to work. [USB HID](./atests/HIDKeyboard/) and [nfc/nci](./atests/nfc_nci/). For the nci example, STm hardware and firmware is required. For the HID example, a USB Keyboard on a linux machine is sufficient.
 
 ## What is robotframework-construct?
 robotframework-construct is a [Robot Framework](https://robotframework.org) keyword library powered by [construct](https://construct.readthedocs.io/en/latest/).

diff --git a/atests/hardware_needed_examples_results/HID/.xml b/atests/hardware_needed_examples_results/HID/.xml
@@ -0,0 +1,240 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<robot generator="Robot 7.1.1 (Python 3.13.0 on linux)" generated="2024-12-07T12:40:22.471092" rpa="false" schemaversion="5">
+<suite id="s1" name="Hid Keyboard" source="/home/franz/projects/robotframework-construct/atests/HIDKeyboard/hid_keyboard.robot">
+<test id="s1-t1" name="Demonstrate USB HID read/write using a USB keyboard as an example" line="15">
+<kw name="Open '${HID_FILE}' for reading binary data" owner="robotframework_construct" source_name="Open '${filepath}' for reading binary data">
+<msg time="2024-12-07T12:40:22.703309" level="INFO">${IFILE} = &lt;_io.BufferedReader name='/dev/hidraw0'&gt;</msg>
+<var>${IFILE}</var>
+<doc>Opens a file filepath for reading binary data.</doc>
+<status status="PASS" start="2024-12-07T12:40:22.702283" elapsed="0.001128"/>
+</kw>
+<kw name="Open '${HID_FILE}' for writing binary data without buffering" owner="robotframework_construct" source_name="Open '${filepath}' for writing binary data without buffering">
+<msg time="2024-12-07T12:40:22.704927" level="INFO">${OFILE} = &lt;_io.FileIO name='/dev/hidraw0' mode='wb' closefd=True&gt;</msg>
+<var>${OFILE}</var>
+<doc>Opens a file filepath for writing binary data.</doc>
+<status status="PASS" start="2024-12-07T12:40:22.704187" elapsed="0.000847"/>
+</kw>
+<kw name="Log To Console" owner="BuiltIn">
+<arg>${\n}Press left alt and hold please</arg>
+<doc>Logs the given message to the console.</doc>
+<status status="PASS" start="2024-12-07T12:40:22.705706" elapsed="0.001111"/>
+</kw>
+<kw name="Parse '${IFILE}' using construct '${HIDReportIn}'" owner="robotframework_construct" source_name="Parse '${binarydata}' using construct '${identifier}'">
+<msg time="2024-12-07T12:40:32.298995" level="INFO">parsed: Container: 
+    modifiers = Container: 
+        right_gui = False
+        right_alt = False
+        right_shift = False
+        right_ctrl = False
+        left_gui = False
+        left_alt = True
+        left_shift = False
+        left_ctrl = False
+    reserved = 0
+    keys = ListContainer: 
+        0
+        0
+        0
+        0
+        0
+        0 using &lt;Compiled HIDReportIn&gt; from 04 00 00 00 00 00 00 00</msg>
+<msg time="2024-12-07T12:40:32.300066" level="INFO">${LeftAltPressed} = Container: 
+    modifiers = Container: 
+        right_gui = False
+        right_alt = False
+        right_shift = False
+        right_ctrl = False
+        left_gui = False
+        left_alt = True
+    ...</msg>
+<var>${LeftAltPressed}</var>
+<doc>Parses binary data using a construct. The binary data can be a byte array, a readable binary file object, or a TCP/UDP socket.</doc>
+<status status="PASS" start="2024-12-07T12:40:22.707895" elapsed="9.592360"/>
+</kw>
+<kw name="Element 'modifiers.left_alt' in '${LeftAltPressed}' should be equal to '${True}'" owner="robotframework_construct" source_name="Element '${locator}' in '${constructDict}' should be equal to '${expectedValue}'">
+<msg time="2024-12-07T12:40:32.315019" level="INFO">descending to 'modifiers' of 'Container: 
+    modifiers = Container: 
+        right_gui = False
+        right_alt = False
+        right_shift = False
+        right_ctrl = False
+        left_gui = False
+        left_alt = True
+        left_shift = False
+        left_ctrl = False
+    reserved = 0
+    keys = ListContainer: 
+        0
+        0
+        0
+        0
+        0
+        0'</msg>
+<msg time="2024-12-07T12:40:32.315353" level="INFO">descending to 'left_alt' of 'Container: 
+    right_gui = False
+    right_alt = False
+    right_shift = False
+    right_ctrl = False
+    left_gui = False
+    left_alt = True
+    left_shift = False
+    left_ctrl = False'</msg>
+<doc>Checks that the element located at locator in construct is equal to expectedValue.</doc>
+<status status="PASS" start="2024-12-07T12:40:32.306134" elapsed="0.009808"/>
+</kw>
+<kw name="Log To Console" owner="BuiltIn">
+<arg>${\n}Press and hold right shift please</arg>
+<doc>Logs the given message to the console.</doc>
+<status status="PASS" start="2024-12-07T12:40:32.320123" elapsed="0.005673"/>
+</kw>
+<kw name="Parse '${IFILE}' using construct '${HIDReportIn}'" owner="robotframework_construct" source_name="Parse '${binarydata}' using construct '${identifier}'">
+<msg time="2024-12-07T12:40:33.780383" level="INFO">parsed: Container: 
+    modifiers = Container: 
+        right_gui = False
+        right_alt = False
+        right_shift = True
+        right_ctrl = False
+        left_gui = False
+        left_alt = True
+        left_shift = False
+        left_ctrl = False
+    reserved = 0
+    keys = ListContainer: 
+        0
+        0
+        0
+        0
+        0
+        0 using &lt;Compiled HIDReportIn&gt; from 24 00 00 00 00 00 00 00</msg>
+<msg time="2024-12-07T12:40:33.781488" level="INFO">${LeftAltPressed} = Container: 
+    modifiers = Container: 
+        right_gui = False
+        right_alt = False
+        right_shift = True
+        right_ctrl = False
+        left_gui = False
+        left_alt = True
+     ...</msg>
+<var>${LeftAltPressed}</var>
+<doc>Parses binary data using a construct. The binary data can be a byte array, a readable binary file object, or a TCP/UDP socket.</doc>
+<status status="PASS" start="2024-12-07T12:40:32.326918" elapsed="1.454763"/>
+</kw>
+<kw name="Element 'modifiers.right_shift' in '${LeftAltPressed}' should be equal to '${True}'" owner="robotframework_construct" source_name="Element '${locator}' in '${constructDict}' should be equal to '${expectedValue}'">
+<msg time="2024-12-07T12:40:33.799612" level="INFO">descending to 'modifiers' of 'Container: 
+    modifiers = Container: 
+        right_gui = False
+        right_alt = False
+        right_shift = True
+        right_ctrl = False
+        left_gui = False
+        left_alt = True
+        left_shift = False
+        left_ctrl = False
+    reserved = 0
+    keys = ListContainer: 
+        0
+        0
+        0
+        0
+        0
+        0'</msg>
+<msg time="2024-12-07T12:40:33.799955" level="INFO">descending to 'right_shift' of 'Container: 
+    right_gui = False
+    right_alt = False
+    right_shift = True
+    right_ctrl = False
+    left_gui = False
+    left_alt = True
+    left_shift = False
+    left_ctrl = False'</msg>
+<doc>Checks that the element located at locator in construct is equal to expectedValue.</doc>
+<status status="PASS" start="2024-12-07T12:40:33.797962" elapsed="0.002256"/>
+</kw>
+<kw name="Write binary data generated from '${HIDReportOutEmpty}' using construct '${HIDReportOut}' to '${OFILE}'" owner="robotframework_construct" source_name="Write binary data generated from '${data}' using construct '${identifier}' to '${file}'">
+<msg time="2024-12-07T12:40:33.826090" level="INFO">built: 00 00 00 00 00 00 00 00 (a total of 8 bytes) using "&lt;Compiled HIDReportOut&gt;" from :"
+{'ReportID': 0,
+ 'modifiers': {'CAPS_LOCK': False, 'NUM_LOCK': False, 'SCROLL_LOCK': False},
+ 'reserved': [0, 0, 0, 0, 0, 0]}" </msg>
+<doc>Writes binary data to a file or sends it over a socket.</doc>
+<status status="PASS" start="2024-12-07T12:40:33.816625" elapsed="0.015455"/>
+</kw>
+<kw name="Log To Console" owner="BuiltIn">
+<arg>${\n}The three leds should be off now</arg>
+<doc>Logs the given message to the console.</doc>
+<status status="PASS" start="2024-12-07T12:40:33.837123" elapsed="0.004679"/>
+</kw>
+<kw name="Sleep" owner="BuiltIn">
+<msg time="2024-12-07T12:40:34.844158" level="INFO">Slept 1 second.</msg>
+<arg>1</arg>
+<doc>Pauses the test executed for the given time.</doc>
+<status status="PASS" start="2024-12-07T12:40:33.843193" elapsed="1.001555"/>
+</kw>
+<kw name="Modify the element located at 'modifiers.SCROLL_LOCK' of '${HIDReportOutEmpty}' to '${True}'" owner="robotframework_construct" source_name="Modify the element located at '${locator}' of '${constructDict}' to '${value}'">
+<msg time="2024-12-07T12:40:34.860863" level="INFO">descending to 'modifiers' of '{'ReportID': 0, 'modifiers': {'SCROLL_LOCK': False, 'NUM_LOCK': False, 'CAPS_LOCK': False}, 'reserved': [0, 0, 0, 0, 0, 0]}'</msg>
+<doc>Modifies the element located at locator in constructDict to the value value.</doc>
+<status status="PASS" start="2024-12-07T12:40:34.859781" elapsed="0.001323"/>
+</kw>
+<kw name="Write binary data generated from '${HIDReportOutEmpty}' using construct '${HIDReportOut}' to '${OFILE}'" owner="robotframework_construct" source_name="Write binary data generated from '${data}' using construct '${identifier}' to '${file}'">
+<msg time="2024-12-07T12:40:34.888069" level="INFO">built: 00 04 00 00 00 00 00 00 (a total of 8 bytes) using "&lt;Compiled HIDReportOut&gt;" from :"
+{'ReportID': 0,
+ 'modifiers': {'CAPS_LOCK': False, 'NUM_LOCK': False, 'SCROLL_LOCK': True},
+ 'reserved': [0, 0, 0, 0, 0, 0]}" </msg>
+<doc>Writes binary data to a file or sends it over a socket.</doc>
+<status status="PASS" start="2024-12-07T12:40:34.867237" elapsed="0.034841"/>
+</kw>
+<kw name="Log To Console" owner="BuiltIn">
+<arg>${\n}The scroll lock led should be on now</arg>
+<doc>Logs the given message to the console.</doc>
+<status status="PASS" start="2024-12-07T12:40:34.904778" elapsed="0.006164"/>
+</kw>
+<kw name="Sleep" owner="BuiltIn">
+<msg time="2024-12-07T12:40:35.928622" level="INFO">Slept 1 second.</msg>
+<arg>time_=1</arg>
+<doc>Pauses the test executed for the given time.</doc>
+<status status="PASS" start="2024-12-07T12:40:34.912064" elapsed="1.018275"/>
+</kw>
+<kw name="Modify the element located at 'modifiers.SCROLL_LOCK' of '${HIDReportOutEmpty}' to '${False}'" owner="robotframework_construct" source_name="Modify the element located at '${locator}' of '${constructDict}' to '${value}'">
+<msg time="2024-12-07T12:40:35.946278" level="INFO">descending to 'modifiers' of '{'ReportID': 0, 'modifiers': {'SCROLL_LOCK': True, 'NUM_LOCK': False, 'CAPS_LOCK': False}, 'reserved': [0, 0, 0, 0, 0, 0]}'</msg>
+<doc>Modifies the element located at locator in constructDict to the value value.</doc>
+<status status="PASS" start="2024-12-07T12:40:35.932082" elapsed="0.022982"/>
+</kw>
+<kw name="Modify the element located at 'modifiers.CAPS_LOCK' of '${HIDReportOutEmpty}' to '${True}'" owner="robotframework_construct" source_name="Modify the element located at '${locator}' of '${constructDict}' to '${value}'">
+<msg time="2024-12-07T12:40:35.980049" level="INFO">descending to 'modifiers' of '{'ReportID': 0, 'modifiers': {'SCROLL_LOCK': False, 'NUM_LOCK': False, 'CAPS_LOCK': False}, 'reserved': [0, 0, 0, 0, 0, 0]}'</msg>
+<doc>Modifies the element located at locator in constructDict to the value value.</doc>
+<status status="PASS" start="2024-12-07T12:40:35.971177" elapsed="0.009154"/>
+</kw>
+<kw name="Write binary data generated from '${HIDReportOutEmpty}' using construct '${HIDReportOut}' to '${OFILE}'" owner="robotframework_construct" source_name="Write binary data generated from '${data}' using construct '${identifier}' to '${file}'">
+<msg time="2024-12-07T12:40:35.993251" level="INFO">built: 00 01 00 00 00 00 00 00 (a total of 8 bytes) using "&lt;Compiled HIDReportOut&gt;" from :"
+{'ReportID': 0,
+ 'modifiers': {'CAPS_LOCK': True, 'NUM_LOCK': False, 'SCROLL_LOCK': False},
+ 'reserved': [0, 0, 0, 0, 0, 0]}" </msg>
+<doc>Writes binary data to a file or sends it over a socket.</doc>
+<status status="PASS" start="2024-12-07T12:40:35.989991" elapsed="0.012228"/>
+</kw>
+<kw name="Log To Console" owner="BuiltIn">
+<arg>${\n}The caps lock led should be on now</arg>
+<doc>Logs the given message to the console.</doc>
+<status status="PASS" start="2024-12-07T12:40:36.003942" elapsed="0.009472"/>
+</kw>
+<tag>hardware</tag>
+<status status="PASS" start="2024-12-07T12:40:22.700285" elapsed="13.317487"/>
+</test>
+<doc>This is a simple example for a robot file using robotframework-construct demonstrating accessing real HW over the USB HID interface.
+
+This currently only tested on linux</doc>
+<status status="PASS" start="2024-12-07T12:40:22.473688" elapsed="13.549976"/>
+</suite>
+<statistics>
+<total>
+<stat pass="1" fail="0" skip="0">All Tests</stat>
+</total>
+<tag>
+<stat pass="1" fail="0" skip="0">hardware</stat>
+</tag>
+<suite>
+<stat pass="1" fail="0" skip="0" id="s1" name="Hid Keyboard">Hid Keyboard</stat>
+</suite>
+</statistics>
+<errors>
+</errors>
+</robot>
diff --git a/docs/release_notes.md b/docs/release_notes.md
@@ -1,9 +1,11 @@
 # Changelog
 
-## Robotframework_Construct 0.2.4 
+## Robotframework_Construct 0.2.4 (in the works)
 
 ### Features
 
+ - improved test coverage killing all mutants
+ - improved github page, added banners for ruff/radon/mutationtesting/pypireleases/tests/building breakout example
  - improved logging, now the raw hexdump of both the parsed and the generated data is available
  - improved logging, prettier visualization of data
 

diff --git a/src/robotframework_construct/__init__.py b/src/robotframework_construct/__init__.py
@@ -76,7 +76,6 @@ def _set_element_from_constructDict(self, constructDict: typing.Union[dict, cons
         constructDict[target] = value
 
     def _traverse_construct_for_element(self, constructDict: typing.Union[dict, construct.Struct], locator: str, original: typing.Union[dict, construct.Struct], item: str) -> typing.Union[dict, construct.Struct]:
-        robot.api.logger.info(f"descending to '{item}' of '{constructDict}'")
         match (item, constructDict,):
             case (str(), dict(),):
                 constructDict = constructDict[item]