Allow before/after annotations to accept list of [[owner.]package.]procedure

[jgebal]

I'd like to suggest the following to the before..., after... annotations.

• add ability to reference procedures from other packages
• add ability to call multiple procedures

Additionally, beforeall, afterall, beforeeach, aftereach, we could be suite level annotations with similar syntax as beforetest/aftertest.
Example below:

package test_departments_api is

  --%suite(Departments API)
  --%beforeall(common_data_helper.data_setup, privileges_helper.setup)
  --%afterall(privileges_helper.cleanup, common_data_helper.data_cleanup)


  procedure setup_manager;

  --%test(Adds department)
  --%beforetest(some_package.add_employee, some_package.add_location, setup_manager)
  procedure successfully_add_department;

  --%test(Fails to add depatrment when no manager found)
  --%beforetest(common_employee_helper.setup_employee, common_location_helper.setup_location)
  procedure fail_to_add_department;

  --%test(Returns department by name)
  --%beforetest(common_department_helper.setup_depatment)
  procedure get_department_by_name;

end;

This way, we can allow for even better separation of common things.
It is still possible to achieve the same without before/after annotations referencing procedures outside of package, but it requires a lot of bolierplate code as below.

package test_departments_api is

  --%suite(Departments API)

  --%beforeall
  procedure common_setup;
  
  --%afterall
  procedure common_cleanup;

  procedure setup_manager;

  --%test(Adds department)
  --%beforetest(some_package.add_employee, some_package.add_location, setup_manager)
  procedure successfully_add_department;

  --%test(Fails to add depatrment when no manager found)
  --%beforetest(common_employee_helper.setup_employee, common_location_helper.setup_location)
  procedure fail_to_add_department;

  --%test(Returns department by name)
  --%beforetest(common_department_helper.setup_depatment)
  procedure get_department_by_name;

end;
/
...
package body test_departments_api is

  procedure common_setup is
  begin
    common_data_helper.data_setup;
    privileges_helper.setup;
  end;

  procedure common_cleanup is
  begin
    privileges_helper.cleanup;
    common_data_helper.data_cleanup;
  end;

...

Would it make sence and add value to have this kind of flexibility in annotations?

The down side I see is that we would only know at runtime if the dependencies to other packages defined by before/after are valid.

[jgebal]

One challenge to overcome at the moment is a scenario when we have one of annotations: --%beforeall, --%afterall, --%beforeeach, --%aftereach defined at both procedure and suite level

Example:

package test_departments_api is

  --%suite(Departments API)
  --%beforeall(common_data_helper.data_setup, privileges_helper.setup)
  --%afterall(privileges_helper.cleanup, common_data_helper.data_cleanup)

  --%beforeall
  procedure setup_manager;

  --%test(Adds department)
  procedure successfully_add_department;

end;

In this case order of execution should be defined by order of annotations in spec.

So the execution flow would be:

common_data_helper.data_setup;
privileges_helper.setup;
setup_manager;

The challenge in this case is maintaining order of execution.

This is mainly because we interpret the package and procedure level annotations separately as they need to be handled differently.

So we would need to build an ordered list of before/after all/each elements like:

subtype annoation_line_no is binary_integer;
type t_annotation_items_list is table of varchar2(250) index by binary_integer;
type t_annotations_list is table of t_annotation_items_list index by annoation_line_no;

This way we can slot --%beforeall items into the list and then take items out of the list in correct order.

It will be tricky to code it in a way that it's clean and clear what the intention behind the code

[lwasylow]

@jgebal not entirely sure I understood the line about before all in suite level. Since we have a one suite per package definition of that in package would only make sense if that work for all other suites under that suitepath. However because each is in separate package it can became unclear where some operations happened if parent suite got before all that spans on all child ones. Even worse if the design someone start relying on these setup making dependencies between suites, not sure if that would be behaviour we want to encourage.