utPLSQL.github.io/utPLSQL/v2.3.1/utconfig.html at old_docs · utPLSQL/utPLSQL.github.io

636 lines (528 loc) · 22 KB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<!-- WARNING! This file is generated. -->
<!-- To alter documentation, edit files in src directory -->
<html xmlns="http://www.w3.org/1999/xhtml">
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>utConfig Package</title>
   <link rel="stylesheet" href="utplsql.css" type="text/css" />
   <meta name="keywords" content="utPLSQL, PL\SQL, Unit Testing, Framework, Oracle" />
   <meta name="description" content="Unit Testing PL\SQL" />
   <meta name="title" content="utConfig Package" />
   <meta name="author" content="Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
   <meta name="copyright" content="(C) 2000-2005, 2014-2016 Steven Feuerstein, Chris Rimmer, Patrick Barel and the utPLSQL Project" />
   <div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
   <p>[ <a href="index.html">Home</a>
 | <a href="started.html">Getting Started</a>
 | <a href="buildpack.html">Build Test Packages</a>
 | <a href="examples.html">Examples</a>
 | <a href="userguide.html">User Guide</a>
 | <a href="release.html">Release Notes</a>
 | <a href="map.html">Document Map</a> ]</p>
   <p><a href="utplsql.html">&lt; Previous Section: utPLSQL Package</a> | <a href="utresult.html">Next Section: utResult Package &gt;</a></p>
