The will be two child fields. valid will contain a list of example fields that may be returned during nominal operation. error will be a map of custom error names (key) to their returned result (value).
The second change will come to the function objects:
Similarly, each example field will be added to a particular computation. It will have some valid entries as well as a map of error types with returned results.
Unit tests
A new python-unittest.py template can be used to generate device-specific unit tests. Modeled off of the existing Python templates, the register read functions will be replaced by hardcoded entries.
These will be processed by the function execution, defined as tests. Assertions will run at the end to see if the function matches one of the valid examples.
def test_ascelsius(self):
# Run some logic
variable = read_register_a() # Get the hardcoded 0x43
# Additional logic
returnVal = ... # Whatever is normally computed
expectedVal = 16 # asCelsius.example.valid[0]
self.assertEqual(expectedVal, returnVal)
Finally, running this unit test python3 -m unittest /path/to/test.py will verify if the results match.
Templates
These fields can be added to doc.md, datasheet.tex, and webpage.html to provide additional register-level documentation.
They can also improve code documentation, like raspberrypi.py:
def set_{{key.lower()}}(self{% if register.length > 0 %}, data{% endif %}):
"""
{{utils.pad_string(" ", register.description)}}
+ Example value is {{ register.examples.valid[0] }}.
"""
Validator
This can be integrated into the existing Cyanobyte validator tool if the schema includes examples (if not it will generate a file with no tests).
The validator will receive new flags to more precisely tune its output and execution.
By default the tool will do both, as well as any future validation operations. Internally, the existence of any of these flags will cause all flags to be checked. Technically you could use both flags --validate-schema --unit-test /path/to/files.py ahead of a potential third validation technique.
Branching off of #267, aid in the development of high-quality schemas by allowing schemas to specify example values for registers and functions.
This will provide:
This issue itself will not focus on emulations of devices.
Spec changes
This change will add a new set of fields to the
register
objects:The will be two child fields.
valid
will contain a list of example fields that may be returned during nominal operation.error
will be a map of custom error names (key) to their returned result (value).The second change will come to the function objects:
Similarly, each example field will be added to a particular computation. It will have some valid entries as well as a map of error types with returned results.
Unit tests
A new
python-unittest.py
template can be used to generate device-specific unit tests. Modeled off of the existing Python templates, the register read functions will be replaced by hardcoded entries.These will be processed by the function execution, defined as tests. Assertions will run at the end to see if the function matches one of the valid examples.
Finally, running this unit test
python3 -m unittest /path/to/test.py
will verify if the results match.Templates
These fields can be added to
doc.md
,datasheet.tex
, andwebpage.html
to provide additional register-level documentation.They can also improve code documentation, like
raspberrypi.py
:Validator
This can be integrated into the existing Cyanobyte validator tool if the schema includes examples (if not it will generate a file with no tests).
The validator will receive new flags to more precisely tune its output and execution.
By default the tool will do both, as well as any future validation operations. Internally, the existence of any of these flags will cause all flags to be checked. Technically you could use both flags
--validate-schema --unit-test /path/to/files.py
ahead of a potential third validation technique.