Description
Current state
Currently --%suite and --%test annotations take description as argument.
The --%context annotation doesn't allow that and expects name to be given instead.
This is inconsistent and leads to confusion when using the framework.
Engineers expect simplicity and ease of use from the framework which isn't the case with --%context annotation.
Consider the below example:
create or replace package queue_spec as
--%suite(Queue specification)
--%context(A new queue)
--%test(Cannot be created with non positive bounding capacity)
procedure non_positive_bounding_cap;
--%endcontext
end;With this package, current implementation of utPLSQL gives the following:
| suitepath | description | name |
|---|---|---|
| queue_spec | Queue specification | queue_spec |
| queue_spec.A new queue | A new queue | A new queue |
| queue_spec.A new queue.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |
- The name of suite comes from package name and description from annotation
- The name of test comes from procedure name and description from annotation
- The name of context is take from annotation and description is copied from name
The 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.
utPLSQL does not give any warning on invalid context names too.
The proper implementation of the above package following current framework behavior should be more like below.
create or replace package queue_spec as
--%suite(Queue specification)
--%context(a_new_queue)
--%displayname(A new queue)
--%test(Cannot be created with non positive bounding capacity)
procedure non_positive_bounding_cap;
--%endcontext
end;The above is confusing, hard to remember and easy to confuse engineers.
| suitepath | description | name |
|---|---|---|
| queue_spec | Queue specification | queue_spec |
| queue_spec.a_new_queue | A new queue | a_new_queue |
| queue_spec.a_new_queue.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |
Describe the solution you'd like
I suggest to change the current behavior so that the --%context annotation accepts description as argument and is aligned with --%test and --suite annotations.
Framework 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.
Rules:
- if no
nameis specified for a context, the context name is defaulted tonested_context_#NwhereNis the consecutive number of the context inside it's parent. - if a
nameis specified for the context, the name is used instead - if provided
nameis not valid, a warning is given and the name is defaulted tonested_context_#N
Given the original example.
create or replace package queue_spec as
--%suite(Queue specification)
--%context(A new queue)
--%test(Cannot be created with non positive bounding capacity)
procedure non_positive_bounding_cap;
--%endcontext
end;The new implementation would give the following results:
| suitepath | description | name |
|---|---|---|
| queue_spec | Queue specification | queue_spec |
| queue_spec.nested_context_#1 | A new queue | nested_context_#1 |
| queue_spec.nested_context_#1.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |
To give an explicit name to the context, users would use syntax:
create or replace package queue_spec as
--%suite(Queue specification)
--%context(A new queue)
--%name(a_new_queue)
--%test(Cannot be created with non positive bounding capacity)
procedure non_positive_bounding_cap;
--%endcontext
end;Describe alternatives you've considered
An alternative would be to convert the description into context name by:
- making it lower-case
- trimming leading and trailing whitespace and full stop characters
- replacing all the whitespaces, full stops and special characters with underscores
This could work pretty well for some many use-cases.
create or replace package queue_spec as
--%suite(Queue specification)
--%context(A new queue)
--%test(Cannot be created with non positive bounding capacity)
procedure non_positive_bounding_cap;
--%endcontext
end;The alternative implementation would give the following results:
| suitepath | description | name |
|---|---|---|
| queue_spec | Queue specification | queue_spec |
| queue_spec.a_new_queue | A new queue | a_new_queue |
| queue_spec.a_new_queue.non_positive_bounding_cap | Cannot be created with non positive bounding capacity | non_positive_bounding_cap |
We would still need to use default context names if no description is provided.