From a926c7058b00d54d31cc143c78633a2e9c9fc3e4 Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Fri, 7 Sep 2001 21:45:42 +0000 Subject: [PATCH] Add Java testsuite info. --- src/interfaces/jdbc/TESTSUITE | 322 ++++++++++++++++++++++++++++++++++ 1 file changed, 322 insertions(+) create mode 100644 src/interfaces/jdbc/TESTSUITE diff --git a/src/interfaces/jdbc/TESTSUITE b/src/interfaces/jdbc/TESTSUITE new file mode 100644 index 0000000000..93daa3ac41 --- /dev/null +++ b/src/interfaces/jdbc/TESTSUITE @@ -0,0 +1,322 @@ +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= + J2EE_HOME= + JAVA_HOME= + NO_JAVATEST=Y + LOCAL_CLASSES= + +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.