Add testing steps

diff --git a/ext/oci8/README b/ext/oci8/README
index b9df41db3a86982c44c71b5ac1a4cf3332395737..c47b1d75055301b3a7a11e463638cb27cf3fbfec 100644 (file)
--- a/ext/oci8/README
+++ b/ext/oci8/README
@@ -5,20 +5,20 @@ Installing OCI8
 2. Installing as shared extension.
 3. Installing as statically compiled extension.
 4. Installing from PECL.
-
+5. Testing OCI8
 
 1. Common requirements
 ----------------------
-In case if you use Oracle Instant Client, you don't have to set ORACLE_HOME and 
-most of the other environment variables to build PHP with OCI8 support. 
+In case if you use Oracle Instant Client, you don't have to set ORACLE_HOME and
+most of the other environment variables to build PHP with OCI8 support.
 The only variables you may have to set are:
 LD_LIBRARY_PATH - it must include Instant Client libraries dir
-NLS_LANG - in case if you want to change the default encoding used during 
+NLS_LANG - in case if you want to change the default encoding used during
 interaction with Oracle servers
 
-If you use common Oracle Client installation that comes along with the Oracle 
-server installation, you MUST set at least ORACLE_HOME environment variable 
-and make it visible for your web-server BEFORE it starts. Most appropriate 
+If you use common Oracle Client installation that comes along with the Oracle
+server installation, you MUST set at least ORACLE_HOME environment variable
+and make it visible for your web-server BEFORE it starts. Most appropriate
 places to add ORACLE_HOME definition are:
 - /etc/profile
 - /etc/profile.local
@@ -27,21 +27,21 @@ and others.
 
 2. Installing as shared extension
 ---------------------------------
-To install OCI8 as shared extension (i.e. the one you should put into 
+To install OCI8 as shared extension (i.e. the one you should put into
 your php.ini) use the following configure lines to configure PHP:
 a) if you use common Oracle Client installation:
 ./configure --with-oci8=shared,$ORACLE_HOME
 
 b) with Oracle Instant Client:
 ./configure --with-oci8=shared,instantclient,/path/to/instant/client/lib
-If you use rpm-based installation of Oracle Instant Client, your configure 
+If you use rpm-based installation of Oracle Instant Client, your configure
 line will look like this:
 ./configure --with-oci8=shared,instantclient,/usr/lib/oracle/<OIC version>/client/lib
 
-Follow the usual building procedure after that and you'll get OCI8 shared 
+Follow the usual building procedure after that and you'll get OCI8 shared
 extension (i.e. oci8.so). Add it into the php.ini file like this:
 extension=oci8.so
-and don't forget to specify the right extension_dir for PHP to be able 
+and don't forget to specify the right extension_dir for PHP to be able
 to find shared extensions correctly.
 
 3. Installing as statically compiled extension
@@ -53,9 +53,84 @@ a) with common Oracle Client installation
 b) with Oracle Instant Client
 ./configure --with-oci8=instantclient,/path/to/instant/client/lib
 
-After successful compile, you don't have to add oci8.so to the php.ini, the module will 
+After successful compile, you don't have to add oci8.so to the php.ini, the module will
 be usable without any additional actions.
 
 4. Installing from PECL
 -----------------------
 TBD
+
+5. Testing OCI8
+---------------
+
+OCI8 tests are in ext/oci8/tests.  When OCI8 tests are run this
+directory will contain logs of any failures.
+
+5.1. Running OCI8 tests on Linux
+
+5.1.1. Edit ext/oci8/tests/details.inc
+
+  Set the username, password and connection string for the database.
+  Most tests have been developed using the SYSTEM account: some tests
+  might fail unless the user has permissions to create necessary
+  tables, views, procedures etc.
+
+  If the database is on the same machine as PHP, set
+  $oracle_on_localhost to TRUE.
+
+  An alternative to editing details.inc is the set the environment
+  variables
+
+    PHP_OCI8_TEST_USER
+    PHP_OCI8_TEST_PASS
+    PHP_OCI8_TEST_DB
+    PHP_OCI8_TEST_DB_ON_LOCALHOST
+
+  for example:
+
+    $ export PHP_OCI8_TEST_USER=system
+    $ export PHP_OCI8_TEST_PASS=oracle
+    $ export PHP_OCI8_TEST_DB=localhost/XE
+    $ export PHP_OCI8_TEST_DB_ON_LOCALHOST=TRUE
+
+5.1.2. Set any necessary environment variables for the Oracle
+    database.  With Oracle 10g XE do:
+
+    $ . /usr/lib/oracle/xe/app/oracle/product/10.2.0/server/bin/oracle_env.sh
+
+  For other versions of the Oracle database do:
+
+    $ . /usr/local/bin/oraenv
+
+5.1.3. Check your php.ini has E in the variables_order parameter, for
+    example:
+
+    variables_order = "EGPCS"
+
+5.1.4. Run the tests:
+
+    $ cd <your php src directory>
+    $ make test TESTS=ext/oci8
+
+5.2. The tests execute rapidly.  On fast machines with a local
+  database configured for light load (e.g. Oracle 10g XE) you might
+  see random tests fail with ORA-12516 or ORA-12520 errors.  To
+  prevent this, increase the database PROCESSES parameter using the
+  following steps.
+
+5.2.1. Connect as the oracle software owner:
+
+    $ su - oracle
+
+5.2.2. Set the necessary environment variables as in 5.1.2.
+
+5.2.3. Start the SQL*Plus command line tool and increase PROCESSES
+
+    $ sqlplus / as sysdba
+    SQL> alter system set processes=100 scope=spfile
+
+5.2.4. Restart the database:
+
+    SQL> startup force
+
+5.2.5. Rerun the tests