<!-- Begin utPLSQL Body -->
<!-- $Id$ -->
   <h1>utConfig Package</h1>
   <p>This package contains the following functions and procedures:</p>
   <table cellspacing="5">
         <td><a href="#Whoseconfig">utConfig.tester</a></td>
         <td><a href="#Whoseconfig">Return whose configuration is used</a></td>
      </tr>
         <td><a href="#setconfig">utConfig.settester</a></td>
         <td><a href="#setconfig">Set whose configuration is used</a></td>
      </tr>
         <td><a href="utconfig.html#Showconfig">utConfig.showconfig</a></td>
         <td><a href="utconfig.html#Showconfig">View a schema's configuration</a></td>
      </tr>
         <td><a href="#Setdir">utConfig.setdir</a></td>
         <td><a href="#Setdir">Set the directory containing the test package code</a></td>
      </tr>
         <td><a href="#dir">utConfig.dir</a></td>
         <td><a href="#dir">Return the directory containing the test package code</a></td>
      </tr>
         <td><a href="#Setprefix">utConfig.setprefix</a></td>
         <td><a href="#Setprefix">Set the default unit test prefix for your code</a></td>
      </tr>
         <td><a href="#prefix">utConfig.prefix</a></td>
         <td><a href="#prefix">Return the default unit test prefix for your code</a></td>
      </tr>
         <td><a href="#Manualregister">utConfig.registertest</a></td>
         <td><a href="#Manualregister">Set the registration mode (manual or automatic)</a></td>
      </tr>
         <td><a href="#Manualregister">utConfig.registering</a></td>
         <td><a href="#Manualregister">Return the registration mode</a></td>
      </tr>
         <td><a href="#Autocompile">utConfig.autocompile</a></td>
         <td><a href="#Autocompile">Set autocompile feature</a></td>
      </tr>
         <td><a href="#Autocompile">utConfig.autocompiling</a></td>
         <td><a href="#Autocompile">Return the autocompile flag</a></td>
      </tr>
         <td><a href="#Delimiter">utConfig.setdelimiter</a></td>
         <td><a href="#Delimiter">Set the V2 delimiter</a></td>
      </tr>
         <td><a href="#Delimiter">utConfig.delimiter</a></td>
         <td><a href="#Delimiter">Return the V2 delimiter</a></td>
      </tr>
         <td><a href="#ShowFailuresOnly">utConfig.showfailuresonly</a></td>
         <td><a href="#ShowFailuresOnly">Turn off the display of successful tests</a></td>
      </tr>
         <td><a href="#ShowFailuresOnly">utConfig.showingfailuresonly</a></td>
         <td><a href="#ShowFailuresOnly">Return whether successful test results are shown or not</a></td>
      </tr>
         <td><a href="#setgetreporter">utConfig.setreporter</a></td>
         <td><a href="#setgetreporter">Sets the default Output Reporter to use</a></td>
      </tr>
         <td><a href="#setgetreporter">utConfig.getreporter</a></td>
         <td><a href="#setgetreporter">Gets the name of the default Output Reporter to use</a></td>
      </tr>
         <td><a href="fileout.html#setfiledir">utConfig.setfiledir</a></td>
         <td><a href="fileout.html#setfiledir">Set the directory for file output</a></td>
      </tr>   
         <td><a href="fileout.html#setfiledir">utConfig.filedir</a></td>
         <td><a href="fileout.html#setfiledir">Return which directory is used for file output</a></td>
      </tr>
         <td><a href="fileout.html#filename1">utConfig.setuserprefix</a></td>
         <td><a href="fileout.html#filename1">Set the user prefix for output file names</a></td>
      </tr>
         <td><a href="fileout.html#filename1">utConfig.userprefix</a></td>
         <td><a href="fileout.html#filename1">Return the user prefix for output file names</a></td>
      </tr>
         <td><a href="fileout.html#filename2">utConfig.setincludeprogname</a></td>
         <td><a href="fileout.html#filename2">Set whether to include the name of the program being tested in output file names</a></td>
      </tr>
         <td><a href="fileout.html#filename2">utConfig.includeprogname</a></td>
         <td><a href="fileout.html#filename2">Return whether to include the name of the program being tested in output file names</a></td>
      </tr>
         <td><a href="fileout.html#filename3">utConfig.setdateformat</a></td>
         <td><a href="fileout.html#filename3">Set the date format for the date portion of output file names</a></td>
      </tr>
         <td><a href="fileout.html#filename3">utConfig.dateformat</a></td>
         <td><a href="fileout.html#filename3">Return the date format used to construct output file names</a></td>
      </tr>
         <td><a href="fileout.html#filename4">utConfig.setfileextension</a></td>
         <td><a href="fileout.html#filename4">Set the file extension for output file names</a></td>
      </tr>
         <td><a href="fileout.html#filename4">utConfig.fileextension</a></td>
         <td><a href="fileout.html#filename4">Return the file extension used for output file names</a></td>
      </tr>
         <td><a href="fileout.html#allinone">utConfig.setfileinfo</a></td>
         <td><a href="fileout.html#allinone">Set all of the above file output related items</a></td>
      </tr>
         <td><a href="fileout.html#allinone">utConfig.fileinfo</a></td>
         <td><a href="fileout.html#allinone">Return all of the above file output related items</a></td>
      </tr>
   </table>
      To make it as easy as possible for you to run your tests, utPLSQL stores
      various pieces of configuration data in the ut_config table. This data
      is stored by schema name and is automatically loaded into utPLSQL the first
      time you use this utility in your session. This configuration information
      is also automatically updated whenever you call utPLSQL.test -- or any
      of the utPLSQL programs specifically designed to change the configuration
      settings.
      You can at any time view the utPLSQL configuration for the currently-connected
      schema or for another schema (there is not at this point any schema-level
      security; all utPLSQL users can view the configurations of all other users).
   <p>The data that is currently maintained for a utPLSQL user are:</p>
      <b>Test package directory</b> - the location of the test package code
      you want to run. You must specify a directory in order to allow utPLSQL
      to automatically compile your test packages before each test run.
      <b>Unit test prefix</b> - the prefix used for test package names and
      the program names within the package. If you do not specify a prefix, the
      default of "ut_" is automatically applied.
      <b>Unit test registration mod</b>e - This setting determines whether
      utPLSQL will automatically identify the unit tests to be run (strongly
      recommended) or if you have chosen to manually register your unit tests
      in the test package setup procedure.
      <b>Auto-compilation of test packages</b> - By default, utPLSQL will
      recompile your test package before execution. You can turn off this feature
      and manually recompile only when you desire (a fine idea if your test package
      has gotten very large!).
   <h2><a name="Whoseconfig"></a>Return whose configuration is being used</h2>
      By default, the configuration stored for the currently-connected user will
      be used.  However, it is possible to use configurations stored against
      other usernames.  To show whose configuration is currently being used
      the following function is used:
