Document PVE::SectionConfig Peculiarities - v1 ==============================================
This was a long overdue series that adds a bunch of unit tests and documentation updates for PVE::SectionConfig. The main motivation for this series is me running somewhat regularly into new discoveries when using PVE::SectionConfig for other purposes or investigating how certain schemas are generated. Since there have been quite a few surprises and somewhat sharp corners, I decided to document all of these "peculiarities" in the form of unit / regression tests instead of lengthy, wordy, borderline incomprehensible paragraphs in the PVE::SectionConfig POD. (Seriously, some behaviors are quite hard to parse when written out as text.) The additional benefit of these tests is that they (should) guard us against any regressions, should we have to make changes to the PVE::SectionConfig machinery at some point in the future. On top of that, we could use them as reference for aligning the Perl and Rust SectionConfig / JSONSchema implementations in the future. The commits should hopefully explain everything in detail. Note though that these tests are by no means exhaustive. The test scripts are however designed in such a way that it should be relatively simple to add new cases whenever a new quirk pops up. Finally, the POD docstrings in the PVE::SectionConfig source are also adapted / corrected / clarified etc., which was made possible by the insights gained from writing all of these tests. References ========== [0]: https://lore.proxmox.com/pve-devel/[email protected]/ Summary of Changes ================== Max R. Carrara (23): sectionconfig: remove unused variable in get_property_schema() tests: sectionconfig: add comparison test structure tests: sectionconfig: add test case for fixed props in updateSchema tests: sectionconfig: add case for unused properties tests: sectionconfig: add case for unused optional default properties tests: sectionconfig: add case for opt. default prop being req. once tests: sectionconfig: add case for opt. default prop requirde by all tests: sectionconfig: add case for unused required default properties tests: sectionconfig: add case for req. default prop being req. once tests: sectionconfig: add case for required default prop req. by all tests: sectionconfig: add case for required default props opt. for all tests: sectionconfig: add isolated mode test structure tests: sectionconfig: add case for an ident. prop on two plugins tests: sectionconfig: add case for same prop. w/ different optionality tests: sectionconfig: add case for differing opt. default prop uses tests: sectionconfig: add case for differing req. default prop uses sectionconfig: correct docs regarding global props in unified mode sectionconfig: reword docs regarding property usage in isolated mode sectionconfig: extend / correct docstring of `private()` method sectionconfig: note that a prop must be defined through a JSONSchema sectionconfig: note that props added by plugins are always optional sectionconfig: note that `createSchema()` is universal for all plugins sectionconfig: correct example in docstring of `updateSchema()` src/PVE/SectionConfig.pm | 62 +- test/Makefile | 5 +- test/SectionConfig/Helpers.pm | 114 + test/SectionConfig/Makefile | 11 + test/SectionConfig/schema_comparison_test.pl | 2047 ++++++++++++++++++ test/SectionConfig/schema_isolated_test.pl | 826 +++++++ 6 files changed, 3047 insertions(+), 18 deletions(-) create mode 100644 test/SectionConfig/Helpers.pm create mode 100644 test/SectionConfig/Makefile create mode 100755 test/SectionConfig/schema_comparison_test.pl create mode 100755 test/SectionConfig/schema_isolated_test.pl -- 2.47.3 _______________________________________________ pve-devel mailing list [email protected] https://lists.proxmox.com/cgi-bin/mailman/listinfo/pve-devel
