We currently support free metadata on the suite level and there are plans to support it also on the test/task level (#4409) and on the keyword level (#5627). This example covers all three levels:
*** Settings ***
Metadata Version 7.5
*** Test Cases ***
Example
[Metadata] Issue 4409
Keyword
*** Keywords ***
Keyword
[Metadata] Proposer LakitnaIt would be more convenient to specify these values without the Metadata or [Metadata] settings:
*** Settings ***
Version 7.5
*** Test Cases ***
Example
[Issue] 4409
Keyword
*** Keywords ***
Keyword
[Proposer] LakitnaA problem with supporting the above automatically is that we'd then support any setting. It would be messy and, more importantly, it would make it impossible to detect typos like using [Setpu] instead of [Setup]. We thus need some way to specify the allowed metadata/setting names that Robot accepts. Editors can also use this information to provide auto-completion with the allowed names.
Although the overall idea is pretty simple, there are various design decisions to be made discussed below. Getting all this design sorted out in RF 7.5 scope may be too big a task, especially when getting the actual test and keyword level metadata implemented has higher priority. Metadata works also without this extra convenience, so moving this issue to some future release is fine if there are time constraints.
How to specify allowed values?
It would be convenient to do this in a configuration file, but Robot unfortunately doesn't support them. Adding such support would be great, but it is out of the scope of this issue.
The normal way to configure Robot execution is using command line options and we probably should use them here as well. The usage is likely going to be somewhat inconvenient, but luckily it's easy to create scripts for starting execution and have complex command line options there.
Another solution would be using per-file configuration like we do with translations and plan to do with documentation format. I expect allowed metadata to be typically decided on a project level and in such cases per-file configuration is not convenient. I thus don't consider it worth the effort.
One option for metadata on all levels or one option per level?
Should we have just one option that specifies allowed metadata/settings names that could be used on any level or should we have three options for controlling each level separately? Having just one would be simpler, but separate settings would avoid using a valid name on an invalid level.
Should the setting also control what can be used with Metadata and [Metadata]?
If we have configured, for example, that on test level we can use [Issue], could we still use [Metadata] with some other names on test level or would it also be limited to Issue? Should there be a way to configure both separately?
Should we allow configuring required metadata/settings?
In some contexts it would be convenient to require that certain information is specified. Such functionality should probably get its own issue, but this possibility should be taken into account when deciding option names.
Should we allow configuring metadata/setting values?
It could be convenient to limit a metadata value to certain predefined values or to use patterns to specify allowed formats. I consider this out of the scope of this issue, though.
Command line option name or names?
Using just --metadata doesn't work, because it's already in use. Something like --allowed-metadata sounds pretty good, but it would then apply to all levels and it gives an impression that it also limits what names can be used with Metadata and [Metadata]. Whether that is fine or not depends on how the above design decisions are resolved.
Separate options like --suite-setting, --test-setting, --task-setting (alias to the previous one) and --keyword-setting would cover different levels and wouldn't give an impression that these options would affect Metadata or [Metadata].
Command line option usage?
Should it be possible to use an option once to specify all settings (e.g. --allowed-metadata Version,Issue,Proposer) or should each setting be specified separately (e.g. --suite-setting Version --test-setting Issue --keyword-setting Proposer)? The former would be more convenient especially if we have only one option, but the latter could possibly be enhanced to cover features like allowed values (e.g. --test-setting Issue:pattern=\d+).
Should this apply only to parsing or also to programmatic modifications?
I believe these options should only affect parsing. If someone then uses a pre-run modifier or listener to modify suites, tests and keywords, they should be able to use whatever metadata they want. In such programmatic usage it's anyway possible to do even more detailed validation for metadata if needed. Limiting programmatic modifications would also make this a lot harder to implement.
We currently support free metadata on the suite level and there are plans to support it also on the test/task level (#4409) and on the keyword level (#5627). This example covers all three levels:
It would be more convenient to specify these values without the
Metadataor[Metadata]settings:A problem with supporting the above automatically is that we'd then support any setting. It would be messy and, more importantly, it would make it impossible to detect typos like using
[Setpu]instead of[Setup]. We thus need some way to specify the allowed metadata/setting names that Robot accepts. Editors can also use this information to provide auto-completion with the allowed names.Although the overall idea is pretty simple, there are various design decisions to be made discussed below. Getting all this design sorted out in RF 7.5 scope may be too big a task, especially when getting the actual test and keyword level metadata implemented has higher priority. Metadata works also without this extra convenience, so moving this issue to some future release is fine if there are time constraints.
How to specify allowed values?
It would be convenient to do this in a configuration file, but Robot unfortunately doesn't support them. Adding such support would be great, but it is out of the scope of this issue.
The normal way to configure Robot execution is using command line options and we probably should use them here as well. The usage is likely going to be somewhat inconvenient, but luckily it's easy to create scripts for starting execution and have complex command line options there.
Another solution would be using per-file configuration like we do with translations and plan to do with documentation format. I expect allowed metadata to be typically decided on a project level and in such cases per-file configuration is not convenient. I thus don't consider it worth the effort.
One option for metadata on all levels or one option per level?
Should we have just one option that specifies allowed metadata/settings names that could be used on any level or should we have three options for controlling each level separately? Having just one would be simpler, but separate settings would avoid using a valid name on an invalid level.
Should the setting also control what can be used with
Metadataand[Metadata]?If we have configured, for example, that on test level we can use
[Issue], could we still use[Metadata]with some other names on test level or would it also be limited toIssue? Should there be a way to configure both separately?Should we allow configuring required metadata/settings?
In some contexts it would be convenient to require that certain information is specified. Such functionality should probably get its own issue, but this possibility should be taken into account when deciding option names.
Should we allow configuring metadata/setting values?
It could be convenient to limit a metadata value to certain predefined values or to use patterns to specify allowed formats. I consider this out of the scope of this issue, though.
Command line option name or names?
Using just
--metadatadoesn't work, because it's already in use. Something like--allowed-metadatasounds pretty good, but it would then apply to all levels and it gives an impression that it also limits what names can be used withMetadataand[Metadata]. Whether that is fine or not depends on how the above design decisions are resolved.Separate options like
--suite-setting,--test-setting,--task-setting(alias to the previous one) and--keyword-settingwould cover different levels and wouldn't give an impression that these options would affectMetadataor[Metadata].Command line option usage?
Should it be possible to use an option once to specify all settings (e.g.
--allowed-metadata Version,Issue,Proposer) or should each setting be specified separately (e.g.--suite-setting Version --test-setting Issue --keyword-setting Proposer)? The former would be more convenient especially if we have only one option, but the latter could possibly be enhanced to cover features like allowed values (e.g.--test-setting Issue:pattern=\d+).Should this apply only to parsing or also to programmatic modifications?
I believe these options should only affect parsing. If someone then uses a pre-run modifier or listener to modify suites, tests and keywords, they should be able to use whatever metadata they want. In such programmatic usage it's anyway possible to do even more detailed validation for metadata if needed. Limiting programmatic modifications would also make this a lot harder to implement.