FUNCTION utConfig.tester RETURN VARCHAR2;
   <h2><a name="setconfig"></a>Set whose configuration is being used</h2>
      This returns the configuration that will be used whenever a username is
      not specified.  To set this, the following procedure is used:
PROCEDURE utConfig.settester (username_in IN VARCHAR2 := USER);
   <h2><a name="Showconfig"></a>View a schema's configuration</h2>
      Call the utconfig.showconfig procedure to view the configuration for a specified
      schema. The header is:
PROCEDURE utConfig.showconfig (username_in IN VARCHAR2 := NULL);
      If you do not specify a schema, then the <a href="#Whoseconfig">currently
      used</a> configuration is returned. Here is an example of output from this
      procedure:
SQL&gt; exec utconfig.showconfig
=============================================================
utPLSQL Configuration for SCOTT
   Directory: /apps/utplsql/code
   Autcompile? Y
   Manual test registration? N
   Prefix = test_
=============================================================
   <p>And here is an example of calling showConfig for a different schema:</p>
SQL&gt; exec utconfig.showconfig ('COMP')
=============================================================
utPLSQL Configuration for COMP
   Directory: M:\shared_apps\utplsql\comp
   Autcompile? N
   Manual test registration? N
   Prefix = ut_
=============================================================
      You might want to put a call to showConfig in your SQL*Plus login file
      so that you are reminded on startup as to what the current settings are.
      Here is such a script (to be found in Examples\login_sample.sql):
exec utconfig.setdir ('e:\openoracle\utplsql\utinstall\examples')
SET SERVEROUTPUT ON SIZE 1000000 FORMAT WRAPPED
exec utconfig.showconfig
   <h2><a name="Setdir"></a>Set the directory containing the test package code</h2>
      If you want utPLSQL to compile your test package, you must tell it the
      directory in which your code is found. You can do this either when you
      <a href="defsuite.html">define your test suite</a> and packages within the suite, or you can call the
      utConfig.setdir procedure to set the directory for your current session.
      Note: as of v1.5.1, the value you pass in any of these programs is saved
      in the configuration table and will be used in the future -- until you
      change it by passing a different value.
   <p>The header for this procedure is:</p>
PROCEDURE utConfig.setdir (dir_in IN VARCHAR2, username_in IN VARCHAR2 := NULL);
      where dir_in is the directory and username_in is the name of the schema
      to which this directory applies (NULL means the <a href="#Whoseconfig">currently
      used</a> configuration is set), as in:
SQL&gt; exec utconfig.setdir ('e:\demo\utplsql');
   <p>or, with the specification of a non-current schema:</p>
SQL&gt; exec utconfig.setdir ('e:\demo\utplsql', 'ANALYSIS');
   <p>Note that this directory must be accessible through UTL_FILE.</p>
      You might consider putting the the call to utConfig.setdir into your
      login.sql so that it is run automatically, each time your start up SQL*Plus
      -- if you are always working from the same directory.
   <h2><a name="dir"></a>Return the directory containing the test package code</h2>
   <p>You can obtain the current directory with a call to utConfig.dir:</p>
FUNCTION utConfig.dir (username_in IN VARCHAR2 := NULL)
      RETURN VARCHAR2;
   <h2><a name="Setprefix"></a>Set the default unit test prefix for your code.</h2>
      The unit test prefix is very important in utPLSQL; the utility uses the
      prefix to associate source code to be tested with the test package. The
      prefix also allows utPLSQL to automatically identify the programs within
      a test package that are to be executed as unit tests.
      The default prefix in utPLSQL is "ut_", but you can override this when
      you call utPLSQL.test or by calling the utConfig.setprefix procedure:
