Create test listing API

[jgebal]

We need to expose following API within ut_runner:

• is_suite - return 'Y' if given owner, package is a unit test suite, else return 'N'
• get_suites_list - return a list of package with corresponding suitepath and description
  for a given owner
• get_tests_list - return a list of test_procedure with corresponding description
  for a given owner and package
• get_suitepaths - return a list of suitepaths for a given owner

All of functions should make use of ut_annotation_manager to assure retrieval of up-to-date information

[PhilippSalvisberg]

To check if executable tests exist for a given owner, I have to call get_suites_list and get_tests_list for every packages found. Is it possible to make the package parameter optional for the get_test_list call? This would reduce the overall number of calls.

How about disabled tests? Should they be included or ignored? Or should this be configurable?

[pesse]

Will keep an eye on this and provide support in java-api as soon as it's ready

[Pazus]

I think the API should provide as much info as possible including objects and even lines (if able) of the test procedure declaration. The whole structure and parameters of the test should be provided including tags that will be introduced shortly and display names, setups/teardowns for each test etc

[jgebal]

The base for all the info about test/suite will this query on annotations API.

select o.object_owner, o.object_name, a.subobject_name, a.name annotation, a.text annotation_text
  from table(ut3.ut_annotation_manager.get_annotated_objects('UT3_TESTER', 'PACKAGE')) o,
  table(o.annotations) a
  where exists (select 1 from table(o.annotations) s where s.name='suite')

We can make the API public "as-is", by just adding a pass-through function in ut_runner
Alternatively, we can use few flavors of the above query to extract exact information needed.

Pass through seems a quick-win and puts the burden of interpreting annotations on the client-side.

On the other side the well-defined API seems more elegant.

[pesse]

I think flavor is easier to be done in java API. Would suggest to go for the quick win and Let me build the API around it while you focus on other things.
After all the test Listing API is something for IDE mainly and I'd like to encourage ppl to use java-api for that

[jgebal]

Will this be sufficient?

  /**
  * Returns a ref_cursor containing information about unit tests package(s) for given owner
  *
  * @param   a_owner        owner of unit tests to retrieve
  * @param   a_package_name optional name of unit test package to retrieve, if NULLm all unit test packages are returned
  * @return  sys_refcursor  columns: OWNER, PACKAGE_NAME, PROCEDURE_NAME, ANNOTATION, ANNOTATION_TEXT
  */
  function get_unit_tests_info(a_owner varchar2, a_package_name varchar2 := null) return sys_refcursor;

If you feel like it would be better, I could create a pipelined function.

[PhilippSalvisberg]

Will this be sufficient?

Technically yes.

If you feel like it would be better, I could create a pipelined function.

I agree. I do not like a week cursor to be part of an API. A function returning a collection type would be better, makes the content explicit without relying on documentation.

Personally I would also remove the following filter:

exists (select 1 from table(o.annotations) s where s.name='suite')

When the burden of interpreting annotations is on the client-side, then it should be completely on the client side. E.g. this way it would be possible to write code on the client side which identifies packages without suite annotations but with procedures annotated with test.

[jgebal]

I'll then expose just the get_annotated_packages
It will return what you now get from calling:

ut3.ut_annotation_manager.get_annotated_objects(:user, 'PACKAGE')

[jgebal]

I have it now exposed as:

  type t_annotation_rec is record (
    package_owner   varchar2(250),
    package_name    varchar2(250),
    procedure_name  varchar2(250),
    annotation_pos  number(5,0),
    annotation_name varchar2(1000),
    annotation_text varchar2(4000)
  );
  type tt_annotations is table of t_annotation_rec;

  /**
  * Returns a pipelined collection containing information about unit tests package/packages for a given owner
  *
  * @param   a_owner        owner of unit tests to retrieve
  * @param   a_package_name optional name of unit test package to retrieve, if NULLm all unit test packages are returned
  * @return  tt_annotations table of records
  */
  function get_unit_test_info(a_owner varchar2, a_package_name varchar2 := null) return tt_annotations pipelined;

I have also removed the filter from query - so you get all the annotated packages.

[jgebal]

Example queries:

select x.pacakge_owner, x.pacakge_name, a.procedure_name, 
       x.annotation_pos, x.annotation_name, a.annotation_text
  from table(ut_runner.get_unit_test_info( :owner )) x

or

select x.pacakge_owner, x.pacakge_name, a.procedure_name,
      x.annotation_pos, x.annotation_name, a.annotation_text
  from table(ut_runner.get_unit_test_info( :owner, :package_name )) x

[jgebal]

Is the flattened structure any better than the original one in ut_annotation_manager.get_annotated_objects?

[PhilippSalvisberg]

Looks good. I like this flattened structure. Thanks. Should be easy for @pesse to include in the Java API, which I will use in the extension.

BTW: Is the annotation_position equal to the line of code where the annotation is found? If yes, I would rename it to annotation_line.

[jgebal]

Unfortunately, it's just an index number (1,2,3 ect.)
Because annotation parser strips comment lines from package spec before it searches for annotations, the line numbers are lost.
Stripping comment blocks is required to avoid parsing false annotations (placed inside a multi-line comment block)

[PhilippSalvisberg]

Thanks @jgebal for the clarification. annotation_pos sounds reasonable now!

[PhilippSalvisberg]

If line and column are of interest, you could replace the comment blocks with spaces. I've done that in the in method setPlsqlReduced of UtplsqlParser.xtend. But this will most probably have a negative effect on parsing time.