Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 6e95077

Browse files
jgebaljgebal
authored
Merge pull request #613 from utPLSQL/feature/documentation_improvements
Fixed misleading naming in documentation
2 parents 812e0ce + 6e6e285 commit 6e95077

3 files changed

Lines changed: 44 additions & 33 deletions

File tree

‎docs/userguide/annotations.md‎

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -108,19 +108,19 @@ end test_pkg;
108108

109109
| Annotation |Level| Description |
110110
| --- | --- | --- |
111-
| `%suite(<description>)` | Package | Mandatory. Marks package as a test suite. Optional suite description can be provided (see `displayname`). |
112-
| `%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarchies. |
113-
| `%displayname(<description>)` | Package/procedure | Human-readable and meaningful description of a suite/test. `%displayname(Name of the suite/test)`. The annotation is provided for flexibility and convenience only. It has exactly the same meaning as `<description>` in `test` and `suite` annotations. If description is provided using both `suite`/`test` and `displayname`, then the one defined as last takes precedence. |
114-
| `%test(<description>)` | Procedure | Denotes that the annotated procedure is a unit test procedure. Optional test description can by provided (see `displayname`). |
115-
| `%throws(<exception_number>[,<exception_number>[,...]])`| Procedure | Denotes that the annotated procedure must throw one of the exception numbers provided. If no valid numbers were provided as annotation parameters the annotation is ignored. Applicable to test procedures only. |
116-
| `%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the suite. |
117-
| `%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the suite. |
118-
| `%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` procedure in the suite. |
119-
| `%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` procedure in the suite. |
120-
| `%beforetest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed before the annotated `%test` procedure. |
121-
| `%aftertest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
122-
| `%rollback(<type>)` | Package/procedure | Defines transaction control. Supported values: `auto`(default) - a savepoint is created before invocation of each "before block" is and a rollback to specific savepoint is issued after each "after" block; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
123-
| `%disabled` | Package/procedure | Used to disable a suite or a test. Disabled suites/tests do not get executed, they are however marked and reported as disabled in a test run. |
111+
| `--%suite(<description>)` | Package | Mandatory. Marks package as a test suite. Optional suite description can be provided (see `displayname`). |
112+
| `--%suitepath(<path>)` | Package | Similar to java package. The annotation allows logical grouping of suites into hierarchies. |
113+
| `--%displayname(<description>)` | Package/procedure | Human-readable and meaningful description of a suite/test. `%displayname(Name of the suite/test)`. The annotation is provided for flexibility and convenience only. It has exactly the same meaning as `<description>` in `test` and `suite` annotations. If description is provided using both `suite`/`test` and `displayname`, then the one defined as last takes precedence. |
114+
| `--%test(<description>)` | Procedure | Denotes that the annotated procedure is a unit test procedure. Optional test description can by provided (see `displayname`). |
115+
| `--%throws(<exception_number>[,<exception_number>[,...]])`| Procedure | Denotes that the annotated procedure must throw one of the exception numbers provided. If no valid numbers were provided as annotation parameters the annotation is ignored. Applicable to test procedures only. |
116+
| `--%beforeall` | Procedure | Denotes that the annotated procedure should be executed once before all elements of the suite. |
117+
| `--%afterall` | Procedure | Denotes that the annotated procedure should be executed once after all elements of the suite. |
118+
| `--%beforeeach` | Procedure | Denotes that the annotated procedure should be executed before each `%test` procedure in the suite. |
119+
| `--%aftereach` | Procedure | Denotes that the annotated procedure should be executed after each `%test` procedure in the suite. |
120+
| `--%beforetest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed before the annotated `%test` procedure. |
121+
| `--%aftertest(<procedure_name>)` | Procedure | Denotes that mentioned procedure should be executed after the annotated `%test` procedure. |
122+
| `--%rollback(<type>)` | Package/procedure | Defines transaction control. Supported values: `auto`(default) - a savepoint is created before invocation of each "before block" is and a rollback to specific savepoint is issued after each "after" block; `manual` - rollback is never issued automatically. Property can be overridden for child element (test in suite) |
123+
| `--%disabled` | Package/procedure | Used to disable a suite or a test. Disabled suites/tests do not get executed, they are however marked and reported as disabled in a test run. |
124124