PROCEDURE utConfig.setPrefix (
   prefix_in IN VARCHAR2, username_in IN VARCHAR2 := NULL)
      where prefix_in is the prefix and username_in is the name of the schema
      to which this prefix applies (NULL means the <a href="#Whoseconfig">currently
      used</a> configuration is set), as in:
SQL&gt; exec utconfig.setPrefix ('tst#');
   <p>or, with the specification of a non-current schema:</p>
SQL&gt; exec utconfig.setPrefix ('t_', 'ANALYSIS');
   <h2><a name="prefix"></a>Return the default unit test prefix for your code.</h2>
   <p>You can obtain the current prefix with a call to utConfig.prefix:</p>
FUNCTION utConfig.prefix (username_in IN VARCHAR2 := NULL)
      RETURN VARCHAR2;
      uPLSQL currently does not support the use of a suffix, or combination of
      suffix and prefix, to identify test packages and unit test procedures.
   <h2><a name="Manualregister"></a>Set the registration mode (manual or automatic).</h2>
      As of utPLSQL v1.5.1, you no longer have to register your unit test procedures
      in the setup procedure of your test package. Instead, utPLSQL will scan
      the data dictionary (via theALL_ARGUMENTS view) for the names of all the
      unit test procedures you have defined, and then run them. utPLSQL identifies
      these programs by looking for all programs whose names start with the specified
      prefix.
      If you so choose, you can request that utPLSQL turn off automatic detection
      of unit test procedures and only run those programs listed in the setup
      procedure. To do this, you call the utConfig.registerTest procedure:
