Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consistent syntax for suite/test/context annotations #1016

Closed
jgebal opened this issue Oct 28, 2019 · 0 comments · Fixed by #1013

Comments

@jgebal
Copy link
Member

@jgebal jgebal commented Oct 28, 2019

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.

jgebal added a commit that referenced this issue Oct 28, 2019
Changed behavior of ``--%context` annotation. The value f annotation now only indicates the context description.
Resolves #1016
@jgebal jgebal closed this in #1013 Nov 1, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
1 participant
You can’t perform that action at this time.