From 6b9f94022c481fdcde45d491b61eddb414454aea Mon Sep 17 00:00:00 2001 From: Bruce Momjian Date: Fri, 7 Sep 2001 23:34:16 +0000 Subject: Move TESTSUITE file to test/README. --- src/interfaces/jdbc/TESTSUITE | 322 ------------------------ src/interfaces/jdbc/org/postgresql/test/README | 323 +++++++++++++++++++++++++ 2 files changed, 323 insertions(+), 322 deletions(-) delete mode 100644 src/interfaces/jdbc/TESTSUITE create mode 100644 src/interfaces/jdbc/org/postgresql/test/README (limited to 'src/interfaces/jdbc') diff --git a/src/interfaces/jdbc/TESTSUITE b/src/interfaces/jdbc/TESTSUITE deleted file mode 100644 index 93daa3ac411..00000000000 --- a/src/interfaces/jdbc/TESTSUITE +++ /dev/null @@ -1,322 +0,0 @@ -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. diff --git a/src/interfaces/jdbc/org/postgresql/test/README b/src/interfaces/jdbc/org/postgresql/test/README new file mode 100644 index 00000000000..79113b56434 --- /dev/null +++ b/src/interfaces/jdbc/org/postgresql/test/README @@ -0,0 +1,323 @@ +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. + -- cgit v1.2.3