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 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.
if a name is specified for the context, the name is used instead
if provided name is not valid, a warning is given and the name is defaulted to nested_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:
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.
The text was updated successfully, but these errors were encountered:
Current state
Currently
--%suite
and--%test
annotations takedescription
as argument.The
--%context
annotation doesn't allow that and expectsname
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:
With this package, current implementation of utPLSQL gives the following:
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.
The above is confusing, hard to remember and easy to confuse engineers.
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:
name
is specified for a context, the context name is defaulted tonested_context_#N
whereN
is the consecutive number of the context inside it's parent.name
is specified for the context, the name is used insteadname
is not valid, a warning is given and the name is defaulted tonested_context_#N
Given the original example.
The new implementation would give the following results:
To give an explicit name to the context, users would use syntax:
Describe alternatives you've considered
An alternative would be to convert the description into context name by:
This could work pretty well for some many use-cases.
The alternative implementation would give the following results:
We would still need to use default context names if no description is provided.
The text was updated successfully, but these errors were encountered: