René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Consistent syntax for suite/test/context annotations","articleBody":"**Current state**\r\n\r\nCurrently `--%suite` and `--%test` annotations take `description` as argument.\r\nThe `--%context` annotation doesn't allow that and expects `name` to be given instead.\r\n\r\nThis is inconsistent and leads to confusion when using the framework.\r\n\r\nEngineers expect simplicity and ease of use from the framework which isn't the case with `--%context` annotation.\r\n\r\nConsider the below example:\r\n```sql\r\ncreate or replace package queue_spec as\r\n  --%suite(Queue specification)\r\n\r\n  --%context(A new queue)\r\n\r\n    --%test(Cannot be created with non positive bounding capacity)\r\n    procedure non_positive_bounding_cap;\r\n\r\n  --%endcontext\r\nend;\r\n```\r\n\r\nWith this package, current implementation of utPLSQL gives the following:\r\n\r\n| suitepath | description | name |\r\n|-----------|------------|------|\r\n| queue_spec | Queue specification | queue_spec |\r\n| queue_spec.A new queue | A new queue | A new queue |\r\n| queue_spec.A new queue.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |\r\n\r\n- The name of suite comes from package name and description from annotation\r\n- The name of test comes from procedure name and description from annotation \r\n- The name of context is take from annotation and description is copied from name\r\n\r\nThe above package spec is not really valid, as context name should not contain any whitespace or full stop characters. Context name rules should conform to naming rules for Oracle objects.\r\n\r\nutPLSQL does not give any warning on invalid context names too.\r\n\r\nThe proper implementation of the above package following current framework behavior should be more like below.\r\n```sql\r\ncreate or replace package queue_spec as\r\n  --%suite(Queue specification)\r\n\r\n  --%context(a_new_queue)\r\n  --%displayname(A new queue)\r\n\r\n    --%test(Cannot be created with non positive bounding capacity)\r\n    procedure non_positive_bounding_cap;\r\n\r\n  --%endcontext\r\nend;\r\n```\r\n\r\nThe above is confusing, hard to remember and easy to confuse engineers.\r\n\r\n| suitepath | description | name |\r\n|-----------|------------|------|\r\n| queue_spec | Queue specification | queue_spec |\r\n| queue_spec.a_new_queue | A new queue | a_new_queue |\r\n| queue_spec.a_new_queue.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |\r\n\r\n\r\n**Describe the solution you'd like**\r\n\r\nI suggest to change the current behavior so that the `--%context` annotation accepts description as argument and is aligned with `--%test` and `--suite` annotations.\r\n\r\nFramework would need to provide a way for giving an explicit name to a context as well as allow for implicit naming, if users don't care about context names. \r\n\r\nRules:\r\n- if no `name` is specified for a context, the context name is defaulted to `nested_context_#N` where `N` is the consecutive number of the context inside it's parent.\r\n- if a `name` is specified for the context, the name is used instead\r\n- if provided `name` is not valid, a warning is given and the name is defaulted to `nested_context_#N` \r\n\r\n\r\nGiven the original example.\r\n```sql\r\ncreate or replace package queue_spec as\r\n  --%suite(Queue specification)\r\n\r\n  --%context(A new queue)\r\n\r\n    --%test(Cannot be created with non positive bounding capacity)\r\n    procedure non_positive_bounding_cap;\r\n\r\n  --%endcontext\r\nend;\r\n```\r\n\r\nThe new implementation would give the following results:\r\n\r\n| suitepath | description | name |\r\n|-----------|------------|------|\r\n| queue_spec | Queue specification | queue_spec |\r\n| queue_spec.nested_context_#1 | A new queue | nested_context_#1 |\r\n| queue_spec.nested_context_#1.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |\r\n\r\nTo give an explicit name to the context, users would use syntax:\r\n```sql\r\ncreate or replace package queue_spec as\r\n  --%suite(Queue specification)\r\n\r\n  --%context(A new queue)\r\n  --%name(a_new_queue)\r\n\r\n    --%test(Cannot be created with non positive bounding capacity)\r\n    procedure non_positive_bounding_cap;\r\n\r\n  --%endcontext\r\nend;\r\n```\r\n\r\n\r\n**Describe alternatives you've considered**\r\n\r\nAn alternative would be to convert the description into context name by:\r\n- making it lower-case\r\n- trimming leading and trailing whitespace and full stop characters\r\n- replacing all the whitespaces, full stops and special characters with underscores\r\n\r\nThis could work pretty well for some many use-cases.\r\n\r\n```sql\r\ncreate or replace package queue_spec as\r\n  --%suite(Queue specification)\r\n\r\n  --%context(A new queue)\r\n\r\n    --%test(Cannot be created with non positive bounding capacity)\r\n    procedure non_positive_bounding_cap;\r\n\r\n  --%endcontext\r\nend;\r\n```\r\n\r\nThe alternative implementation would give the following results:\r\n\r\n| suitepath | description | name |\r\n|-----------|------------|------|\r\n| queue_spec | Queue specification | queue_spec |\r\n| queue_spec.a_new_queue | A new queue | a_new_queue |\r\n| queue_spec.a_new_queue.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |\r\n\r\n\r\nWe would still need to use default context names if no description is provided.\r\n","author":{"url":"https://github.com/jgebal","@type":"Person","name":"jgebal"},"datePublished":"2019-10-28T12:08:38.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/1016/utPLSQL/issues/1016"}