utPLSQL单元测试框架由几个不同的元素组成：

• 一组存储关于单元测试与测试套件的信息的表
• 一组用于运行测试、构建测试包以及访问测试信息的包
  

用户指南描述了如何使用这些utPLSQL包。

1、utPLSQL包

utPLSQL包提供了以下功能：

• 运行测试。utPLSQL.test以及utPLSQL.run。
• 运行测试套件。utPLSQL.testsuite以及utPLSQL.runsuite。
• 获取utPLSQL版本。utPLSQL.version。
• 控制utPLSQL的跟踪机制。utPLSQL.trc、utPLSQL.notrc以及utPLSQL.tracing。
• 在测试包中注册单元测试。utPLSQL.addtest。

1.1、运行测试或测试套件

utPLSQL既可以运行测试包中的所有单元测试，也可以运行测试套件中定义的多个测试包中的测试。在运行测试之前，必须构建测试包。

使用utPLSQL.test过程运行单个包的测试：

PROCEDURE utPLSQL.test (
   package_in IN VARCHAR2,
   samepackage_in IN BOOLEAN := FALSE,
   prefix_in IN VARCHAR2 := NULL,
   recompile_in IN BOOLEAN := TRUE,
   dir_in IN VARCHAR2 := NULL,
   suite_in in VARCHAR2 := NULL,
   owner_in IN VARCHAR2 := NULL,
   reset_results_in IN BOOLEAN := TRUE ,
   from_suite_in         IN   BOOLEAN := FALSE,
   subprogram_in         IN   VARCHAR2 := '%',
   per_method_setup_in   IN   BOOLEAN := FALSE
);

参数定义如下表。

以下是一些示例。

1. 运行betwnstr函数的单元测试（由于使用了默认的前缀，执行ut_betwnstr测试包）。不重新编译测试包。

SQL> exec utPLSQL.test ('betwnstr', recompile_in => FALSE)

2. 运行包te_employee的全部单元测试，测试包位于/tmp目录中，名称为“test_te_employee”。执行测试之前重新编译测试包。

SQL> exec utPLSQL.test ('te_employee', prefix_in => 
                        'test_', dir_in => '/tmp')

3. 运行包corporate_polluters的全部单元测试，测试包与被测试代码位于相同的包中。

SQL> exec utPLSQL.test ('te_employee', samepackage_in => TRUE)

每次运行utPLSQL.test之后将会显示结果。如果测试成功，输出如下所示：

SUCCESS: "betwnstr"

如果测试失败，输入如下所示：

FAILURE: "betwnstr"
BETWNSTR: IS NULL: NULL start
BETWNSTR: End larger than string length; expected "cdeg", got "cdefg"

运行测试的另一种方法

以上描述的测试程序常用方法假设每个被测试的包，例如mypackage，拥有一个对应的测试包，名称为被测试包名加上一个前缀：ut_mypackage。除了该方法之外，还可以使用run过程。该过程直接运行测试包，不需要满足其他条件。唯一的条件是满足一个有效测试包的命名约定。

PROCEDURE run (
    testpackage_in      IN VARCHAR2,
    prefix_in           IN VARCHAR2 := NULL,
    suite_in            IN VARCHAR2 := NULL,
    owner_in            IN VARCHAR2 := NULL,
    reset_results_in    IN BOOLEAN  := TRUE,
    from_suite_in       IN BOOLEAN  := FALSE,
    subprogram_in       IN VARCHAR2 := '%',
    per_method_setup_id IN BOOLEAN  := FALSE);

参数定义如下表。

运行测试套件

除了运行单个测试包的测试之外，可以设置包含一个或多个测试包的测试套件。然后可以调用utPLSQL.testsuite运行整个测试套件。

PROCEDURE utPLSQL.testsuite (
   suite_in IN VARCHAR2,
   recompile_in IN BOOLEAN := TRUE,
   reset_results_in IN BOOLEAN := TRUE
   per_method_setup_in in BOOLEAN := FALSE
   );

其中suite_in为测试套件的名称，recompile_in决定了自动编译的方式。

以下是运行PL/Vision库全部测试的示例：

SQL> exec utplsql.testsuite ('plvision');

utPLSQL.testSuit的参数列表比utPLSQL.test少很多，可以在套件内部定义这些特性，存储在utPLSQL的表中。

在运行整个测试套件之前。必须定义测试套件。

运行测试套件的另一种方法

与测试单个包的run过程类似，runsuite过程用于运行测试套件。该过程不假设测试包名称与被测试程序之间存在任何关联。

PROCEDURE utPLSQL.runsuite (
   suite_in IN VARCHAR2,
   reset_results_in IN BOOLEAN := TRUE
   per_method_setup_in in BOOLEAN := FALSE
   );

参数的使用方法参见testsuite。

记录与访问测试统计信息

如果定义了测试套件，以及测试包，utPLSQL将会在每次测试之后更新以下统计信息：