125125
# Suitepath concept
126126

‎docs/userguide/expectations.md‎

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -165,7 +165,7 @@ end;
165165
## be_empty
166166
Unary matcher that validates if the provided dataset is empty.
167167

168-
Can be used with `refcursor` or `table type`
168+
Can be used with `refcursor` or `nested table`/`varray` passed as `ANYDATA`
169169

170170
Usage:
171171
```sql
@@ -179,7 +179,16 @@ begin
179179
end;
180180
```
181181

182-
When used with anydata, it is only valid for collection data types.
182+
```sql
183+
procedure test_if_cursor_is_empty is
184+
l_data ut_varchar2_list;
185+
begin
186+
l_data := ut_varchar2_list();
187+
ut.expect( anydata.convertCollection( l_data ) ).to_be_empty();
188+
--or
189+
ut.expect( anydata.convertCollection( l_data ) ).to_( be_empty() );
190+
end;
191+
```
183192

184193
## be_false
185194
Unary matcher that validates if the provided value is false.
@@ -420,7 +429,7 @@ The `a_nulls_are_equal` parameter controls the behavior of a `null = null` compa
420429
To change the behavior of `NULL = NULL` comparison pass the `a_nulls_are_equal => false` to the `equal` matcher.
421430

422431

423-
## Comparing objects, cursors, collections of data
432+
## Comparing cursors, object types, nested tables and varrays
424433