PROCEDURE utConfig.registerTest (
      onoff_in IN BOOLEAN,
      username_in IN VARCHAR2 := NULL
   <p>as in:</p>
SQL&gt; exec utConfig.registerTest (TRUE)
      Note: if you are using automatic unit test detection, any calls to utPLSQL.addtest
      in the setup procedure <i><b>will be ignored</b>.</i>
   <p>You can return the current registration mode using the following function:</p>
FUNCTION registeringtest (username_in IN VARCHAR2 := NULL)
   RETURN BOOLEAN;
   <p>This returns TRUE if the registration mode has been set to manual and FALSE otherwise.</p>
   <h2><a name="Autocompile"></a>Set autocompile feature</h2>
      The default settings for utPLSQL is to re-compile
      your base package before each unit test. This guarantees that any recent
      changes will be tested. It also saves you the step of doing an explicit
      compile.
   <p>In order to perform automatic compilation:</p>
         Your schema will need to
         have either CREATE PROCEDURE or CREATE ANY PROCEDURE privileges granted
         <i>directly</i>;
         you cannot grant these privileges through roles.
      </li>
         You will need to set or
         pass the location of the source code. You can do this by calling <a href="#Setdir">utConfig.setdir</a>
         or by including the directory location in your call to <a href="utplsql.html#utplsql.test">utPLSQL.test</a>
         or <a href="utplsql.html#utplsql.testsuite">utPLSQL.testsuite</a> (the dir_in
         parameter).
      </li>
         The package specification
         must be contained in a file named &lt;package&gt;.pks; the body must be stored
         in &lt;package&gt;.pkb.
      </li>
         You must have configured
         the
         <a href="admin.html#UTL_FILE">UTL_FILE</a> built-in package for use
         on your database instance.
      </li>
      In general (and the default), you should allow your
      test package to be recompiled with each execution. You might want to avoid
      recompilation if:
         You have made a copy of the package body with some
         temporary changes and already compiled that. If you recompile automatically,
         you will wipe out those changes.
      </li>
         You have not set up UTL_FILE
         and you don't want to deal with it.
      </li>
         You are running the tests
         on a server to which you have no access other than via a database connection.
      </li>
   <h3>Turning off Auto-compile</h3>
      If you are working with products like SQL*Navigator,
      you may be always editing from code stored in the database. In this case,
      you will never want to have utPLSQL recompile your code for you - it will
      already be compiled and you do not need to hassle with UTL_FILE.
   <p>You can avoid auto-recompilation in two ways:</p>
      1. Pass a value of FALSE for the recompile_in argument
      to utPLSQL.test or utPLSQL.testsuite. Here is an example:
   -- Define a test suite for PL/Vision
   utsuite.add ('PLVision');
   -- Add two packages for testing
   utsuite.addpkg (
      'PLVision', 'PLVstr', dir_in =&gt; 'e:\utplsql');
   utsuite.addpkg (
      'PLVision', 'PLVdate', dir_in =&gt; 'e:\utplsql');
   -- Run the test suite
   utplsql.testsuite (
      'PLVision', recompile_in =&gt; FALSE);
      If you know that you will <i>never</i> want to recompilation,
      however, you can set the default behavior at the schema level by calling
      the autocompile procedure
   PROCEDURE utConfig.autocompile (
      onoff_in IN BOOLEAN,
      username_in IN VARCHAR2 := NULL
      So I can make the following
      call to turn off autocompilation for the SCOTT schema:
SQL&gt; exec utconfig.autocompile (FALSE, 'SCOTT')
      This program updates the ut_config table with your information and then
      commits the setting.
      You can determine the current
      setting for auto-compilation at any time by calling the following function:
   FUNCTION utConfig.autocompiling (username_in IN VARCHAR2 := NULL)
      RETURN BOOLEAN;
      Note: When you set the schema-level recompilation
      value to FALSE, that will override anything you pass in a call to utPLSQL.test
      or utPLSQL.testsuite.
   <h2><a name="Delimiter"></a>V2 Delimiter</h2>
   <p>You can set the delimiter to be used in V2 procedure names using the following procedure:</p>
PROCEDURE setdelimiter (
  delimiter_in IN VARCHAR2, 
  username_in IN VARCHAR2 := NULL
   <p>while the current delimiter can be obtained by the function:</p>
FUNCTION delimiter (username_in IN VARCHAR2 := NULL)
  RETURN VARCHAR2;
   <h2><a name="ShowFailuresOnly">Turn off the display of successful test results</a></h2>
      By default, the results of all the tests are shown.  This includes both successful and unsuccessful
      results.  The following procedure allows you to limit the tests shown to only those that have failed:
PROCEDURE showfailuresonly (
     onoff_in      IN   BOOLEAN,
     username_in   IN   VARCHAR2 := NULL
   <p>the current setting can be obtained by the function:</p>
FUNCTION showingfailuresonly (username_in IN VARCHAR2 := NULL)
      RETURN BOOLEAN;
   <h2><a name="setgetreporter">Set and Get the default output reporter</a></h2>
      By default, all results are sent to the screen via DBMS_OUTPUT.  However, it is possible to use other output reporters as described in more detail
      on <a href="reporter.html">this page</a>.  The following procedure allows you to set which output reporter should be used by default:
PROCEDURE setreporter (
      reporter_in   IN   VARCHAR2
     ,username_in   IN   VARCHAR2 := NULL
   <p>as usual, the current setting can be obtain by the following function:</p>
FUNCTION getreporter (username_in IN VARCHAR2 := NULL)
      RETURN VARCHAR2;
<!-- End utPLSQL Body -->
   <p><a href="utplsql.html">&lt; Previous Section: utPLSQL Package</a> | <a href="utresult.html">Next Section: utResult Package &gt;</a></p>
   <div class="purple_bar"><a href="index.html"><img src="utplsql.jpg" alt="utPLSQL logo" /></a></div>
      <a href="http://validator.w3.org/check?uri=referer">
         <img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0 Strict" height="31" width="88" />
   <p class="copyright">Copyright &copy; 2000-2005, 2014-2016 <a href="mailto:steven@stevenfeuerstein.com">Steven Feuerstein</a>, <a href="mailto:c@24.org.uk">Chris Rimmer</a>, <a href="mailto:pbarel@vda.nl">Patrick Barel</a> and the utPLSQL Project. All rights reserved</p>
Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

utconfig.html

Latest commit

History

utconfig.html

File metadata and controls