• 最后一次运行状态：成功或者失败？
• 最后一次运行的开始时间与结束时间
• 失败总次数
• 测试总次数
  

以上信息自动执行统计。然后可以使用表ut_package与表ut_suite编写查询与报告。

2、返回utPLSQL版本

运行函数utPLSQL.version返回当前安装的版本。

FUNCTION utPLSQL.version RETURN VARCHAR2

3、utPLSQL跟踪

以下程序没有参数：

PROCEDURE trc;

PROCEDURE notrc;

FUNCTION tracing RETURN BOOLEAN;

程序trc与notrc分别用于打开与关闭跟踪功能。函数tracing在跟踪打开时返回TRUE，关闭时返回FALSE。这个功能对于编写框架代码自身很有用。以下是一个跟踪输出的示例：

Initialized utPLSQL session...
Setpkg to Lottery
Package and program = ut_Lottery
Same package? N
Is package? Y
Prefix = ut_
Recompiling ut_Lottery in
Runprog of ut_SETUP
Package and program = ut_Lottery.ut_SETUP
Same package? N
Is package? Y
Prefix = ut_
Addtest
Package and program = Lottery.UT_DRAW
Same package? N
Override? Y
Prefix = ut_
Runprog of UT_DRAW
Package and program = ut_Lottery.UT_DRAW
Same package? N
Is package? Y
Prefix = ut_
.
>  FFFFFFF   AA     III  L      U     U RRRRR   EEEEEEE
>  F               A  A     I   L      U     U       R    R  E
>  F              A    A    I   L      U     U         R     R E
>  F             A      A   I   L      U     U         R     R E
>  FFFF      A      A   I   L      U     U    RRRRRR  EEEE
>  F           AAAAAAAA   I   L      U     U R   R   E
>  F            A      A   I   L      U     U          R    R  E
>  F            A      A   I   L       U   U           R     R E
>  F            A      A  III  LLLLLLL  UUU   R     R EEEEEEE
.
FAILURE: "Lottery"
.
> Individual Test Case Results:
>
FAILURE - EQ "Test of DRAW" Expected "01 02 05 27 43 49" and 
                          got "02 04 27 28 31 33"
>
>
> Errors recorded in utPLSQL Error Log:
>
> NONE FOUND
Runprog of ut_TEARDOWN
Package and program = ut_Lottery.ut_TEARDOWN
Same package? N
Is package? Y
Prefix = ut_

PL/SQL procedure successfully completed.

4、注册单元测试

从1.4.1版起，不再需要显式注册单元测试。utPLSQL默认会从数据字典（ALL_ARGUMENTS视图）中提取所有单元测试程序的名称，然后运行测试。utPLSQL通过指定前缀查找这些程序。

如果想要显示注册单元测试，需要打开手动注册功能：

SQL> exec utConfig.registertest (TRUE)

该设置立即存储在当前模式的配置中。以下命名关闭手动注册功能：

SQL> exec utConfig.registertest (FALSE)

在设置程序中手动注册单元测试。这些单元测试的信息不进行永久保存，除非在测试套件中定义单元测试。

使用utPLSQL.addtest过程注册单元测试。

PROCEDURE utPLSQL.addtest (
      NAME_IN IN VARCHAR2,
      utprefix_in IN VARCHAR2,
      iterations_in IN PLS_INTEGER := 1
   );
 
   PROCEDURE utPLSQL.addtest (
      package_in IN VARCHAR2,
      NAME_IN IN VARCHAR2,
      utprefix_in IN VARCHAR2,
      iterations_in IN PLS_INTEGER := 1
   );

其中，name_in是单元测试程序的名称，包括前缀；utprefix_in当前未使用；iterations_in是该测试运行的次数，当前未使用；package_in是包含该单元测试程序的包名。如果指定了包名，将会覆盖utPLSQL.test中指定的包名，只对该测试有效。

以下是一个设置了一系列用于employee表查询封装的测试的设置程序。

CREATE OR REPLACE PACKAGE BODY ut_te_employee
IS
   PROCEDURE ut_setup
   IS
   BEGIN
      utplsql.addtest ('UT_EMP_DEPT_LOOKUPROWCOUNT');
      utplsql.addtest ('UT_EMP_JOB_LOOKUPROWCOUNT');
      utplsql.addtest ('UT_EMP_MGR_LOOKUPROWCOUNT');
      utplsql.addtest ('UT_HIRE_DATE$VAL');
      utplsql.addtest ('UT_I_EMPLOYEE_NAME$ROW');
      utplsql.addtest ('UT_I_EMPLOYEE_NAME$VAL');
      utplsql.addtest ('UT_ONEROW');
      utplsql.addtest ('UT_PKYROWCOUNT');
      utplsql.addtest ('UT_ROWCOUNT');
      utplsql.addtest ('UT_SALARY$VAL');
   END;