<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
 <section xml:id="oci8.test">
  <title xmlns="http://docbook.org/ns/docbook">Testing</title>
   <section xml:id="oci8.testing" xmlns="http://docbook.org/ns/docbook">
    <para>
     The OCI8 test suite is in <filename>ext/oci8/tests</filename>.
     After OCI8 tests are run this directory will also contain logs of
     any failures.
    </para>
   </section>
   <section>
    <para>
     Before running PHP's tests, edit <filename>details.inc</filename>
     and set $user, $password and the $dbase connection string.  The
     OCI8 test suite has been developed using
     the <literal>SYSTEM</literal> account.  Some tests will fail if
     the test user does not have equivalent permissions.
    </para>
    <para>
     If Oracle Database Resident Connection Pooling is being
     tested, set $test_drcp to &true; and ensure the
     connection string uses an appropriate DRCP pooled server.
    </para>
    <para>
     An alternative to editing <filename>details.inc</filename> is the
     set environment variables, for example:
     <programlisting>
<![CDATA[
    $ export PHP_OCI8_TEST_USER=system
    $ export PHP_OCI8_TEST_PASS=oracle
    $ export PHP_OCI8_TEST_DB=localhost/XE
    $ export PHP_OCI8_TEST_DRCP=FALSE
]]>
     </programlisting>
     Note in some shells these variables are not propagated correctly
     to the PHP process and tests will fail to connect if this method
     is used.
    </para>
    <para>
     Next, set any necessary environment for the Oracle database.  If you are
     running PHP on the same machines as Oracle Database, you can run:
   <programlisting>
<![CDATA[
    $ . /usr/local/bin/oraenv
]]>
   </programlisting>
    </para>
    <para>
     With Oracle 11<emphasis>g</emphasis>R2 XE do:
     <programlisting>
<![CDATA[
    $ . /u01/app/oracle/product/11.2.0/xe/bin/oracle_env.sh
]]>
     </programlisting>
    </para>
    <para>
     Some shells require that &php.ini; has <literal>E</literal> in the
     variables_order parameter, for example:
     <programlisting>
<![CDATA[
    variables_order = "EGPCS"
]]>
     </programlisting>
    </para>
    <para>
     Run all the PHP tests with:
   <programlisting>
<![CDATA[
    $ cd your_php_src_directory
    $ make test
]]>
   </programlisting>
   or run only the OCI8 tests with
   <programlisting>
<![CDATA[
    $ cd your_php_src_directory
    $ make test TESTS=ext/oci8
]]>
   </programlisting>
    </para>
    <para>
      When the tests have completed, review any test failures. On slow
      systems, some tests may take longer than the default test
      timeout in <filename>run-tests.php</filename>.  To correct this,
      set the environment variable <literal>TEST_TIMEOUT</literal> to
      a larger number of seconds.
    </para>
    <para>
     On fast machines with a local database configured for light load
     (e.g. Oracle 11<emphasis>g</emphasis>R2 XE) some tests might fail with ORA-12516 or
     ORA-12520 errors.  To prevent this, increase the database
     <literal>PROCESSES</literal> parameter using the following steps:
    </para>
    <para>
     Connect as the oracle software owner:
     <programlisting>
<![CDATA[
    $ su - oracle
]]>
     </programlisting>
    </para>
    <para>
     Set the necessary Oracle environment with <filename>oracle_env.sh</filename> or
     <filename>oraenv</filename>, as described above.
    </para>
    <para>
     Start the SQL*Plus command line tool and
     increase <literal>PROCESSES</literal>
     <programlisting>
<![CDATA[
    $ sqlplus / as sysdba
    SQL> alter system set processes=100 scope=spfile
]]>
     </programlisting>
    </para>
    <para>
     Restart the database:
     <programlisting>
<![CDATA[
    SQL> startup force
]]>
     </programlisting>
    </para>
   </section>
 </section>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->