425434
utPLSQL is capable of comparing compound data-types including:
426435
- ref cursors
@@ -434,7 +443,7 @@ utPLSQL is capable of comparing compound data-types including:
434443
- Comparison of cursor columns containing `DATE` will only compare date part **and ignore time** by default. See [Comparing cursor data containing DATE fields](#comparing-cursor-data-containing-date-fields) to check how to enable date-time comparison in cursors.
435444
- To compare nested table/varray type you need to convert it to `anydata` by using `anydata.convertCollection()`
436445
- To compare object type you need to convert it to `anydata` by using `anydata.convertObject()`
437-
- It is possible to compare PL/SQL records and nested tables/varrays/associative arrays of PL/SQL records. To compare this types of data, use cursor comparison feature of utPLSQL and TABLE operator in SQL query
446+
- It is possible to compare PL/SQL records, collections, varrays and associative arrays. To compare this types of data, use cursor comparison feature of utPLSQL and TABLE operator in SQL query
438447
- On Oracle 11g Release 2 - pipelined table functions are needed (see section [Implicit (Shadow) Types in this artcile](https://oracle-base.com/articles/misc/pipelined-table-functions))
439448
- On Oracle 12c and above - use [TABLE function on nested tables/varrays/associative arrays of PL/SQL records](https://oracle-base.com/articles/12c/using-the-table-operator-with-locally-defined-types-in-plsql-12cr1)
440449

@@ -568,16 +577,16 @@ When comparing rows utPLSQL:
568577
- reports whole missing (expected) row from expected when expected has extra rows
569578

570579

571-
### Object and collection data-type comparison examples
580+
### Object and nested table data-type comparison examples
572581

573-
When comparing object type to object type or collection to collection, utPLSQL will check:
582+
When comparing object type / nested table / varray, utPLSQL will check:
574583
- if data-types match
575-
- if data in the compared objects/collections are the same.
584+
- if data in the compared elements is the same.
576585

577-
The diff functionality for objects and collections is similar to diff on cursors.
578-
When diffing objects/collections however, utPLSQL will not check attribute names and data-types.
586+
The diff functionality for objects / nested tables / varrays is similar to diff on cursors.
587+
When diffing, utPLSQL will not check name and data-type of individual attribute as the type itself defines the underlying structure.
579588

580-
Below examples demonstrate how to compare object and collection data-types.
589+
Below examples demonstrate how to compare object and nested table data-types.
581590

582591
Object type comparison.
583592
```sql
@@ -589,7 +598,7 @@ begin
589598
end;
590599
/
591600
create or replace package demo_dept as
592-
-- %suite(demo)
601+
--%suite(demo)
593602

594603
--%test(demo of object to object comparison)
595604
procedure test_department;
@@ -626,7 +635,7 @@ begin
626635
end;
627636
/
628637
create or replace package demo_depts as
629-
-- %suite(demo)
638+
--%suite(demo)
630639

631640
--%test(demo of collection comparison)
632641
procedure test_departments;
@@ -773,19 +782,21 @@ The matrix below illustrates the data types supported by different matchers.
773782

774783
| | be_between | be_empty | be_false | be_greater_than | be_greater_or_equal | be_less_or_equal | be_less_than | be_like | be_not_null | be_null | be_true | equal | have_count | match |
775784
|:------------------------------|:----------:|:--------:|:--------:|:---------------:|:-------------------:|:----------------:|:------------:|:-------:|:-----------:|:-------:|:-------:|:-----:|:----------:|:-----:|
776-
| anydata( collection, object ) | | X | | | | | | | X | X | | X | X | |
777785
| blob | | | | | | | | | X | X | | X | | |
778786
| boolean | | | X | | | | | | X | X | X | X | | |
779787
| clob | | | | | | | | X | X | X | | X | | X |
780788
| date | X | | | X | X | X | X | | X | X | | X | | |
781789
| number | X | | | X | X | X | X | | X | X | | X | | |
782-
| refcursor | | X | | | | | | | X | X | | X | X | |
783790
| timestamp | X | | | X | X | X | X | | X | X | | X | | |
784791
| timestamp with timezone | X | | | X | X | X | X | | X | X | | X | | |
785792
| timestamp with local timezone | X | | | X | X | X | X | | X | X | | X | | |
786793
| varchar2 | X | | | | | | | X | X | X | | X | | X |
787794
| interval year to month | X | | | X | X | X | X | | X | X | | X | | |
788795
| interval day to second | X | | | X | X | X | X | | X | X | | X | | |
796+
| refcursor | | X | | | | | | | X | X | | X | X | |
797+
| nested table (as anydata) | | X | | | | | | | X | X | | X | X | |
798+
| varray (as anydata) | | X | | | | | | | X | X | | X | X | |
799+
| object (as anydata) | | | | | | | | | X | X | | X | | |
789800

790801

791802

‎docs/userguide/getting-started.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ This way, we assure we don't jump ahead too much and produce code that is untest
2525
```sql
2626
create or replace package test_betwnstr as
2727

28-
-- %suite(Between string function)
28+
--%suite(Between string function)
2929

3030
end;
3131
/
@@ -46,9 +46,9 @@ Finished in .451423 seconds
4646
```sql
4747
create or replace package test_betwnstr as
4848

49-
-- %suite(Between string function)
49+
--%suite(Between string function)
5050

51-
-- %test(Returns substring from start position to end position)
51+
--%test(Returns substring from start position to end position)
5252
procedure basic_usage;
5353

5454
end;
@@ -201,12 +201,12 @@ A new requirement was added:
201201
```sql
202202
create or replace package test_betwnstr as
203203

204-
-- %suite(Between string function)
204+
--%suite(Between string function)
205205

206-
-- %test(Returns substring from start position to end position)
206+
--%test(Returns substring from start position to end position)
207207
procedure basic_usage;
208208

209-
-- %test(Returns substring when start position is zero)
209+
--%test(Returns substring when start position is zero)
210210
procedure zero_start_position;
211211

212212
end;

0 commit comments

Comments
 (0)