Consistent syntax for suite/test/context annotations

[jgebal]

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 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:

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.