--- /dev/null
+PostgreSQL/JDBC Test Suite Howto
+================================
+1 Introduction
+2 Installation
+3 Configuration
+4 Running the test suite
+5 Extending the test suite with new tests
+6 Guidelines for developing new tests
+7 Example
+8 Running the JDBC 2 test suite from Sun against PostgreSQL
+9 Credits, feedback
+
+
+1 Introduction
+--------------
+The PostgreSQL source tree contains an automated test suite for
+the JDBC driver. This document explains how to install,
+configure and run this test suite. Furthermore, it offers
+guidelines and an example for developers to add new test cases.
+
+Sun provides two standard JDBC test suites that you may also
+find useful.
+http://java.sun.com/products/jdbc/download2.html (JDBC 1)
+http://java.sun.com/products/jdbc/jdbctestsuite-1_2_1.html (JDBC
+2, including J2EE requirements)
+The JDBC 2 test suite is covered in section 8 below. The JDBC 1
+test suite is not currently covered in this document.
+
+2 Installation
+--------------
+Of course, you need to have a Java 2 JDK or JRE installed. The
+standard JDK from Sun is OK. You can download it from
+http://java.sun.com/.
+
+You need to install the Ant build utility. You can download it
+from http://jakarta.apache.org/ant/.
+
+You also need to install the JUnit testing framework. You can
+download it from http://www.junit.org/. Add junit.jar to your
+CLASSPATH before you perform the following steps. Ant will
+dynamically detect that JUnit is present and then build the JDBC
+test suite.
+
+You need to install and build the PostgreSQL source tree. You
+can download it from http://www.postgresql.org/devel-corner/.
+See README and INSTALL in the top of the tree for more
+information.
+
+You should run ./configure with the command line option
+--with-java. You may also want to use --with-pgport to compile a
+non-standard default port number (e.g. 5433) into all
+components. This will cause the server to listen on this
+non-standard port and it will cause the JDBC driver to connect
+to this port by default. In this way your testing environment is
+easily separated from other PostgreSQL applications on the same
+system.
+
+In this Howto we'll use $JDBC_SRC to refer to the directory
+src/interfaces/jdbc of the PostgreSQL source tree in your
+environment. The test suite is located in the subdirectory
+$JDBC_SRC/org/postgresql/test.
+
+3 Configuration
+---------------
+The test suite requires a PostgreSQL database to run the tests
+against and a user to login as. For a full regression test of
+the entire PostgreSQL system, you should run the test against a
+server built from the same source tree as the driver you're
+testing. The tests will create and drop many objects in this
+database, so it should not contain production tables to avoid
+loss of data. We recommend you assign the following names:
+
+ database: test
+ username: test
+ password: password
+
+These names correspond with the default names set for the test
+suite in $JDBC_SRC/build.xml. If you have chosen other names you
+need to edit this file and change the properties "database",
+"username" and "password" accordingly.
+
+4 Running the test suite
+------------------------
+%cd $JDBC_SRC
+%make
+%make check
+
+This will run the command line version of JUnit. If you'd like
+to see an animated coloured progress bar as the tests are
+executed, you may want to use one of the GUI versions of the
+test runner. See the JUnit documentation for more information.
+
+If the test suite reports errors or failures that you cannot
+explain, please post the relevant parts of the output to the
+mailing list pgsql-jdbc@postgresql.org.
+
+5 Extending the test suite with new tests
+-----------------------------------------
+If you're not familiar with JUnit, we recommend that you
+first read the introductory article "JUnit Test Infected:
+Programmers Love Writing Tests" on
+http://junit.sourceforge.net/doc/testinfected/testing.htm.
+Before continuing, you should ensure you understand the
+following concepts: test suite, test case, test, fixture,
+assertion, failure.
+
+The test suite consists of test cases, which consist of tests.
+A test case is a collection of tests that test a particular
+feature. The test suite is a collection of test cases that
+together test the driver - and to an extent the PostgreSQL
+backend - as a whole.
+
+If you decide to add a test to an existing test case, all you
+need to do is add a method with a name that begins with "test"
+and which takes no arguments. JUnit will dynamically find this
+method using reflection and run it when it runs the test case.
+In your test method you can use the fixture that is setup for it
+by the test case.
+
+If you decide to add a new test case, you should do two things:
+1) Add a class that extends junit.framework.TestCase. It should
+contain setUp() and tearDown() methods that create and destroy
+the fixture respectively.
+2) Edit $JDBC_SRC/org/postgresql/test/JDBC2Tests.java and add a
+suite.addTestSuite() call for your class. This will make the
+test case part of the test suite.
+
+6 Guidelines for developing new tests
+-------------------------------------
+Every test should create and drop its own tables. We suggest to
+consider database objects (e.g. tables) part of the fixture for
+the tests in the test case. The test should also succeed when a
+table by the same name already exists in the test database, e.g.
+by dropping the table before running the test (ignoring errors).
+The recommended pattern for creating and dropping tables can be
+found in the example in section 7 below.
+
+Please note that JUnit provides several convenience methods to
+check for conditions. See the TestCase class in the Javadoc
+documentation of JUnit, which is installed on your system. For
+example, you can compare two integers using
+TestCase.assertEquals(int expected, int actual). This method
+will print both values in case of a failure.
+
+To simply report a failure use TestCase.fail().
+
+The JUnit FAQ explains how to test for a thrown exception.
+
+Avoid the use of the deprecated TestCase.assert(), since it will
+collide with the new assert keyword in the Java 2 platform
+version 1.4.
+
+As a rule, the test suite should succeed. Any errors or failures
+- which may be caused by bugs in the JDBC driver, the backend or
+the test suite - should be fixed ASAP. Don't let a test fail
+just to make it clear that something needs to be fixed somewhere.
+That's what the TODO lists are for.
+
+Add some comments to your tests to explain to others what it is
+you're testing. A long sequence of JDBC method calls and JUnit
+assertions can be hard to comprehend.
+
+For example, in the comments you can explain where a certain test
+condition originates from. Is it a JDBC requirement, PostgreSQL
+behaviour or the intended implementation of a feature?
+
+7 Example (incomplete)
+----------------------
+package org.postgresql.test.jdbc2;
+
+import org.postgresql.test.JDBC2Tests;
+import junit.framework.TestCase;
+import java.sql.*;
+
+/**
+ * Test case for ...
+ */
+public class FooTest extends TestCase {
+
+ private Connection con;
+ private Statement stmt;
+
+ public FooTest(String name) {
+ super(name);
+ }
+
+ protected void setUp() throws Exception {
+ con = JDBC2Tests.openDB();
+ stmt = con.createStatement();
+
+ // Drop the test table if it already exists for some
+ // reason. It is not an error if it doesn't exist.
+ try {
+ stmt.executeUpdate("DROP TABLE testfoo");
+ } catch (SQLException e) {
+ // Intentionally ignore. We cannot distinguish
+ // "table does not exist" from other errors, since
+ // PostgreSQL doesn't support error codes yet.
+ }
+
+ stmt.executeUpdate(
+ "CREATE TABLE testfoo(pk INTEGER, col1 INTEGER)");
+ stmt.executeUpdate("INSERT INTO testfoo VALUES(1, 0)");
+
+ // You may want to call con.setAutoCommit(false) at
+ // this point, if most tests in this test case require
+ // the use of transactions.
+ }
+
+ protected void tearDown() throws Exception {
+ con.setAutoCommit(true);
+ if (stmt != null) {
+ stmt.executeUpdate("DROP TABLE testfoo");
+ stmt.close();
+ }
+ if (con != null) {
+ JDBC2Tests.closeDB(con);
+ }
+ }
+
+ public void testFoo() {
+ // Use the assert methods in junit.framework.TestCase
+ // for the actual tests
+
+ // Just some silly examples
+ assertNotNull(con);
+ if (stmt == null) {
+ fail("Where is my statement?");
+ }
+ }
+
+ public void testBar() {
+ // Another test.
+ }
+}
+
+8. Running the JDBC 2 test suite from Sun against PostgreSQL
+------------------------------------------------------------
+Download the test suite from
+http://java.sun.com/products/jdbc/jdbctestsuite-1_2_1.html
+This is the JDBC 2 test suite that includes J2EE requirements.
+
+1. Configure PostgreSQL so that it accepts TCP/IP connections and
+ start the server. Prepare PostgreSQL by creating two users (cts1
+ and cts2) and two databases (DB1 and DB2) in the cluster that is
+ going to be used for JDBC testing.
+
+2. Download the latest release versions of the J2EE, J2SE, and JDBC
+ test suite from Sun's Java site (http://java.sun.com), and install
+ according to Sun's documentation.
+
+3. The following environment variables should be set:
+
+ CTS_HOME=<path where JDBC test suite installed (eg: /usr/local/jdbccts)>
+ J2EE_HOME=<path where J2EE installed (eg: /usr/local/j2sdkee1.2.1)>
+ JAVA_HOME=<path where J2SE installed (eg: /usr/local/jdk1.3.1)>
+ NO_JAVATEST=Y
+ LOCAL_CLASSES=<path to PostgreSQL JDBC driver jar>
+
+4. In $J2EE_HOME/config/default.properties:
+
+ jdbc.drivers=org.postgresql.Driver
+ jdbc.datasources=jdbc/DB1|jdbc:postgresql://localhost:5432/DB1|jdbc/DB2|jdbc:postgresq://localhost:5432/DB2
+
+ Of course, if PostgreSQL is running on a computer different from
+ the one running the application server, localhost should be changed
+ to the proper host. Also, 5432 should be changed to whatever port
+ PostgreSQL is listening on (5432 is the default).
+
+ In $J2EE_HOME/bin/userconfig.sh:
+
+ Add $CTS_HOME/lib/harness.jar, $CTS_HOME/lib/moo.jar,
+ $CTS_HOME/lib/util.jar to J2EE_CLASSPATH. Also add the path to
+ the PostgreSQL JDBC jar to J2EE_CLASSPATH. Set the JAVA_HOME
+ variable to where you installed the J2SE. You should end up with
+ something like this:
+
+ CTS_HOME=/home/liams/linux/java/jdbccts
+ J2EE_CLASSPATH=/home/liams/work/inst/postgresql-7.1.2/share/java/postgresql.jar:$CTS_HOME/lib/harness.jar:$CTS_HOME/lib/moo.jar:$CTS_HOME/lib/util.jar
+ export J2EE_CLASSPATH
+
+ JAVA_HOME=/home/liams/linux/java/jdk1.3.1
+ export JAVA_HOME
+
+ In $CTS_HOME/bin/cts.jte:
+
+ webServerHost=localhost
+ webServerPort=8000
+ servletServerHost=localhost
+ servletServerPort=8000
+
+5. Start the application server (j2ee):
+
+ $ cd $J2EE_HOME
+ $ bin/j2ee -verbose
+
+ The server can be stopped after the tests have finished:
+
+ $ cd $J2EE_HOME
+ $ bin/j2ee -stop
+
+6. Run the JDBC tests:
+
+ $ cd $CTS_HOME/tests/jdbc/ee
+ $ make jdbc-tests
+
+At the time of writing of this document, a great number of tests
+in this test suite fail.
+
+9 Credits, feedback
+-------------------
+The parts of this document describing the PostgreSQL test suite
+were originally written by Rene Pijlman. Liam Stewart contributed
+the section on the Sun JDBC 2 test suite.
+
+Please send your questions about the JDBC test suites or suggestions
+for improvement to the pgsql-jdbc@postgresql.org mailing list.
+
+The source of this document is maintained in
+src/interfaces/jdbc/org/postgresql/test/README in CVS. Patches for
+improvement can be send to the mailing list
+pgsql-patches@postgresql.org.
projects / postgresql / commitdiff