|
As Kathy Saunders
announced in February, IBM is contributing attached
Derby client to Apache Derby project. Derby client is a type 4 JDBC
client driver that is designed to work with Derby Network Server. I am attaching:
(Below ${derby.source} refers to the root of your derby source)
To perform a clean jar build, go to ${derby.source} and then
I am very excited to have this submission!!! I vote +1 to accept this as part of Derby. Satheesh |
Derby Network Client
Last update: 4/11/05
Contents
- Overview
- Functionality
- JDBC Driver and DataSource names
- Ways to Connect using the Derby Client Driver
- Data Source properties
- Tracing
- Security
- Packaging, Distribution and Versioning
- Comparision and/or differences with the Derby Embedded Driver
- Effects to existing documentation
- Miscellaneous
Overview
The Derby network client provides network connectivity to the Derby Network Server. It is distributed as an additional jar file, derbyclient.jar, with an entirely independent code base from the embedded driver.
The Derby network client is a type 4, JDBC compliant Driver, which attempts to match the Derby Embedded JDBC driver as much as possible. Initially, it will have some differences from the embedded driver, for example, some SQL States will remain null and error messages will not be localized in the initial offering. Hopefully, over time the functionality of the two drivers will converge.
Functionality
All functionality for the Derby network client is packaged in the derbyclient.jar file which will be added to the Derby distribution. The client application needs only to include the new jar and application classes in its classpath. derbyclient.jar has no dependencies on the tools, server, or derby database engine classes, nor do those classes depend on derbyclient.jar. Some new client classes are in the same package as the embedded driver, such as org.apache.derby.jdbc.ClientDriver, but the actual classes are contained only in the client jar file.
The Derby network client allows connections via JDBC URL using DriverManager by its implementations of JDBC20 data sources, javax.sql.DataSource, javax.sql.ConnectionPoolDataSource. An implementation of javax.sql.XADataSource is also provided for network XA Support. The Derby network client provides a tracing facility to collect JDBC trace information and view protocol flows for debugging. Security mechanisms are also provided for user and password encryption. DataSource properties and connection attributes can be used to enable tracing, as well as security settings.
Tools support for ij and dblook as well as test harness support is provided.
The sections that follow will describe the functionality and provide examples of using each characteristic mentioned here.
JDBC Driver and DataSource names
The Derby network client classes and JDBC interfaces they implement are listed below.
| JDBC Interface | Derby network client class | |
|---|---|---|
| java.sql.Driver | org.apache.derby.jdbc.ClientDriver | |
| javax.sql.DataSource | org.apache.derby.jdbc.ClientDataSource | |
| javax.sql.XADataSource | org.apache.derby.jdbc.ClientXADataSource | |
| javax.sql.ConnectionPoolDataSource | org.apache.derby.jdbc.ClientConnectionPoolDataSource |
Connection URL Format
The protocol for the client URL is jdbc:derby://. The embedded and client attributes are specified the same way. The embedded driver has been changed to reject URL's with a // following derby:
Derby network client URL Format
jdbc:derby://server[:port]/databaseName[;attributeKey=value]..
An example of using this URL to connect to the Derby network server running on the localhost at port 1527 in ij is:
ij> connect `jdbc:derby://localhost:1527/sample;create=true;user=user1;password=secret4me';
Ways to Connect using the Derby Client Driver
Client CLASSPATH
Prior to using the Derby network client, the derbyclient.jar file needs to be added to the classpath on the client. On Windows, to add the derbyclient.jar file to your classpath, use the following command:
set CLASSPATH=%CLASSPATH%;%DERBY_INSTALL%\lib\derbyclient.jar;
When using the Derby client driver to connect to the Derby database, there are two general methodologies used to connect. The first method is to use the DriverManager. The second way to connect is to use one of the three DataSource classes listed above.
To use the DriverManager, the first step is to load the ClientDriver.
Loading the driver:
port java.sql.* ;
...
try
{
Class.forName("org.apache.derby.jdbc.ClientDriver").newInstance();
} catch (ClassNotFoundException e) {
e.printStackTrace();
} catch(java.lang.InstantiationException instant) {
instant.printStackTrace();
} catch(java.lang.IllegalAccessException illegal) {
illegal.printStackTrace();
}
...
Now a connection can be made with the DriverManager.
Connecting with the DriverManager:
String url =
"";
connection = DriverManager.getConnection(url); Connecting with the ClientDataSource:
import java.sql.*;
import javax.sql.*;
import org.apache.derby.jdbc.ClientDataSource;
...
ClientDataSource ds=new ClientDataSource();
ds.setDatabaseName("sample");
ds.setServerName("localhost"); // host with listening network server.
ds.setPortNumber(1527); // port of listening network server.
ds.setUser("user1"); // Assign the user ID
ds.setPassword("secret4me"); // Assign the password
Connection con= ds.getConnection(); // Create a Connection object
Data Source properties
The following data source properties are available on the ClientDataSource, ClientConnectionPoolDataSource and the ClientXADataSource classes.
Standard JDBC Data Source Properties Property Type Description Default Req'd Url Attr databaseName* String name of database X dataSourceName* String a data source name description* String a description of this data source user* String user's account name APP user password* String user's database password password serverName String host name or TCP/IP address where the server is listening for requests localhost portNumber int port number where the server is listening for requests 1527 Client Specific Data Source Properties traceFile String filename for tracing output. Setting this property turns on tracing. (See Tracing) traceFile traceDirectory String directory for tracing output. Each connection will output to a separate file. Setting this property turns on tracing. (See Tracing) traceDirectory traceLevel int level of client tracing if traceFile or traceDirectory are set TRACE_ALL traceLevel traceFileAppend boolean true if tracing output should append to the existing trace file. false traceFileAppend securityMechanism int security mechanism (See Security) USER_ONLY_SECURITY securityMechanism retrieveMessageText boolean retrieve message text from server. A stored procedure is called to retrieve the message text with each SQLException and may start a new unit of work. Set to false if you do not want the performance impact or encounter issues with a new unit of work being started. true retrieveMessageText Server Specific Data Source Properties These properties are translated into server specific URL attributes which are passed to the Derby embedded driver by appending them to the databaseName. For example, calling setDatabaseName("mydb") followed by setConnectionAttributes("create=true") will cause the string mydb;create=true to be sent to the server as the database name . The URL to connect to the database will therefore include these attributes. connectionAttributes* String set to the list of Derby embedded connection attributes separated by semi-colons. E.g., to specify an encryption bootPassword of "x8hhk2adf", and set upgrade to true, do the following: ds.setConnectionAttributes("bootPassword=x8hhk2adf;upgrade=true"); various. See Derby Documentation for a full list. * This property is also available on the EmbeddedDataSource. All other data source properties are supplemental to the ClientDataSources.
Note: setAttributesAsPassword , which is available for the embedded data sources is not available for the client data source. It is not clear how to communicate it to the server.
Tracing
The Derby network client provides a tracing facility to collect JDBC trace information and view protocol flows. Listed below are various ways to obtain trace output. However, the easiest way to turn on tracing is to use the traceFile attribute on the url in ij. The example below shows all tracing going to the file trace.out from an ij session.
ij>connect 'jdbc:derby://localhost:1527/mydb;create=true;traceFile=trace.out;user=user1;password=secret4me';
ClientDataSource Tracing
Three methods can be used to collect tracing data if obtaining connections from the ClientDataSource.
- Use the setLogWriter(java.io.PrintWriter) method of ClientDataSource and set the PrintWriter to a non null value.
- Use the setTraceFile(String filename) method of ClientDataSource.
- Use the setTraceDirectory(String dirname) method of ClientDataSource to trace each connection flow in its own file for programs that have multiple connections.
DriverManager Tracing
If the DriverManager is used to obtain connections, two ways are available to enable and collect tracing information.
- Use the setLogWriter(java.io.PrintWriter) method of DriverManager and set the PrintWriter to a non null value.
- Use the URL attributes traceFile or traceDirectory to set these properties prior to creating the connection with the DriverManager.getConnection() method.
ClientDataSource Tracing Examples
Shown below are examples of each tracing type for the ClientDataSource Tracing.
- Use the setLogWriter(java.io.PrintWriter) method of
ClientDataSource and set the PrintWriter to a non null value.
/** * Example to show how to set /enable tracing when using DataSource * - using the setLogWriter method on the datasource */ private static void sampleConnectUsingSimpleDataSource() throws Exception { java.sql.Connection conn = null; try { javax.sql.DataSource ds = new org.apache.derby.jdbc.ClientDataSource(); ((org.apache.derby.jdbc.ClientDataSource) ds).setServerName("localhost"); ((org.apache.derby.jdbc.ClientDataSource) ds).setPortNumber(1527); ((org.apache.derby.jdbc.ClientDataSource) ds).setDatabaseName("sampleDB;create=true"); System.out.println("---------------------------------------------------------------"); System.out.println("[TraceWithSetLogWriter] Setting setLogWriter to trace.log."); System.out.println("Traces will be written into trace.log"); java.io.PrintWriter pw = new PrintWriter(new FileOutputStream("trace.log"),true); ds.setLogWriter(pw); // Refine the level of tracing detail ((org.apache.derby.jdbc.ClientDataSource) ds). setTraceLevel(org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS | org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS); // This connection request is traced using trace level // TRACE_CONNECTS | TRACE_PROTOCOL_FLOWS conn = ds.getConnection("user1", "secretPassword"); java.sql.Statement s = conn.createStatement(); try { s.executeUpdate("DROP TABLE sampleTable"); } catch(Exception e) { // ignore drop of table error } s.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)"); PreparedStatement ps = conn.prepareStatement("insert into sampleTable values(?)"); // do some inserts conn.setAutoCommit(false); ps.setInt(1,1); ps.setInt(1,2); ps.executeUpdate(); conn.commit(); // cleanup resources s.close(); ps.close(); conn.close(); pw.flush(); pw.close(); } catch(java.sql.SQLException e) { e.printStackTrace(); } } - Use the setTraceFile(String filename) method of ClientDataSource.
/** * Example to show how to set /enable tracing when obtaining connections from DataSource * - using the setTraceFile method on the datasource */ private static void sampleConnectUsingSimpleDataSource() throws Exception { java.sql.Connection conn = null; try { javax.sql.DataSource ds = new org.apache.derby.jdbc.ClientDataSource(); ((org.apache.derby.jdbc.ClientDataSource) ds).setServerName("localhost"); ((org.apache.derby.jdbc.ClientDataSource) ds).setPortNumber(1527); ((org.apache.derby.jdbc.ClientDataSource) ds).setDatabaseName("sampleDB;create=true"); System.out.println("---------------------------------------------------------------"); System.out.println("[TraceWithSetTraceFile] Setting setTraceFile to trace.log."); System.out.println("Traces will be written into trace.log"); ((org.apache.derby.jdbc.ClientDataSource) ds).setTraceFile("trace.log"); // Refine the level of tracing detail ((org.apache.derby.jdbc.ClientDataSource) ds). setTraceLevel(org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS | org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS); // This connection request is traced using trace level // TRACE_CONNECTS | TRACE_PROTOCOL_FLOWS conn = ds.getConnection("user1", "secretPassword"); java.sql.Statement s1 = conn.createStatement(); try { s1.executeUpdate("DROP TABLE sampleTable"); } catch(Exception e) { // ignore drop of table error } s1.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)"); PreparedStatement ps = conn.prepareStatement("insert into sampleTable values (?)"); conn.setAutoCommit(false); ps.setInt(1,1); ps.executeUpdate(); conn.commit(); // cleanup resources s1.close(); ps.close(); conn.close(); } catch(java.sql.SQLException e) { e.printStackTrace(); } } - Use the setTraceDirectory(String dirname) method of ClientDataSource to trace each connection flow in its own file for programs that have multiple connections.
Call the setTraceDirectory(String directoryName) method on the ClientDataSource or use the URL attribute traceDirectory=<directory> to specify a directory for trace output. The directory must already exist. If the traceDirectory property is enabled, then tracing of multiple connections on the same datasource will be directed to separate files under the specified directory.
When tracing to a directory, each connection will be traced to a separate file named traceFile_origination_n, where origination indicates the origination of the log writer in use and can be "xads", "cpds", "ds", or "driver", and n represents the nth connection against the datasource. The log writer origination indicator in the file name maps to the log writer as follows:
- ds - ClientXADataSource
- cpds - ClientConnectionPoolDataSource
- ds - ClientDataSource
- driver - ClientDriver
/** * Example to show how to set /enable tracing when obtaining connections from DataSource * - using the setTraceDirectory method on the DataSource */ private static void sampleConnectUsingSimpleDataSource() throws Exception { java.sql.Connection conn = null; try { javax.sql.DataSource ds = new org.apache.derby.jdbc.ClientDataSource(); ((org.apache.derby.jdbc.ClientDataSource) ds).setServerName("localhost"); ((org.apache.derby.jdbc.ClientDataSource) ds).setPortNumber(1527); ((org.apache.derby.jdbc.ClientDataSource) ds).setDatabaseName("sampleDB;create=true"); ((org.apache.derby.jdbc.ClientDataSource) ds).setTraceDirectory("myTraceDir"); conn = ds.getConnection("user1", "secretPassword"); java.sql.Statement s1 = conn.createStatement(); try { s1.executeUpdate("DROP TABLE sampleTable"); } catch(Exception e) { System.out.println("First time, expected exception in drop table as table not yet created in database" +e.getMessage()); } s1.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)"); PreparedStatement ps = conn.prepareStatement("insert into sampleTable values (?)"); conn.setAutoCommit(false); ps.setInt(1,1); ps.executeUpdate(); conn.commit(); // cleanup resources s1.close(); ps.close(); conn.close(); // Each connection trace will be in a file of its own prefixed // by name set using the setTraceFile // example : traceFile_origination_n. n is the nth connection against the datasource. // origination indicates the origination of the logwriter in use and can be // cpds, xads, ds, driver Connection conn2 = ds.getConnection("user2","password2"); conn2.close(); } catch(java.sql.SQLException e) { e.printStackTrace(); } }
DriverManager Tracing Examples
Shown below is an example of enabling tracing when obtaining connections using the DriverManager API.
- Use the setLogWriter(java.io.PrintWriter) method of DriverManager and set the PrintWriter to a non null value.
/** * Example to show how to set /enable tracing when obtaining connections from * java.sql.DriverManager api. * - using the setLogWriter method on the DriverManager api */ import java.sql.*; import javax.sql.*; import org.apache.derby.jdbc.ClientDataSource; import java.io.PrintWriter; import java.io.FileOutputStream; ... private static void sampleConnectWithURLUsingDriverManager() throws Exception { java.sql.Connection conn = null; try { Class.forName("org.apache.derby.jdbc.ClientDriver"); } catch(ClassNotFoundException e) { System.out.println("[TraceWithSetLogWriter] Derby Client driver is not in the classpath.Check if derbyclient.jar is in your classpath!"); return; } try { System.out.println("---------------------------------------------------------------------"); System.out.println("Setting logging/tracing using setLogWriter on DriverManager to trace1.log"); java.sql.DriverManager.setLogWriter(new java.io.PrintWriter(new FileOutputStream("trace1.log"))); } catch(Exception e) { System.out.println("[TraceWithSetLogWriter] Unable to set tracing/logging PrintWriter to trace.log"); } // The traceLevel property is established through the URL syntax, // and driver tracing is directed to file "trace1.log" String databaseURL = "jdbc:derby://localhost:1527" + "/sampleDB;create=true;traceLevel=" + (org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS|org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS); // Set other properties java.util.Properties properties = new java.util.Properties(); properties.setProperty("user", "myname"); properties.setProperty("password", "mypass"); try { // This connection request is traced using trace level // TRACE_CONNECTS | TRACE_PROTOCOL_FLOWS conn = java.sql.DriverManager.getConnection(databaseURL, properties); java.sql.Statement s = conn.createStatement(); try { s.executeUpdate("DROP TABLE sampleTable"); } catch(Exception e) { System.out.println("First time, expected exception in drop table as table not yet created in database" +e.getMessage()); } s.executeUpdate("CREATE TABLE sampleTable( sampleColumn int)"); PreparedStatement ps = conn.prepareStatement("insert into sampleTable values(?)"); // do some inserts conn.setAutoCommit(false); ps.setInt(1,1); ps.setInt(1,2); ps.executeUpdate(); conn.commit(); // cleanup resources s.close(); ps.close(); conn.close(); } catch(java.sql.SQLException e) { e.printStackTrace(); } }
Changing the Default Trace Level
The trace level defaults to ClientDataSource.TRACE_ALL. The tracing can be changed by calling the setTraceLevel(int level) method or setting the URL attribute traceLevel, as shown below.
String url = "" + ";traceFile=/u/user1/trace.out" + ";traceLevel=" + org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS; DriverManager.getConnection(url,"user1","secret4me");This table lists the available tracing levels and values.
Trace Level Value org.apache.derby.jdbc.ClientDataSource.TRACE_NONE 0x0 org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTION_CALLS 0x1 org.apache.derby.jdbc.ClientDataSource.TRACE_STATEMENT_CALLS 0x2 org.apache.derby.jdbc.ClientDataSource.TRACE_RESULT_SET_CALLS 0x4 org.apache.derby.jdbc.ClientDataSource.TRACE_DRIVER_CONFIGURATION 0x10 org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS 0x20 org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS 0x40 org.apache.derby.jdbc.ClientDataSource.TRACE_RESULT_SET_META_DATA 0x80 org.apache.derby.jdbc.ClientDataSource.TRACE_PARAMETER_META_DATA 0x100 org.apache.derby.jdbc.ClientDataSource.TRACE_DIAGNOSTICS 0x200 org.apache.derby.jdbc.ClientDataSource.TRACE_XA_CALLS 0x800 org.apache.derby.jdbc.ClientDataSource.TRACE_ALL 0xFFFFFFFF; To specify more than one trace , use one of these techniques:
- Use bitwise OR (|) operators with two or more trace values. For example,
to trace PROTOCOL flows and connection calls, specify this value for
traceLevel:
TRACE_PROTOCOL_FLOWS|TRACE_CONNECTION_CALLS - Use a bitwise complement ( ~ ) operator with a trace value to specify all
except a certain trace. For example, to trace everything except PROTOCOL
flows, specify this value for traceLevel:
~TRACE_PROTOCOL_FLOWS
Security
Derby network client allows you to select a security mechanism by specifying a value for the securityMechanism property. You can set this property in one of the following ways:
- When using the DriverManager interface, set securityMechanism in a java.util.Properties object before you invoke the form of the getConnection method which includes the java.util.Properties parameter.
- When using the DataSource interface, and you are creating and deploying your own DataSource objects, invoke the DataSource.setSecurityMechanism method after you create a DataSource object.
The table below lists the security mechanisms the Derby network client supports, and the corresponding property value to specify to obtain this securityMechanism. The default security mechanism is the user ID only if no password is set and User ID and password if password is set. The default user, if none is specified is APP.
Security mechanisms supported by the Derby network client Security mechanism securityMechanism property value Comments User ID and password ClientDataSource.CLEAR_TEXT_PASSWORD_SECURITY (0x03) Default if password is set User ID only ClientDataSource.USER_ONLY_SECURITY (0x04) Default if password is not set Encrypted user ID and encrypted password ClientDataSource.ENCRYPTED_USER_AND_PASSWORD_SECURITY (0x09) Encryption requires a JCE Implementation that supports Diffie-Helman algorithm with a prime of 32 bytes
Packaging, Distribution and Versioning
The Derby network client will assume the version of the Derby release in which it is offered (currently thought to be 10.1).
A new jar file, derbyclient.jar, needs to be added to the distribution, which will contain the client classes. The client classpath will require only derbyclient.jar to access the server. Demo programs and server framework batch files and scripts will need to be changed to use the Derby network client.
Comparision and/or differences with the Derby Embedded Driver
The following known differences exist between the embedded driver and the network client driver. Many of these are already documented as Network Server differences at http://incubator.apache.org/derby/manuals/admin/hubprnt19.html#HDRSII-APPS-. Three differences that are listed in the server guide are not relevant with the network client. XA is supported, error messages are retrieved by default and user/password are not required. Below is a summary of the differences.
- Error messages and SQLStates are sometimes different and are sometimes null on the client, particularly for data conversion errors.
- Multiple SQL Exceptions and Warnings will only return a single Exception on the client. It will have the SQLState of the first exception and in the text will have the text of the additional Exceptions appended.
- There are no localized error messages for the client.
- The client driver has not been tested under security manager.
- The client driver fully materializes LOBS when the row is retrieved.
- Scrollable cursors (ResultSet.TYPE_SCROLL_SENSITIVE or ResultSet.TYPE_SCROLL_INSENSITIVE) are not supported if the resultset contains LOB data. TYPE_FORWARD_ONLY must be specified for result sets containing LOB data.
- To use encrypted user id and password, you need to have IBM JCE (Java Cryptography Extension) 1.2.1 or later. (DERBY-65)
Effects to existing documentation
The following Derby Manuals should be updated to include the new client driver. The Server Guide, Tools and Getting Started guides at least will be affected. Currently they document using the network server with the IBM DB2 Universal JDBC Driver. In general, the current documentation is relevant to the new driver except for the items listed below.
URL Derby Network Client URL Documented URL jdbc:derby://server[:port]/databaseName[;attributeKey=value].. jdbc:derby:net//server[:port]/databaseName[;embeddedAttributeKey=value]..:clientAttributeKey=value;. Driver and DataSource Names JDBC Interface Derby Network Client Documented Class Name java.sql.Driver org.apache.derby.jdbc.ClientDriver com.ibm.db2.jcc.DB2Driver javax.sql.DataSource org.apache.derby.jdbc.ClientDataSource com.ibm.db2.jcc.DB2DataSource javax.sql.XADataSource org.apache.derby.jdbc.ClientXADataSource com.ibm.db2.jcc.DB2XADataSource javax.sql.ConnectionPoolDataSource org.apache.derby.jdbc.ClientConnectionPoolDataSource com.ibm.db2.jcc.DB2ConnectionPoolDataSource Miscellaneous Changes Derby Network Client Documented jar file name derbyclient.jar db2jcc.jar, db2jcc_licence_c.jar attribute to retrieve message text* retrieveMessageText (default true) retrieveMessagesFromServerOnGetMessage (default false) required datasource property settings databaseName only required property requires databaseName, serverName,driverType, user, password *Note: The retrieveMessageText attribute should not be included in most of the examples as it now defaults to true.
Client data source properties, tracing and security needs to be documented as described above.
Miscellaneous
Tools
ij will recognize the new URL and load the driver automatically. dblook will accept the client URL. sysinfo has been changed to locate the new jar file.
Testing
You can run the client regression tests by running the suite derbynetclientmats. You can run individual tests with the client framework by setting the framework system property to DerbyNetClient. An example of this is shown below.
java -Dframework=DerbyNetClient org.apache.derbyTesting.functionTests.harness.RunTest lang/supersimple.sqlYou can run the Derby network client test suite as follows:
java org.apache.derbyTesting.functionTests.harness.RunSuite derbynetclientmats
Index: tools/ant/properties/dirs.properties =================================================================== --- tools/ant/properties/dirs.properties (revision 161156) +++ tools/ant/properties/dirs.properties (working copy) @@ -34,6 +34,7 @@ derby.engine.src.dir=${derbysrc.dir}/engine derby.drda.src.dir=${derbysrc.dir}/drda +derby.client.src.dir=${derbysrc.dir}/client derby.tools.src.dir=${derbysrc.dir}/tools derby.build.src.dir=${derbysrc.dir}/build derby.demo.src.dir=${derbysrc.dir}/demo @@ -42,6 +43,7 @@ derby.engine.dir=${derby.engine.src.dir}/${derby.dir} derby.drda.dir=${derby.drda.src.dir}/${derby.dir} +derby.client.dir=${derby.client.src.dir}/{derby.dir} derby.tools.dir=${derby.tools.src.dir}/${derby.dir} derby.build.dir=${derby.build.src.dir}/org/apache/derbyBuild derby.locales.dir=${derby.engine.dir}/loc Index: java/testing/README.htm =================================================================== --- java/testing/README.htm (revision 161156) +++ java/testing/README.htm (working copy) @@ -1,1189 +1,2159 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> -<html> +<html xmlns:o="urn:schemas-microsoft-com:office:office" +xmlns:w="urn:schemas-microsoft-com:office:word" +xmlns:st1="urn:schemas-microsoft-com:office:smarttags" +xmlns="http://www.w3.org/TR/REC-html40";> + <head> - <meta content="text/html; charset=ISO-8859-1" - http-equiv="content-type"> - <title>readme.htm</title> +<meta http-equiv=Content-Type content="text/html; charset=iso-8859-1"> +<meta name=ProgId content=Word.Document> +<meta name=Generator content="Microsoft Word 10"> +<meta name=Originator content="Microsoft Word 10"> +<link rel=File-List href="README_files/filelist.xml"> +<title>readme.htm</title> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="date"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="City"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="State"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="place"/> +<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags" + name="time"/> +<!--[if gte mso 9]><xml> + <o:DocumentProperties> + <o:Author>IBM_User</o:Author> + <o:LastAuthor>IBM_User</o:LastAuthor> + <o:Revision>2</o:Revision> + <o:TotalTime>4</o:TotalTime> + <o:Created>2005-04-07T04:38:00Z</o:Created> + <o:LastSaved>2005-04-07T04:42:00Z</o:LastSaved> + <o:Pages>1</o:Pages> + <o:Words>4678</o:Words> + <o:Characters>26668</o:Characters> + <o:Company>IBM</o:Company> + <o:Lines>222</o:Lines> + <o:Paragraphs>62</o:Paragraphs> + <o:CharactersWithSpaces>31284</o:CharactersWithSpaces> + <o:Version>10.6714</o:Version> + </o:DocumentProperties> +</xml><![endif]--><!--[if gte mso 9]><xml> + <w:WordDocument> + <w:SpellingState>Clean</w:SpellingState> + <w:GrammarState>Clean</w:GrammarState> + <w:Compatibility> + <w:ApplyBreakingRules/> + <w:UseFELayout/> + </w:Compatibility> + <w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel> + </w:WordDocument> +</xml><![endif]--><!--[if !mso]><object + classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object> +<style> +st1\:*{behavior:url(#ieooui) } +</style> +<![endif]--> +<style> +<!-- + /* Font Definitions */ + @font-face + {font-family:Wingdings; + panose-1:5 0 0 0 0 0 0 0 0 0; + mso-font-charset:2; + mso-generic-font-family:auto; + mso-font-pitch:variable; + mso-font-signature:0 268435456 0 0 -2147483648 0;} [EMAIL PROTECTED] + {font-family:SimSun; + panose-1:2 1 6 0 3 1 1 1 1 1; + mso-font-alt:\5B8B\4F53; + mso-font-charset:134; + mso-generic-font-family:auto; + mso-font-pitch:variable; + mso-font-signature:3 135135232 16 0 262145 0;} [EMAIL PROTECTED] + {font-family:"[EMAIL PROTECTED]"; + panose-1:2 1 6 0 3 1 1 1 1 1; + mso-font-charset:134; + mso-generic-font-family:auto; + mso-font-pitch:variable; + mso-font-signature:3 135135232 16 0 262145 0;} + /* Style Definitions */ + p.MsoNormal, li.MsoNormal, div.MsoNormal + {mso-style-parent:""; + margin:0in; + margin-bottom:.0001pt; + mso-pagination:widow-orphan; + font-size:12.0pt; + font-family:"Times New Roman"; + mso-fareast-font-family:SimSun;} +h1 + {mso-margin-top-alt:auto; + margin-right:0in; + mso-margin-bottom-alt:auto; + margin-left:0in; + mso-pagination:widow-orphan; + mso-outline-level:1; + font-size:24.0pt; + font-family:"Times New Roman"; + font-weight:bold;} +h2 + {mso-margin-top-alt:auto; + margin-right:0in; + mso-margin-bottom-alt:auto; + margin-left:0in; + mso-pagination:widow-orphan; + mso-outline-level:2; + font-size:18.0pt; + font-family:"Times New Roman"; + font-weight:bold;} +h3 + {mso-margin-top-alt:auto; + margin-right:0in; + mso-margin-bottom-alt:auto; + margin-left:0in; + mso-pagination:widow-orphan; + mso-outline-level:3; + font-size:13.5pt; + font-family:"Times New Roman"; + font-weight:bold;} +p + {mso-margin-top-alt:auto; + margin-right:0in; + mso-margin-bottom-alt:auto; + margin-left:0in; + mso-pagination:widow-orphan; + font-size:12.0pt; + font-family:"Times New Roman"; + mso-fareast-font-family:SimSun;} +span.SpellE + {mso-style-name:""; + mso-spl-e:yes;} +span.GramE + {mso-style-name:""; + mso-gram-e:yes;} [EMAIL PROTECTED] Section1 + {size:8.5in 11.0in; + margin:1.0in 1.25in 1.0in 1.25in; + mso-header-margin:.5in; + mso-footer-margin:.5in; + mso-paper-source:0;} +div.Section1 + {page:Section1;} + /* List Definitions */ + @list l0 + {mso-list-id:1251028; + mso-list-template-ids:27700226;} [EMAIL PROTECTED] l0:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l0:level2 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:1.0in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:"Courier New"; + mso-bidi-font-family:"Times New Roman";} [EMAIL PROTECTED] l1 + {mso-list-id:122038099; + mso-list-template-ids:-1433876078;} [EMAIL PROTECTED] l1:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l2 + {mso-list-id:169027477; + mso-list-template-ids:-1973884710;} [EMAIL PROTECTED] l3 + {mso-list-id:175727143; + mso-list-template-ids:-2134076004;} [EMAIL PROTECTED] l3:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l4 + {mso-list-id:260646577; + mso-list-type:hybrid; + mso-list-template-ids:47117188 67698691 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} [EMAIL PROTECTED] l4:level1 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:1.0in; + mso-level-number-position:left; + margin-left:1.0in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l5 + {mso-list-id:300963081; + mso-list-template-ids:2101672862;} [EMAIL PROTECTED] l5:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:1.5in; + mso-level-number-position:left; + margin-left:1.5in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l5:level2 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:2.0in; + mso-level-number-position:left; + margin-left:2.0in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l5:level3 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:2.5in; + mso-level-number-position:left; + margin-left:2.5in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l5:level4 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:3.0in; + mso-level-number-position:left; + margin-left:3.0in; + text-indent:-.25in; + font-family:Symbol;} [EMAIL PROTECTED] l5:level5 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:3.5in; + mso-level-number-position:left; + margin-left:3.5in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l5:level6 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:4.0in; + mso-level-number-position:left; + margin-left:4.0in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l5:level7 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:4.5in; + mso-level-number-position:left; + margin-left:4.5in; + text-indent:-.25in; + font-family:Symbol;} [EMAIL PROTECTED] l5:level8 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:5.0in; + mso-level-number-position:left; + margin-left:5.0in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l5:level9 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:5.5in; + mso-level-number-position:left; + margin-left:5.5in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l6 + {mso-list-id:303386825; + mso-list-template-ids:47117188;} [EMAIL PROTECTED] l6:level1 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:1.0in; + mso-level-number-position:left; + margin-left:1.0in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l6:level2 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:1.5in; + mso-level-number-position:left; + margin-left:1.5in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l6:level3 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:2.0in; + mso-level-number-position:left; + margin-left:2.0in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l6:level4 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:2.5in; + mso-level-number-position:left; + margin-left:2.5in; + text-indent:-.25in; + font-family:Symbol;} [EMAIL PROTECTED] l6:level5 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:3.0in; + mso-level-number-position:left; + margin-left:3.0in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l6:level6 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:3.5in; + mso-level-number-position:left; + margin-left:3.5in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l6:level7 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:4.0in; + mso-level-number-position:left; + margin-left:4.0in; + text-indent:-.25in; + font-family:Symbol;} [EMAIL PROTECTED] l6:level8 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:4.5in; + mso-level-number-position:left; + margin-left:4.5in; + text-indent:-.25in; + font-family:"Courier New";} [EMAIL PROTECTED] l6:level9 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:5.0in; + mso-level-number-position:left; + margin-left:5.0in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l7 + {mso-list-id:321079697; + mso-list-template-ids:285398786;} [EMAIL PROTECTED] l7:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l8 + {mso-list-id:332493851; + mso-list-template-ids:421552426;} [EMAIL PROTECTED] l8:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l8:level2 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:1.0in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:"Courier New"; + mso-bidi-font-family:"Times New Roman";} [EMAIL PROTECTED] l8:level3 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:1.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Wingdings;} [EMAIL PROTECTED] l8:level4 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:2.0in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Wingdings;} [EMAIL PROTECTED] l9 + {mso-list-id:377556322; + mso-list-template-ids:575036220;} [EMAIL PROTECTED] l9:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l10 + {mso-list-id:439029018; + mso-list-template-ids:-1131543626;} [EMAIL PROTECTED] l10:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l11 + {mso-list-id:461465900; + mso-list-template-ids:658283634;} [EMAIL PROTECTED] l11:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l12 + {mso-list-id:481192588; + mso-list-type:hybrid; + mso-list-template-ids:2101672862 67698693 67698691 67698693 67698689 67698691 67698693 67698689 67698691 67698693;} [EMAIL PROTECTED] l12:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0A7; + mso-level-tab-stop:1.5in; + mso-level-number-position:left; + margin-left:1.5in; + text-indent:-.25in; + font-family:Wingdings;} [EMAIL PROTECTED] l13 + {mso-list-id:691029681; + mso-list-template-ids:1587728578;} [EMAIL PROTECTED] l13:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l14 + {mso-list-id:816066815; + mso-list-template-ids:-1552284938;} [EMAIL PROTECTED] l14:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l14:level2 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:1.0in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:"Courier New"; + mso-bidi-font-family:"Times New Roman";} [EMAIL PROTECTED] l15 + {mso-list-id:869486718; + mso-list-template-ids:2129824680;} [EMAIL PROTECTED] l15:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l16 + {mso-list-id:1290086840; + mso-list-template-ids:1978430556;} [EMAIL PROTECTED] l16:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l17 + {mso-list-id:1347486083; + mso-list-template-ids:1712613156;} [EMAIL PROTECTED] l17:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l18 + {mso-list-id:1476600082; + mso-list-template-ids:-521917396;} [EMAIL PROTECTED] l18:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l19 + {mso-list-id:1806464445; + mso-list-template-ids:1589904280;} [EMAIL PROTECTED] l19:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} [EMAIL PROTECTED] l19:level2 + {mso-level-number-format:bullet; + mso-level-text:o; + mso-level-tab-stop:1.0in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:"Courier New"; + mso-bidi-font-family:"Times New Roman";} [EMAIL PROTECTED] l20 + {mso-list-id:1884713887; + mso-list-template-ids:-176255094;} [EMAIL PROTECTED] l20:level1 + {mso-level-number-format:bullet; + mso-level-text:\F0B7; + mso-level-tab-stop:.5in; + mso-level-number-position:left; + text-indent:-.25in; + mso-ansi-font-size:10.0pt; + font-family:Symbol;} +ol + {margin-bottom:0in;} +ul + {margin-bottom:0in;} +--> +</style> +<!--[if gte mso 10]> +<style> + /* Style Definitions */ + table.MsoNormalTable + {mso-style-name:"Table Normal"; + mso-tstyle-rowband-size:0; + mso-tstyle-colband-size:0; + mso-style-noshow:yes; + mso-style-parent:""; + mso-padding-alt:0in 5.4pt 0in 5.4pt; + mso-para-margin:0in; + mso-para-margin-bottom:.0001pt; + mso-pagination:widow-orphan; + font-size:10.0pt; + font-family:"Times New Roman";} +</style> +<![endif]--> </head> -<body> -<h1><a class="mozTocH1" name="mozTocId934928"></a>Derby Functional Tests<br> -</h1> -<h2><a class="mozTocH2" name="mozTocId504000"></a>Package: -org.apache.derbyTesting<!--mozToc h1 1 h2 2 h3 3 h4 4 h5 5 h6 6--><br> -</h2> -<p> -<small>created by [EMAIL PROTECTED]<br> -last updated on 12/02/2004 by: [EMAIL PROTECTED]<br> -</small> -</p> -<ul> - <li><a href="#intro">1. Introduction</a></li> - <li><a href="#quickstart">2. Quickstart</a></li> - <li style="margin-left: 40px;"><a - href="#2.1_running_with_derby_classes_">2.1 running tests<br> - </a></li> - <li style="margin-left: 40px;"><a - href="#building_derbyTesting__running_with">2.2 building -derbyTesting package</a><br> - </li> - <li><a href="#run">3. More details on running the derby functional -tests</a></li> - <li style="margin-left: 40px;"><a href="#run1">3.1 Running 1 test</a></li> - <li style="margin-left: 40px;"><a href="#run2">3.2 Running suites of -tests</a></li> - <li><a href="#overview">4. Harness internals for developers</a> </li> - <li style="margin-left: 40px;"><a href="#ov1">4.1 Test types</a></li> - <li style="margin-left: 40px;"><a href="#ov2">4.2 Supporting files -for tests</a></li> - <li style="margin-left: 40px;"><a href="#ov3">4.3 -<testname>_app.properties</a></li> - <li style="margin-left: 40px;"><a href="#ov4">4.4 -<testname>_derby.properties</a></li> - <li style="margin-left: 40px;"><a href="#ov5">4.5 tmp files, out -files, master files, and canons</a></li> - <li style="margin-left: 40px;"><a href="#ov6">4.6 Masking and -comparing</a></li> - <li style="margin-left: 40px;"><a href="#Adding_a_new_test">4.7 -Adding a new test</a></li> - <li style="margin-left: 40px;"><a - href="#4.8_Suites_and_Adding_a_new_suite">4.8 Suites and adding a -new suite</a></li> - <li style="margin-left: 40px;"><a href="#ov9">4.9 Running with a new -jvm</a></li> - <li style="margin-left: 40px;"><a href="#skipping">4.10 Skipping a -test</a></li> - <li style="margin-left: 40px;"><a href="#frameworks">4.11 Frameworks</a></li> - <li style="margin-left: 40px;"><a href="#props">4.12 Some test -harness properties</a> </li> + +<body lang=EN-US link=blue vlink=blue style='tab-interval:.5in'> + +<div class=Section1> + +<h1><a name=mozTocId934928></a><st1:City><st1:place>Derby</st1:place></st1:City> +Functional Tests</h1> + +<h2><a name=mozTocId504000></a>Package: <span class=SpellE>org.apache.derbyTesting</span><!--mozToc h1 1 h2 2 h3 3 h4 4 h5 5 h6 6--></h2> + +<p><span class=GramE><span style='font-size:10.0pt'>created</span></span><span +style='font-size:10.0pt'> by [EMAIL PROTECTED]<br> +last updated on </span><st1:date Year="2004" Day="2" Month="12"><span + style='font-size:10.0pt'>12/02/2004</span></st1:date><span style='font-size: +10.0pt'> by: [EMAIL PROTECTED]</span></p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#intro">1. + Introduction</a></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#quickstart">2. <span + class=SpellE>Quickstart</span></a></li> </ul> -<br> -<h2>1. <a name="intro"></a>Introduction</h2> -<p> -This document describes functionality of the derby -functional testing package org.apache.derbyTesting. This package is -based on the functional tests in use at IBM for testing the Cloudscape -product before its contribution to ASF.</p> -<p>In the following, instructions are geared towards a unix -environment. For other environments, some details may need to be -adjusted. For instance, the document may -refer to $ANT_HOME, for DOS, this would be %ANT_HOME%.<br> -</p> -<p>In the following the top -directory under which the subversion tree is placed is referred to as -${derby.source} - see also the -derby <a href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</a>.<br> -</p> -<p>The version of the classes and supporting files of the derbyTesting -package have to match the version of the classes of the derby package. -Thus you either need to build all jars yourself, or get all jar files -from the incubator site at the same time when available. <br> -<br> -</p> -<span style="font-weight: bold;"> -</span> -<h2><a class="mozTocH2" name="mozTocId191589"></a>2. <a - name="quickstart"></a>QuickStart<br> -</h2> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a +href="#2.1_running_with_derby_classes_">2.1 running tests<br> +</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a +href="#building_derbyTesting__running_with">2.2 building <span class=SpellE>derbyTesting</span> +package</a></span></p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#run">3. More + details on running the derby functional tests</a></li> +</ul> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#run1">3.1 Running 1 test</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#run2">3.2 Running suites +of tests</a></span></p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l10 level1 lfo1;tab-stops:list .5in'><a href="#overview">4. + Harness internals for developers</a> </li> +</ul> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#ov1">4.1 Test types</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#ov2">4.2 Supporting +files for tests</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#ov3">4.3 <<span +class=SpellE>testname</span>>_<span class=SpellE>app.properties</span></a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#ov4">4.4 <<span +class=SpellE>testname</span>>_<span class=SpellE>derby.properties</span></a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#ov5">4.5 <span +class=SpellE>tmp</span> files, out files, master files, and canons</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#ov6">4.6 Masking and +comparing</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#Adding_a_new_test">4.7 +Adding a new test</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a +href="#4.8_Suites_and_Adding_a_new_suite">4.8 Suites and adding a new suite</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#ov9">4.9 Running with a +new <span class=SpellE>jvm</span></a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#skipping">4.10 Skipping +a test</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#frameworks">4.11 +Frameworks</a></span></p> + +<p class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; +margin-left:71.1pt;text-indent:-.25in;mso-list:l10 level1 lfo1;tab-stops:list .5in'><![if !supportLists]><span +style='font-size:10.0pt;mso-bidi-font-size:12.0pt;font-family:Symbol; +mso-fareast-font-family:Symbol;mso-bidi-font-family:Symbol'><span +style='mso-list:Ignore'>�<span style='font:7.0pt "Times New Roman"'> +</span></span></span><![endif]><span dir=LTR><a href="#props">4.12 Some test +harness properties</a> </span></p> + +<p class=MsoNormal><o:p> </o:p></p> + +<h2>1. <a name=intro></a>Introduction</h2> + +<p>This document describes functionality of the derby functional testing +package <span class=SpellE>org.apache.derbyTesting</span>. This package is based +on the functional tests in use at IBM for testing the Cloudscape product before +its contribution to ASF.</p> + +<p>In the following, instructions are geared towards a <span class=SpellE><span +class=GramE>unix</span></span> environment. For other environments, some +details may need to be adjusted. For instance, the document may refer to +$ANT_HOME, for DOS, this would be %ANT_HOME%.</p> + +<p>In the following the top directory under which the subversion tree is placed +is referred to as ${<span class=SpellE>derby.source</span>} - see also the +derby <a href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</a>.</p> + +<p style='margin-bottom:12.0pt'>The <span class=GramE>version of the classes +and supporting files of the <span class=SpellE>derbyTesting</span> package have</span> +to match the version of the classes of the derby package. Thus you either need +to build all jars yourself, or get all jar files from the incubator site at the +same time when available. </p> + +<h2><a name=mozTocId191589></a>2. <a name=quickstart></a><span class=SpellE>QuickStart</span></h2> + <h3><a name="2.1_running_with_derby_classes_"></a>2.1 running tests</h3> -<p> -The derbyTesting package enables you to run 1 test or a suite of tests. -Before you can run, you need to setup your environment:<br> -</p> -<ul> - <li>Obtain a jdk or jre (based on jdk 1.3.1 specification or higher). -Add the bin directory to your $PATH. Currently supported are:<br> - </li> + +<p>The <span class=SpellE>derbyTesting</span> package enables you to run 1 test +or a suite of tests. Before you can run, you need to setup your environment:</p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l16 level1 lfo2;tab-stops:list .5in'>Obtain a <span class=SpellE>jdk</span> + or <span class=SpellE>jre</span> (based on <span class=SpellE>jdk</span> + 1.3.1 specification or higher). Add the bin directory to your $PATH. + Currently supported are:</li> </ul> -<table - style="text-align: left; width: 497px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small> jdk131 -- Sun -HotSpot jdk1.3.1</small><br> - <small> jdk141 - Sun HotSpot jdk1.4.1</small><br> - <small> jdk142 - Sun HotSpot jdk1.4.2</small><br> - <small> jdk15 - Sun HotSpot jdk1.5</small><br> - <small> ibm131 - IBM Classic jdk1.3.1</small><br> - <small> ibm141 - IBM Classic jdk1.4.1</small><br> - <small> ibm142 - IBM Classic jdk1.4.2</small><br> - <small> j9_13 - WCTME jvm (available with IBM -Websphere Client Technology Micro Edition) <br> - </small></td> - </tr> - </tbody> + +<table class=MsoNormalTable border=1 cellpadding=0 width=582 style='width:436.4pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'> jdk131 - + Sun <span class=SpellE>HotSpot</span> jdk1.3.1</span><br> + <span style='font-size:10.0pt'> jdk141 - Sun <span + class=SpellE>HotSpot</span> jdk1.4.1</span><br> + <span style='font-size:10.0pt'> jdk142 - Sun <span + class=SpellE>HotSpot</span> jdk1.4.2</span><br> + <span style='font-size:10.0pt'> jdk15 - Sun <span + class=SpellE>HotSpot</span> jdk1.5</span><br> + <span style='font-size:10.0pt'> ibm131 - IBM Classic + jdk1.3.1</span><br> + <span style='font-size:10.0pt'> ibm141 - IBM Classic + jdk1.4.1</span><br> + <span style='font-size:10.0pt'> ibm142 - IBM Classic + jdk1.4.2</span><br> + <span style='font-size:10.0pt'> j9_13 - WCTME <span + class=SpellE>jvm</span> (available with IBM <span class=SpellE>Websphere</span> + Client Technology Micro Edition) </span></p> + </td> + </tr> </table> -<ul> - <li>set $CLASSPATH to include the following jars:</li> - <ul> - <li><small>jakarta-oro-2.0.8.jar</small></li> - <small> oromatcher, obtain from <a - href="http://jakarta.apache.org/oro/index.html";>http://jakarta.apache.org/oro/index.html</a>, + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l14 level1 lfo3;tab-stops:list .5in'>set $CLASSPATH to include + the following jars:</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span + style='font-size:10.0pt'>jakarta-oro-2.0.8.jar</span></li> + </ul> +</ul> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=SpellE><span class=GramE>oromatcher</span></span>, obtain from <a +href="http://jakarta.apache.org/oro/index.html";>http://jakarta.apache.org/oro/index.html</a>, or follow this link for <a - href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro-2.0.8.zip";>zip</a> +href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro-2.0.8.zip";>zip</a> file, or <a - href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro-2.0.8.tar.gz";>tar</a>.gz)</small><li><small>derbyTesting.jar<br> - </small></li> - </ul> - <ul> - <small> test files and classes</small><li><small>derby.jar<br> - </small></li> - <small> main derby package classes</small><li><small>derbytools.jar<br> - </small></li> - <small> derby tools classes for tools like ij -and dblook</small><li><small>derbynet.jar<br> - </small></li> - <small> derby network server classes</small><li><small>db2jcc.jar -and db2jcc_license_c.jar <br> - </small></li> - <small> IBM Universal JDBC Driver classes. (See -IBM <a href="http://www-106.ibm.com/developerworks/db2/downloads/jcc/";>developerworks</a> -for download)</small><br> - <li><small>derbyLocale_*.jar</small></li> - <small> locale files holding translated messages.</small><br> - </ul> +href="http://apache.roweboat.net/jakarta/oro/source/jakarta-oro-2.0.8.tar.gz";><span +class=SpellE>tar</span></a><span class=SpellE>.gz</span>)</span></p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span class=SpellE><span + style='font-size:10.0pt'>derbyTesting.jar</span></span></li> + </ul> </ul> -<small></small> -<ul> - <ul> - </ul> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=GramE>test</span> files and classes</span></p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span class=SpellE><span + style='font-size:10.0pt'>derby.jar</span></span></li> + </ul> </ul> -<p> -For example:<br> -</p> -<div style="margin-left: 40px;"> -<table style="text-align: left; width: 484px; height: 32px;" border="1" - cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small>(note that $jardir is -only a convenience variable and that the command below has carriage -returns for formatting reasons):<br> - </small><small>set jardir=/local/derbyjar<br> -set -CLASSPATH="$jardir/derby.jar:$jardir/derbytools.jar:$jardir/derbynet.jar:$jardir/db2jcc.jar:<br> -$jardir/db2jcc_license_c.jar:$jardir/derbyTesting.jar:/local/derby/tools/java/jakarta-oro-2.0.8.jar:<br> -$jardir/derbyLocale_de_DE.jar:$jardir/derbyLocale_es.jar:$jardir/derbyLocale_fr.jar:<br> -$jardir/derbyLocale_it.jar:$jardir/derbyLocale_ja_JP.jar:$jardir/derbyLocale_ko_KR.jar:<br> -$jardir/derbyLocale_pt_BR.jar:$jardir/derbyLocale_zh_CN.jar:$jardir/derbyLocale_zh_TW.jar:<br> -$CLASSPATH</small><br> - <small>set PATH=/local/jdk141/bin:$PATH</small><br> - </td> - </tr> - </tbody> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=GramE>main</span> derby package classes</span></p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span class=SpellE><span + style='font-size:10.0pt'>derbytools.jar</span></span></li> + </ul> +</ul> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=GramE>derby</span> tools classes for tools like <span class=SpellE>ij</span> +and <span class=SpellE>dblook</span></span></p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span class=SpellE><span + style='font-size:10.0pt'>derbynet.jar</span></span></li> + </ul> +</ul> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=GramE>derby</span> network server classes<o:p></o:p></span></p> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'><o:p> </o:p></span></p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span + style='font-size:10.0pt'>derbyclient.jar </span></li> + </ul> +</ul> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=GramE>derby</span> derby client classes<o:p></o:p></span></p> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'><o:p> </o:p></span></p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span + style='font-size:10.0pt'>db2jcc.jar and db2jcc_license_c.jar </span></li> + </ul> +</ul> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=GramE>IBM Universal JDBC Driver classes.</span> (See IBM <a +href="http://www-106.ibm.com/developerworks/db2/downloads/jcc/";><span +class=SpellE>developerworks</span></a> for download)</span></p> + +<ul type=disc> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l14 level2 lfo3;tab-stops:list 1.0in'><span class=SpellE><span + style='font-size:10.0pt'>derbyLocale</span></span><span style='font-size: + 10.0pt'>_*.jar</span></li> + </ul> +</ul> + +<p class=MsoNormal style='margin-left:1.0in'><span style='font-size:10.0pt'> +<span class=GramE>locale</span> files holding translated messages.</span></p> + +<p>For example:</p> + +<div style='margin-left:35.1pt'> + +<table class=MsoNormalTable border=1 cellpadding=0 width=567 style='width:425.0pt; + mso-cellspacing:1.5pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'>(note that $<span + class=SpellE>jardir</span> is only a convenience variable and that the + command below has carriage returns for formatting reasons):<br> + set <span class=SpellE>jardir</span>=/local/<span class=SpellE>derbyjar</span><br> + set CLASSPATH="$jardir/derby.jar:$jardir/derbytools.jar:$jardir/derbynet.jar:$jardir/derbyclient.jar:$jardir/db2jcc.jar:<br> + $jardir/db2jcc_license_c.jar:$jardir/derbyTesting.jar:/local/derby/tools/java/jakarta-oro-2.0.8.jar:<br> + $jardir/derbyLocale_de_DE.jar:$jardir/derbyLocale_es.jar:$jardir/derbyLocale_fr.jar:<br> + $jardir/derbyLocale_it.jar:$jardir/derbyLocale_ja_JP.jar:$jardir/derbyLocale_ko_KR.jar:<br> + $jardir/derbyLocale_pt_BR.jar:$jardir/derbyLocale_zh_CN.jar:$jardir/derbyLocale_zh_TW.jar:<br> + $CLASSPATH</span><br> + <span style='font-size:10.0pt'>set PATH=/local/jdk141/bin:$PATH</span></p> + </td> + </tr> </table> + </div> -<p> -To run 1 test: -</p> -<table - style="text-align: left; width: 514px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">syntax:<br> - <small>java --D<testproperty> -org.apache.derbyTesting.functionTests.harness.RunTest -<testdir>/<testname></small><br> - <small>where <br> - </small> - <ul> - <li><small> <testproperty> are test specific -properties, such as -'framework' for the RunTest class. </small></li> - <li><small> <testdir> is one of the -directories under -functionTests/tests where the actual test is located</small></li> - <li><small> <testname> is the actual name of -the test</small></li> - </ul> - <small>examples:<br> -to run the test supersimple against the embedded driver:<br> - </small> <small>java -org.apache.derbyTesting.functionTests.harness.RunTest -lang/supersimple.sql<br> - <br> -To run a test with network server, add -Dframework=DerbyNet to the run. -The test harness will to start -network server at port 1527 or connect to a running one, run the test, -and stop network server thereafter.<br> -for example:<br> - java </small><small>-Dframework=DerbyNet - </small><small>org.apache.derbyTesting.functionTests.harness.RunTest -lang/supersimple.sql<br> - </small><small> </small></td> - </tr> - </tbody> + +<p>To run 1 test: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=602 style='width:451.3pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal>syntax:<br> + <span style='font-size:10.0pt'>java -D<<span + class=SpellE>testproperty</span>> <span class=SpellE>org.apache.derbyTesting.functionTests.harness.RunTest</span> + <<span class=SpellE>testdir</span>>/<<span class=SpellE>testname</span>></span><br> + <span style='font-size:10.0pt'>where </span></p> + <ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l9 level1 lfo5;tab-stops:list .5in'><span + style='font-size:10.0pt'> <<span class=SpellE><span + class=GramE>testproperty</span></span>> are test specific properties, + such as 'framework' for the <span class=SpellE>RunTest</span> class. </span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l9 level1 lfo5;tab-stops:list .5in'><span + style='font-size:10.0pt'> <<span class=SpellE>testdir</span>> + is one of the directories under <span class=SpellE>functionTests</span>/tests + where the actual test is located</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l9 level1 lfo5;tab-stops:list .5in'><span + style='font-size:10.0pt'> <<span class=SpellE>testname</span>> + is the actual name of the test</span></li> + </ul> + <p class=MsoNormal><span class=GramE><span style='font-size:10.0pt'>examples</span></span><span + style='font-size:10.0pt'>:<br> + to run the test <span class=SpellE>supersimple</span> against the embedded + driver:<br> + </span> <span style='font-size:10.0pt'>java <span + class=SpellE>org.apache.derbyTesting.functionTests.harness.RunTest</span> <span + class=SpellE>lang/supersimple.sql</span><br> + <br> + To run a test with network server, add -<span class=SpellE>Dframework</span>=<span + class=SpellE>DerbyNet</span> to the run. The test harness will to start + network server at port 1527 or connect to a running one, run the test, and + stop network server thereafter.<br> + for example:<br> + java -<span class=SpellE>Dframework</span>=<span + class=SpellE>DerbyNet</span> <span class=SpellE>org.apache.derbyTesting.functionTests.harness.RunTest</span> + <span class=SpellE>lang/supersimple.sql</span></span></p> + </td> + </tr> </table> -<p> -A successful run will have a .pass file, and the output to the -console will show no difference between expected and actual test -result. A failed test run will have at least a .fail file and the -output to the console will show the difference between expected and -actual result.<br> -</p> -<p> -To run a suite: -</p> -<table - style="text-align: left; width: 546px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">syntax:<br> - <small>java --D<testproperty> -org.apache.derbyTesting.functionTests.harness.RunSuite -<testsuite></small><br> - <small>where <br> - </small> - <ul> - <li><small> <testproperty> are test specific -properties, such as -'verbose' for the RunSuite class. </small></li> - <li><small> <testsuite> is one of the suites -under -org/apache/derbyTesting/suites</small></li> - </ul> - <small>for example for running the suite derbylang:<br> - </small><small> java -Dverbose=true -org.apache.derbyTesting.functionTests.harness.RunSuite derbylang</small><br> - </td> - </tr> - </tbody> + +<p>A successful run will have a .pass file, and the output to the console will +show no difference between expected and actual test result. A failed test run +will have at least a .fail file and the output to the console will show the +difference between expected and actual result.</p> + +<p>To run a suite: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=639 style='width:479.4pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal>syntax:<br> + <span style='font-size:10.0pt'>java -D<<span class=SpellE>testproperty</span>> + <span class=SpellE>org.apache.derbyTesting.functionTests.harness.RunSuite</span> + <<span class=SpellE>testsuite</span>></span><br> + <span style='font-size:10.0pt'>where </span></p> + <ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l15 level1 lfo6;tab-stops:list .5in'><span + style='font-size:10.0pt'> <<span class=SpellE><span + class=GramE>testproperty</span></span>> are test specific properties, + such as 'verbose' for the <span class=SpellE>RunSuite</span> class. </span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l15 level1 lfo6;tab-stops:list .5in'><span + style='font-size:10.0pt'> <<span class=SpellE>testsuite</span>> + is one of the suites under org/apache/<span class=SpellE>derbyTesting</span>/suites</span></li> + </ul> + <p class=MsoNormal><span style='font-size:10.0pt'>for example for + running the suite <span class=SpellE>derbylang</span>:<br> + java -<span class=SpellE>Dverbose</span>=true <span + class=SpellE>org.apache.derbyTesting.functionTests.harness.RunSuite</span> <span + class=SpellE>derbylang</span></span></p> + </td> + </tr> </table> -<p> -Each suite run should be started in a clean directory. The test -output directory will not be emptied out before testing is -begun, although individual test files and result files will be cleaned -out and overwritten. -</p> -<p> -The suites provided are: -</p> -<ul> - <li>derbylang: <br> - </li> - <ul> - <li>basic functionality of -language implementation in derby. <br> - </li> - <li>Mostly .sql type tests. <br> - </li> - <li>tested on a variety of hardware takes from 1.15m to 2.00 hours<br> - </li> + +<p>Each suite run should be started in a clean directory. The test output +directory will not be emptied out before testing is begun, although individual +test files and result files will be cleaned out and overwritten. </p> + +<p>The suites provided are: </p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>derbylang</span>: + </li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>basic</span> + functionality of language implementation in derby. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>Mostly .<span + class=SpellE>sql</span> type tests. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 1.15m to 2.00 hours</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>derbynetclientmats</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>basic</span> + derby network server tests using derby client</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>variety of tests, + including some from <span class=SpellE>derbylang</span> suite</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 15 to 30 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>derbynetmats</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>basic</span> + network server tests using IBM JDBC driver</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>variety of tests, + including some from <span class=SpellE>derbylang</span> suite</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 15 to 30 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>derbynetautostart</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests <span + class=SpellE>networkserver</span> functionality without requiring <span + class=SpellE>networkserver</span> framework</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>propertyinfo</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs test to get + property information</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>storeall</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests for storage area</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>includes:</li> + <ul type=square> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE><span + class=GramE>storemats</span></span>: most basic quick verification + tests.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>storemore</span>: + more extensive storage tests</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>storetests</span>: + set of store tests grouped together because they do not each need to + create a new database</li> </ul> - <li>derbynetmats</li> - <ul> - <li>basic network server tests.</li> - <li>variety of tests, including some from derbylang suite</li> - <li>tested on a variety of hardware takes from 15 to 30 minutes</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 25 to 50 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>xa</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>tests</span> + the <span class=SpellE>xa</span> implementation. There is both a storage + and language element to these tests</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from <st1:time Minute="0" Hour="14">2</st1:time> to 4 + minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>storeunit</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>tests</span> + store-related unit tests. Runs from <st1:time Minute="0" Hour="8">8</st1:time> + to 15 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>unit </li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>tests</span> + 4 general functionality unit tests. runs from <st1:time Minute="0" + Hour="17">5</st1:time> to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>jdbcapi</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>tests</span> + implementation of <span class=SpellE>jdbc</span> <span class=SpellE>api</span> + such as Connection class implementation, Metadata etc.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes from 20 to 40 + minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>jdbc20</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests implementation + of features from the <span class=SpellE>jdbc</span> 20 specification</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 2 to 5 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>jdk14</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests implementation + of features from the jdk14 specification</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 2 to 5 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>demo, <span class=SpellE>simpledemo</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests the <span + class=SpellE>SimpleApp</span> example </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=SpellE><span + class=GramE>simpledemo</span></span> runs <span class=SpellE>SimpleApp</span> + itself - and thus has a different default resource package name (namely, + no package) than all the other tests. Hence it needed its own <span + class=SpellE>suite.properties</span> file.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 30 to 1 minute</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>nist</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>test obtained from the + NIST SQL suite v 6.0</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 5 to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>encryptionAll</span> + </li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 30 to 55 minutes</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs a few encryption + tests plus the following encryption tests suites</li> + <ul type=square> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'>encryption</li> + <ul type=square> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level4 lfo7;tab-stops:list 2.0in'>runs the <span + class=SpellE>storemats</span>, <span class=SpellE>sysinfo</span> and + multi suites in encryption scheme <span class=SpellE>DESede</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level4 lfo7;tab-stops:list 2.0in'>takes 25 to 40 + minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>encryptionAES</span> + - tests AES encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>encryptionBlowfish</span> + - tests Blowfish encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>encryptionCFB</span> + - tests CFB encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>encryptionDES</span> + - tests DES encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>encryptionECB</span> + - tests ECB encryption scheme</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level3 lfo7;tab-stops:list 1.5in'><span class=SpellE>encryptionOFB</span> + - tests OFB encryption scheme</li> </ul> - <li>derbynetautostart</li> - <ul> - <li>tests networkserver functionality without requiring -networkserver framework<br> - </li> - </ul> - <li>propertyinfo</li> - <ul> - <li>runs test to get property information<br> - </li> - </ul> - <li>storeall</li> - <ul> - <li>tests for storage area</li> - <li>includes:</li> - <ul> - <li>storemats: most basic quick verification tests.<br> - </li> - <li>storemore: more extensive storage tests</li> - <li>storetests: set of store tests grouped together because they -do not each need to create a new database</li> - </ul> - <li>tested on a variety of hardware takes from 25 to 50 minutes<br> - </li> - </ul> - <li>xa</li> - <ul> - <li>tests the xa implementation. There is both a storage and -language element to these tests</li> - <li>tested on a variety of hardware takes from 2 to 4 minutes<br> - </li> - </ul> - <li>storeunit</li> - <ul> - <li>tests store-related unit tests. Runs from 8 to 15 minutes<br> - </li> - </ul> - <li>unit <br> - </li> - <ul> - <li>tests 4 general functionality unit tests. runs from 5 to 10 -minutes<br> - </li> - </ul> - <li>jdbcapi</li> - <ul> - <li>tests implementation of jdbc api such as Connection class -implementation, Metadata etc.</li> - <li>takes from 20 to 40 minutes<br> - </li> - </ul> - <li>jdbc20<br> - </li> - <ul> - <li>tests implementation of features from the jdbc 20 specification</li> - <li>takes 2 to 5 minutes<br> - </li> - </ul> - <li>jdk14</li> - <ul> - <li>tests implementation of features from the jdk14 specification</li> - <li>takes 2 to 5 minutes<br> - </li> - </ul> - <li>demo, simpledemo<br> - </li> - <ul> - <li>tests the SimpleApp example <br> - </li> - <li>simpledemo runs SimpleApp itself - and thus has a different -default resource package name (namely, no package) than all the other -tests. Hence it needed its own suite.properties file.</li> - <li>takes 30 to 1 minute</li> - </ul> - <li>nist</li> - <ul> - <li>test obtained from the NIST SQL suite v 6.0</li> - <li>takes 5 to 10 minutes<br> - </li> - </ul> - <li>encryptionAll <br> - </li> - <ul> - <li>takes 30 to 55 minutes</li> - <li>runs a few encryption tests plus the following encryption tests -suites<br> - </li> - </ul> - <ul> - <ul> - <li>encryption</li> - </ul> - <ul> - <ul> - <li>runs the storemats, sysinfo and multi suites in encryption -scheme DESede<br> - </li> - </ul> - <ul> - <li>takes 25 to 40 minutes</li> - </ul> - </ul> - <ul> - <li>encryptionAES - tests AES encryption scheme<br> - </li> - </ul> - <ul> - <li>encryptionBlowfish - tests Blowfish encryption scheme<br> - </li> - </ul> - <ul> - <li>encryptionCFB - tests CFB encryption scheme<br> - </li> - </ul> - <ul> - <li>encryptionDES - tests DES encryption scheme<br> - </li> - </ul> - <ul> - <li>encryptionECB - tests ECB encryption scheme<br> - </li> - </ul> - <ul> - <li>encryptionOFB - tests OFB encryption scheme</li> - </ul> - </ul> - <ul> - </ul> - <li>multi</li> - <ul> - <li>runs a simple test case with 10 threads</li> - <li>runs for 10 minutes, then shuts down all threads<br> - </li> - </ul> - <li>derbytools<br> - </li> - <ul> - <li>tests for dblook, ij, and import/export utilities</li> - <li>takes 5 to 10 minutes<br> - </li> - </ul> - <li>i18nTest</li> - <ul> - <li>tests that characters outside simple ascii scope do not result in errors. - <li>takes 5 to 10 minutes<br> - </li> - </ul> - <li>derbyall</li> - <ul> - <li>contains all suites typically run by all developers<br> - </li> - </ul> - <ul> - <li>tested on a variety of hardware takes from 3.00 - 6.00 hours </li> - </ul> - <li><a href="#Note1:"><small>See Note1</small></a><br> - </li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>multi</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs a simple test + case with 10 threads</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>runs for 10 minutes, + then shuts down all threads</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>derbytools</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tests for <span + class=SpellE>dblook</span>, <span class=SpellE>ij</span>, and + import/export utilities</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 5 to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'>i18nTest</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'><span class=GramE>tests</span> + that characters outside simple <span class=SpellE>ascii</span> scope do + not result in errors. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>takes 5 to 10 minutes</li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><span class=SpellE>derbyall</span></li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>contains all suites + typically run by all developers</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l8 level2 lfo7;tab-stops:list 1.0in'>tested on a variety of + hardware takes from 3.00 - 6.00 hours </li> + </ul> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l8 level1 lfo7;tab-stops:list .5in'><a href="#Note1:"><span + style='font-size:10.0pt'>See Note1</span></a></li> </ul> -<p> -A successful run with all tests passing will have no *.fail files -created, the <testsuite>_fail.txt file will be empty, and the -<testsuite>_report.txt file will show no failures in the Summary -results section. -</p> -<table - style="text-align: left; width: 556px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small>-------snippet from -derbylang_report.txt -----<br> ------------------------------------------------------------<br> -Summary results:<br> - <br> -Test Run Started: 2004-11-10 11:27:55.0<br> -Test Run Duration: 00:04:09<br> - <br> -129 Tests Run<br> -100% Pass (129 tests passed)<br> - 0% Fail (0 tests failed)<br> -0 Suites skipped</small><br> - </td> - </tr> - </tbody> + +<p>A successful run with all tests passing will have no *.fail files created, +the <<span class=SpellE>testsuite</span>>_fail.txt file will be empty, +and the <<span class=SpellE>testsuite</span>>_report.txt file will show +no failures in the Summary results section. </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=651 style='width:488.2pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'>-------snippet from + derbylang_report.txt -----<br> + -----------------------------------------------------------<br> + Summary results:<br> + <br> + Test Run Started: 2004-11-10 11:27:55.0<br> + Test Run Duration: </span><st1:time Minute="4" Hour="0"><span + style='font-size:10.0pt'>00:04:09</span></st1:time><span style='font-size: + 10.0pt'><br> + <br> + 129 Tests Run<br> + 100% Pass (129 tests passed)<br> + 0% Fail (0 tests failed)<br> + 0 Suites skipped</span></p> + </td> + </tr> </table> -<br> -<h3><a name="building_derbyTesting__running_with"></a>2.2 building -derbyTesting package<br> -</h3> -<p> -To build the derbyTesting package:<br> -</p> -<ul> - <li>follow all the steps in the derby <a - href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</a>.</li> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name="building_derbyTesting__running_with"></a>2.2 building <span +class=SpellE>derbyTesting</span> package</h3> + +<p>To build the <span class=SpellE>derbyTesting</span> package:</p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l20 level1 lfo8;tab-stops:list .5in'><span class=GramE>follow</span> + all the steps in the derby <a + href="http://incubator.apache.org/derby/BUILDING.html";>BUILDING.txt</a>.</li> </ul> -<p>This is some typical -output for the ant build process.<br> -</p> -<table - style="text-align: left; width: 516px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small>> cd -/local/derby/java/testing<br> -> ant.ksh<br> -Searching for build.xml ...<br> -Buildfile: /local/derby/java/testing/build.xml<br> - <br> -compile:<br> - [javac] Compiling 30 source files to -/local/derby/classes<br> -...<br> - [copy] Copying 1 file to -/local/derby/classes/org/apache/derbyTesting/funct<br> -ionTests<br> - <br> -BUILD SUCCESSFUL<br> -Total time: 10 minutes 3 seconds</small></td> - </tr> - </tbody> + +<p>This is some typical output for the ant build process.</p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=604 style='width:453.05pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'>> <span class=SpellE>cd</span> + /local/derby/java/testing<br> + > <span class=SpellE>ant.ksh</span><br> + Searching for <span class=SpellE>build.xml</span> ...<br> + <span class=SpellE>Buildfile</span>: /local/derby/java/testing/<span + class=SpellE>build.xml</span><br> + <br> + compile:<br> + [<span class=SpellE>javac</span>] Compiling 30 source + files to /local/derby/classes<br> + ...<br> + [copy] Copying 1 file to + /local/derby/classes/org/apache/<span class=SpellE>derbyTesting/funct</span><br> + <span class=SpellE>ionTests</span><br> + <br> + BUILD SUCCESSFUL<br> + Total time: 10 minutes 3 seconds</span></p> + </td> + </tr> </table> -<p>Once you have built the derbyTesting package built, you can make a -derbyTesting.jar use the jar build target at the ${derby.source}level. + +<p>Once you have built the <span class=SpellE>derbyTesting</span> package +built, you can make a <span class=SpellE>derbyTesting.jar</span> use the jar +build target at the ${<span class=SpellE>derby.source</span><span class=GramE>}level</span>. </p> -<p> -This will look something like: -</p> -<table - style="text-align: left; width: 528px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small>c:> ant derbytestingjar<br> -Searching for build.xml ...<br> -Buildfile: C:\derby\build.xml<br> - <br> -initjars:<br> - [mkdir] Created dir: C:\derby\jars\<br> - [mkdir] Created dir: C:\derby\jars\lists<br> - [echo] Revision number set to exported<br> - [echo] .<br> - <br> -derbytestingjar:<br> - [echo] Beginning derbytesting.jar build<br> -.....<br> -BUILD SUCCESSFULL<br> - </small></td> - </tr> - </tbody> + +<p>This will look something like: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=618 style='width:463.6pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span class=GramE><span style='font-size:10.0pt'>c:</span></span><span + style='font-size:10.0pt'>> ant <span class=SpellE>derbytestingjar</span><br> + Searching for <span class=SpellE>build.xml</span> ...<br> + <span class=SpellE>Buildfile</span>: C:\derby\build.xml<br> + <br> + <span class=SpellE>initjars</span>:<br> + [<span class=SpellE>mkdir</span>] Created dir: + C:\derby\jars\<br> + [<span class=SpellE>mkdir</span>] Created dir: + C:\derby\jars\lists<br> + [echo] Revision number set to exported<br> + [echo] .<br> + <br> + <span class=SpellE><span class=GramE>derbytestingjar</span></span>:<br> + [echo] Beginning <span class=SpellE>derbytesting.jar</span> + build<br> + .....<br> + BUILD SUCCESSFULL</span></p> + </td> + </tr> </table> -<br> -<br> -<h2><a class="mozTocH2" name="mozTocId582299"></a>3. <a name="run"></a>More -details on running the derby functional tests</h2> -<p> -The functional tests are run using a class called 'RunTest'. This class -calls a number of other classes. A group of tests, called a 'suite' is -executed using a class called 'RunSuite'.<br> -</p> -<h3><a class="mozTocH3" name="mozTocId595945"></a>3.1 <a name="run1"></a>Running -1 test</h3> -<p>See section 2.1 for the basic steps to run 1 test. -</p> -<p>To pass on system level properties to the test harness, use the test -harness property -DtestSpecialFlags. For -example, to run a test forcing -the message text to be retrieved from the network server: -</p> -<table - style="text-align: left; width: 558px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"> <small>java --Dframework=DerbyNet --DtestSpecialFlags=RetrieveMessagesFromServerOnGetMessage=true -org.apache.derbyTesting.functionTests.harness.RunTest -lang/supersimple.sql</small></td> - </tr> - </tbody> + +<p class=MsoNormal style='margin-bottom:12.0pt'><o:p> </o:p></p> + +<h2><a name=mozTocId582299></a>3. <a name=run></a>More details on running the +derby functional tests</h2> + +<p>The functional tests are run using a class called '<span class=SpellE>RunTest</span>'. +This class calls a number of other classes. A group of tests, called a 'suite' +is executed using a class called '<span class=SpellE>RunSuite</span>'.</p> + +<h3><a name=mozTocId595945></a>3.1 <a name=run1></a>Running 1 test</h3> + +<p>See section 2.1 for the basic steps to run 1 test. </p> + +<p>To pass on system level properties to the test harness, use the test harness +property -<span class=SpellE>DtestSpecialFlags</span>. For example, to run a +test forcing the message text to be retrieved from the network server: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=653 style='width:489.95pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'>java -<span class=SpellE>Dframework</span>=<span + class=SpellE>DerbyNet</span> -<span class=SpellE>DtestSpecialFlags</span>=<span + class=SpellE>RetrieveMessagesFromServerOnGetMessage</span>=true <span + class=SpellE>org.apache.derbyTesting.functionTests.harness.RunTest</span> <span + class=SpellE>lang/supersimple.sql</span></span></p> + </td> + </tr> </table> + <p><br> -Tests will be executed in the current directory. When -running a test -using the network server, i.e. -Dframework=DerbyNet, the test will run -in a subdirectory (automatically created) 'DerbyNet'. <small> <br> -<a href="#Note2:">See Note2</a>.<br> -</small></p> -<p> -The test will normally create the following:<br> -</p> -<ul> - <li>a database. The default name is 'wombat'. However, the name may -be different depending on certain properties passed in to the test -harness.</li> - <li>a .out file: the final result file</li> - <li>a .tmp file; the initial result file, before any modification to -prevent irrelevant differences has been applied (before 'masking').</li> - <li>a .diff file; the differences between the .out and the master -file with expected output it is compared to.</li> - <li>a .pass or .fail file. This file lists the test if it passes -under .pass, and under .fail if the output in .out is different from -the expected output in the master.</li> +Tests will be executed in the current directory. When running a test using the +network server, i.e. -<span class=SpellE>Dframework</span>=<span class=SpellE>DerbyNet</span>, +the test will run in a subdirectory (automatically created) '<span +class=SpellE>DerbyNet</span>'. <span style='font-size:10.0pt'><br> +<a href="#Note2:">See Note2</a>.</span></p> + +<p>The test will normally create the following:</p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'><span class=GramE>a</span> + database. The default name is 'wombat'. However, the name may be different + depending on certain properties passed in to the test harness.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'>a .out file: the final result + file</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'><span class=GramE>a</span> .<span + class=SpellE>tmp</span> file; the initial result file, before any + modification to prevent irrelevant differences has been applied (before + 'masking').</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'><span class=GramE>a</span> + .diff file; the differences between the .out and the master file with + expected output it is compared to.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l3 level1 lfo9;tab-stops:list .5in'><span class=GramE>a</span> + .pass or .fail file. This file lists the test if it passes under .<span + class=GramE>pass,</span> and under .fail if the output in .out is + different from the expected output in the master.</li> </ul> -<p> -possibly created:<br> -</p> -<ul> - <li>additional files used in a specific test may get copied over to -the test directory. These normally do not get cleaned up.</li> - <li>.tmpstr file is created for network server tests and is a -possibly -massaged copy of the master file the output needs to be compared with.</li> - <li>.err and .out files in network server database files for any -additional error output.</li> + +<p><span class=GramE>possibly</span> created:</p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l1 level1 lfo10;tab-stops:list .5in'><span class=GramE>additional</span> + files used in a specific test may get copied over to the test directory. + These normally do not get cleaned up.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l1 level1 lfo10;tab-stops:list .5in'>.<span class=SpellE>tmpstr</span> + file is created for network server tests and is a possibly massaged copy + of the master file the output needs to be compared with.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l1 level1 lfo10;tab-stops:list .5in'>.err and .out files in + network server database files for any additional error output.</li> </ul> -<p> -When the test is successful, cleanup will occur unless the test harness -property -Dkeepfiles=true is used. Cleanup will attempt to cleanup all -files except for .pass. <small><br> -<a href="#Note3:_">See Note3.</a></small> -</p> -<p> -A successful run (this example is from a dos environment) would -look for instance like: -</p> -<table - style="text-align: left; width: 414px; height: 45px; margin-left: 80px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small>c:> -derbyTesting.functionTests.harness.RunTest lang/supersimple.sql<br> -C:\derby\run2<br> -supersimple<br> --- listing properties --<br> -derby.locks.deadlockTimeout=3<br> -derby.locks.waitTimeout=3<br> -*** Start: supersimple jdk1.4.2_03 2004-11-10 16:51:02 ***<br> -The test should be running...<br> -MasterFileName = master/supersimple.out<br> -*** End: supersimple jdk1.4.2_03 2004-11-10 16:51:25 ***<br> - </small></td> - </tr> - </tbody> + +<p>When the test is successful, cleanup will occur unless the test harness +property -<span class=SpellE>Dkeepfiles</span>=true is used. Cleanup will attempt +to cleanup all files except for .pass. <span style='font-size:10.0pt'><br> +<a href="#Note3:_">See Note3.</a></span> </p> + +<p>A successful run (this example is from a dos environment) would look for +instance like: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=485 style='width:363.5pt; + mso-cellspacing:1.5pt;margin-left:70.25pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span class=GramE><span style='font-size:10.0pt'>c:</span></span><span + style='font-size:10.0pt'>> <span class=SpellE>derbyTesting.functionTests.harness.RunTest</span> + <span class=SpellE>lang/supersimple.sql</span><br> + C:\derby\run2<br> + <span class=SpellE>supersimple</span><br> + -- listing properties --<br> + <span class=SpellE>derby.locks.deadlockTimeout</span>=3<br> + <span class=SpellE>derby.locks.waitTimeout</span>=3<br> + *** Start: <span class=SpellE>supersimple</span> jdk1.4.2_03 2004-11-10 </span><st1:time + Minute="51" Hour="16"><span style='font-size:10.0pt'>16:51:02</span></st1:time><span + style='font-size:10.0pt'> ***<br> + The test should be running...<br> + <span class=SpellE>MasterFileName</span> = master/<span class=SpellE>supersimple.out</span><br> + *** End: <span class=SpellE>supersimple</span> jdk1.4.2_03 + 2004-11-10 </span><st1:time Minute="51" Hour="16"><span style='font-size: + 10.0pt'>16:51:25</span></st1:time><span style='font-size:10.0pt'> ***</span></p> + </td> + </tr> </table> -<br> -<p>A Test Failure shows the diff, creates a .fail file, does not create -a .pass file, and does not cleanup any files upon completion. The -output might look like this:<br> -</p> -<table - style="text-align: left; width: 442px; height: 32px; margin-left: 80px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small> </small><small>c:> -derbyTesting.functionTests.harness.RunTest lang/supersimple.sql<br> -C:\derby\run2</small><small><br> -supersimple<br> --- listing properties --<br> -derby.locks.deadlockTimeout=3<br> -derby.locks.waitTimeout=3<br> -*** Start: supersimple jdk1.4.2_03 2004-11-10 16:54:39 ***<br> -The test should be running...<br> -MasterFileName = master/supersimple.out<br> -10 del<br> -< 10<br> -10a10<br> -> 1<br> -Test Failed.<br> -*** End: supersimple jdk1.4.2_03 2004-11-10 16:55:02 ***</small><br> - </td> - </tr> - </tbody> + +<p class=MsoNormal><o:p> </o:p></p> + +<p>A Test Failure shows the diff, creates a .fail file, does not create a .pass +<span class=GramE>file,</span> and does not cleanup any files upon completion. +The output might look like this:</p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=517 style='width:388.1pt; + mso-cellspacing:1.5pt;margin-left:70.25pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'> <span class=GramE>c:</span>> + <span class=SpellE>derbyTesting.functionTests.harness.RunTest</span> <span + class=SpellE>lang/supersimple.sql</span><br> + C:\derby\run2<br> + <span class=SpellE>supersimple</span><br> + -- listing properties --<br> + <span class=SpellE>derby.locks.deadlockTimeout</span>=3<br> + <span class=SpellE>derby.locks.waitTimeout</span>=3<br> + *** Start: <span class=SpellE>supersimple</span> jdk1.4.2_03 2004-11-10 </span><st1:time + Minute="54" Hour="16"><span style='font-size:10.0pt'>16:54:39</span></st1:time><span + style='font-size:10.0pt'> ***<br> + The test should be running...<br> + <span class=SpellE>MasterFileName</span> = master/<span class=SpellE>supersimple.out</span><br> + 10 </span><st1:State><st1:place><span style='font-size:10.0pt'>del</span></st1:place></st1:State><span + style='font-size:10.0pt'><br> + < 10<br> + 10a10<br> + > 1<br> + Test Failed.<br> + *** End: <span class=SpellE>supersimple</span> jdk1.4.2_03 + 2004-11-10 </span><st1:time Minute="55" Hour="16"><span style='font-size: + 10.0pt'>16:55:02</span></st1:time><span style='font-size:10.0pt'> ***</span></p> + </td> + </tr> </table> -<br> -<h3><a class="mozTocH3" name="mozTocId368566"></a>3.2 <a name="run2"></a>Running -a suite of tests</h3> -<p> -See section 2.1 for a basic explanation on how to run a suite of tests.<br> -</p> -<p> -Tests will be run in a subdirectory with the name of the test -suite under the current directory. Eg. for derbylang suite, a directory -derbylang will be created. While the tests are run, information about -the run is inserted into a <testsuite>.sum file. When all tests -have completed summary files are created <testsuite>_pass.txt, -_fail.txt, and _diff.txt files are created as well as a -<testsuite>_report.txt -with additional details. Some of the information is duplicate. Also, a -.skip file will be created holding a list of the tests that were -skipped (for more details on this, see the section on <a - href="#skipping">skipping tests</a>). -</p> -<p> -RunSuite does not empty the top level directory before running. Thus, -if another suite was run in the same directory at an earlier time, the -resulting summary files might contain results for more than the current -run. Therefore it is important to run each suite in a clean directory. -</p> -<p>Sample output from RunSuite:<br> -</p> -<table - style="text-align: left; width: 471px; height: 32px; margin-left: 80px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small><small>c:> $ java -org.apache.derbyTesting.functionTests.harness.RunSuite derbylang<br> -Top suite: derbylang<br> -Suite to run: derbylang:derbylang<br> -Now do RunList<br> -Now run the suite's tests<br> -Run the tests...<br> -Execute command: java -DjavaCmd=java --Doutputdir=C:\derbyt1\derbylang\derbylang --Dtopsuitedir=C:\derbyt1\derbylang -Dtoprepo<br> -rtdir=C:\derbyt1\derbylang -Drundir=C:\derbyt1 --Dsuitename=derbylang:derbylang -Dtopsuitename=derbylang -org.apache.derbyTesting.functionTests.harness.RunTest -lang/altertable.sql<br> -Execute command: java -DjavaCmd=java --Doutputdir=C:\derbyt1\derbylang\derbylang --Dtopsuitedir=C:\derbyt1\derbylang -Dtopreportdir=C:\derbyt1\derbylang --Drundir=C:\derbyt1 -Dsuitename=derbylang:derbylang --Dtopsuitename=derbylang -org.apache.derbyTesting.functionTests.harness.RunTest -lang/arithmetic.sql<br> -...(.more tests)....<br> -Generated report: derbylang_report.txt</small></small><small><br> - </small></td> - </tr> - </tbody> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name=mozTocId368566></a>3.2 <a name=run2></a>Running a suite of tests</h3> + +<p><span class=GramE>See section 2.1 for a basic explanation on how to run a +suite of tests.</span></p> + +<p>Tests will be run in a subdirectory with the name of the test suite under +the current directory. <span class=SpellE><span class=GramE>Eg</span></span><span +class=GramE>.</span> <span class=GramE>for</span> <span class=SpellE>derbylang</span> +suite, a directory <span class=SpellE>derbylang</span> will be created. While +the tests are run, information about the run is inserted into a <<span +class=SpellE>testsuite</span>>.sum file. When all tests have completed +summary files are created <<span class=SpellE>testsuite</span>>_pass.txt, +_fail.txt, and _diff.txt files are created as well as a <<span class=SpellE>testsuite</span>>_report.txt +with additional details. Some of the information is <span class=GramE>duplicate</span>. +Also, a .skip file will be created holding a list of the tests that were +skipped (for more details on this, see the section on <a href="#skipping">skipping +tests</a>). </p> + +<p><span class=SpellE>RunSuite</span> does not empty the top level directory +before running. Thus, if another suite was run in the same directory at an +earlier time, the resulting summary files might contain results for more than +the current run. Therefore it is important to run each suite in a clean +directory. </p> + +<p>Sample output from <span class=SpellE>RunSuite</span>:</p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=551 style='width:413.55pt; + mso-cellspacing:1.5pt;margin-left:70.25pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span class=GramE><span style='font-size:7.5pt'>c:</span></span><span + style='font-size:7.5pt'>> $ java <span class=SpellE>org.apache.derbyTesting.functionTests.harness.RunSuite</span> + <span class=SpellE>derbylang</span><br> + Top suite: <span class=SpellE>derbylang</span><br> + Suite to run: <span class=SpellE>derbylang:derbylang</span><br> + Now do <span class=SpellE>RunList</span><br> + Now run the suite's tests<br> + Run the tests...<br> + Execute command: java -<span class=SpellE>DjavaCmd</span>=java -<span + class=SpellE>Doutputdir</span>=C:\derbyt1\derbylang\derbylang -<span + class=SpellE>Dtopsuitedir</span>=C:\derbyt1\derbylang -<span class=SpellE>Dtoprepo</span><br> + <span class=SpellE>rtdir</span>=C:\derbyt1\derbylang -<span class=SpellE>Drundir</span>=C:\derbyt1 + -<span class=SpellE>Dsuitename</span>=<span class=SpellE>derbylang:derbylang</span> + -<span class=SpellE>Dtopsuitename</span>=<span class=SpellE>derbylang</span> <span + class=SpellE>org.apache.derbyTesting.functionTests.harness.RunTest</span> <span + class=SpellE>lang/altertable.sql</span><br> + Execute command: java -<span class=SpellE>DjavaCmd</span>=java -<span + class=SpellE>Doutputdir</span>=C:\derbyt1\derbylang\derbylang -<span + class=SpellE>Dtopsuitedir</span>=C:\derbyt1\derbylang -<span class=SpellE>Dtopreportdir</span>=C:\derbyt1\derbylang + -<span class=SpellE>Drundir</span>=C:\derbyt1 -<span class=SpellE>Dsuitename</span>=<span + class=SpellE>derbylang:derbylang</span> -<span class=SpellE>Dtopsuitename</span>=<span + class=SpellE>derbylang</span> <span class=SpellE>org.apache.derbyTesting.functionTests.harness.RunTest</span> + <span class=SpellE>lang/arithmetic.sql</span><br> + ...(.more tests)....<br> + Generated report: derbylang_report.txt</span></p> + </td> + </tr> </table> -<p> -This output does not show whether the tests passed or failed. The -Summary section in <testsuite>_report.txt shows the statistics of -the passed vs. failed tests, the summary <testsuite>_*.txt files -list the tests that passed and failed. -</p> -<br> -<h2><a class="mozTocH2" name="mozTocId635355"></a>4. <a name="overview"></a> -Harness internals for developers<br> -</h2> -<p> -The following is intended for people who have the subversion tree -available and want to add or modify tests. -</p> -<p> -The test harness executing one test basically does the following in -sequence: -</p> -<ul> - <li>identify test to run</li> - <li>identify properties to run with</li> - <li>copy needed support files</li> - <li>find the expected output</li> - <li>if network server, start network server</li> - <li>run the test, creating the database</li> - <li>if network server, shutdown the server</li> - <li>modify the output based on Sed class and _sed.properties file for -the test</li> - <li>compare expected output with actual output</li> - <li>if pass, cleanup.</li> + +<p>This output does not show whether the tests passed or failed. The Summary +section in <<span class=SpellE>testsuite</span>>_report.txt shows the +statistics of the passed vs. failed tests, the summary <<span class=SpellE>testsuite</span>>_*.txt +files list the tests that passed and failed. </p> + +<p class=MsoNormal><o:p> </o:p></p> + +<h2><a name=mozTocId635355></a>4. <a name=overview></a>Harness internals for +developers</h2> + +<p>The following is intended for people who have the subversion tree available +and want to add or modify tests. </p> + +<p>The test harness executing one test basically does the following in +sequence: </p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>identify test to run</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>identify properties to run + with</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>copy needed support files</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>find the expected output</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>if network server, start + network server</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>run the test, creating the + database</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>if network server, shutdown + the server</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>modify the output based on <span + class=SpellE>Sed</span> class and _<span class=SpellE>sed.properties</span> + file for the test</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'>compare expected output + with actual output</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l17 level1 lfo11;tab-stops:list .5in'><span class=GramE>if</span> + pass, cleanup.</li> </ul> -<br> -<h3><a class="mozTocH3" name="mozTocId344499"></a>4.1 <a name="ov1"></a>Test -types</h3> -<p> -The test harness recognizes, or will recognize tests with the following -extensions:<br> -</p> -<ul> - <li> .java tests that run in a separate jvm.</li> - <li> .sql tests that run using ij</li> - <li> .sql2 related to .sql</li> - <li> .multi multi threaded tests. There is -currently only 1 test being run. The multi test functions a little -differently from .java and .sql* tests in that RunTest starts a -separate harness class called MultiTest to control the details of the -run. Also, the actual test files live under -org/apache/derbyTesting/functionTests/multiTests, rather than -org/apache/derbyTesting/functionTests/tests. <br> - </li> - <li> .unit unit tests. The unit tests -actually refer to <testname>_derby.properties files under -org/apache/derbyTesting/functionTests/tests/unit that activate the -actual unit test harness and tests under -org/apache/derbyTesting/unitTests. These tests test more underlying -functionality than the (rest of the) functionTests, which are more -geared toward how end-users might use functionality.<br> - </li> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name=mozTocId344499></a>4.1 <a name=ov1></a>Test types</h3> + +<p>The test harness recognizes, or will recognize tests with the following +extensions:</p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .java + tests that run in a separate <span class=SpellE>jvm</span>.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .<span class=SpellE>sql</span> + tests that run using <span class=SpellE>ij</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .sql2 + related to .<span class=SpellE>sql</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .multi + multi threaded tests. There is currently only 1 test + being run. The multi test functions a little differently from .java and .<span + class=SpellE>sql</span>* tests in that <span class=SpellE>RunTest</span> + starts a separate harness class called <span class=SpellE>MultiTest</span> + to control the details of the run. Also, the actual test files live under + org/apache/<span class=SpellE>derbyTesting/functionTests/multiTests</span>, + rather than org/apache/<span class=SpellE>derbyTesting/functionTests/tests</span>. + </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l11 level1 lfo12;tab-stops:list .5in'> .unit + unit tests. The unit tests actually refer to <<span + class=SpellE>testname</span>>_<span class=SpellE>derby.properties</span> + files under org/apache/<span class=SpellE>derbyTesting/functionTests/tests/unit</span> + that activate the actual unit test harness and tests under org/apache/<span + class=SpellE>derbyTesting/unitTests</span>. These tests test more + underlying functionality than the (rest of the) <span class=SpellE>functionTests</span>, + which are more geared toward how end-users might use functionality.</li> </ul> -<br> -<h3><a class="mozTocH3" name="mozTocId809770"></a>4.2 <a name="ov2"></a>Supporting -files for tests</h3> -<p> -Various additional files may be used by a test, for instance, to create -large data values, to test using of jar files and the like. Any files -that need to be accessed by a particular test that are not accessed -from the classpath need to be listed under supportfiles= in the -<testname>_app.properties file.<br> -Tests can refer to classes without being in the classpath, and sql -tests can use the ij command 'run resource ' to execute additional .sql -files without changes to the _app.properties files. -</p> -<p>For example, in the file -(org/apache/derbyTesting/functionTests/tests/)tools/dblook_test_app.properties:<br> -<small> -supportfiles=tools/dblook_makeDB.sql,tools/dblook_test.jar</small><br> -</p> -<h3><a class="mozTocH3" name="mozTocId427577"></a>4.3 <a name="ov3"></a><testname>_app.properties</h3> -<p> -Every test directory has a default_app.properties. This file is for -system level properties generic to all the tests in that test + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name=mozTocId809770></a>4.2 <a name=ov2></a>Supporting files for tests</h3> + +<p>Various additional files may be used by a test, for instance, to create +large data values, to test using of jar files and the like. Any files that need +to be accessed by a particular test that are not accessed from the <span +class=SpellE>classpath</span> need to be listed under <span class=SpellE>supportfiles</span>= +in the <<span class=SpellE>testname</span>>_<span class=SpellE>app.properties</span> +file.<br> +Tests can refer to classes without being in the <span class=SpellE>classpath</span>, +and <span class=SpellE>sql</span> tests can use the <span class=SpellE>ij</span> +command 'run resource ' to execute additional .<span class=SpellE>sql</span> +files without changes to the _<span class=SpellE>app.properties</span> files. </p> + +<p>For example, in the file (org/apache/<span class=SpellE>derbyTesting/functionTests/tests</span>/<span +class=GramE>)tools</span>/<span class=SpellE>dblook_test_app.properties</span>:<br> +<span style='font-size:10.0pt'> <span class=SpellE>supportfiles</span>=tools/<span +class=SpellE>dblook_makeDB.sql,tools/dblook_test.jar</span></span></p> + +<h3><a name=mozTocId427577></a>4.3 <a name=ov3></a><<span class=SpellE>testname</span>>_<span +class=SpellE>app.properties</span></h3> + +<p>Every test directory has a <span class=SpellE>default_app.properties</span>. +This file is for system level properties generic to all the tests in that test directory. </p> -<p> -If a test requires different system level properties, a test specific -properties file can be created to overwrite the defaults. The test -specific properties file needs to have a name starting with the -test file name, followed with _app.properties</p> -<p>For example, for the test tools/dblook_test.java, there is a -properties file called tools/dblook_test_app.properties<br> -</p> -<h3><a class="mozTocH3" name="mozTocId715566"></a>4.4 <a name="ov4"></a><testname>_derby.properties</h3> -<p> -Every test directory has a default_derby.properties. This file is for -derby specific properties common to all the tests in that test + +<p>If a test requires different system level properties, a test specific +properties file can be created to overwrite the defaults. The test specific +properties file needs to have a name starting with the test file name, followed +with _<span class=SpellE>app.properties</span></p> + +<p>For example, for the test tools/<span class=SpellE>dblook_test.java</span>, +there is a properties file called tools/<span class=SpellE>dblook_test_app.properties</span></p> + +<h3><a name=mozTocId715566></a>4.4 <a name=ov4></a><<span class=SpellE>testname</span>>_<span +class=SpellE>derby.properties</span></h3> + +<p style='margin-bottom:12.0pt'>Every test directory has a <span class=SpellE>default_derby.properties</span>. +This file is for derby specific properties common to all the tests in that test directory.<br> -If a test requires different derby properties, a test specific -properties file can be created to overwrite the defaults. The test -specific properties file needs to have a name starting with the -test file name, followed with _derby.properties<br> -<br> -</p> -<h3><a class="mozTocH3" name="mozTocId874096"></a>4.5 <a name="ov5"></a>tmp +If a test requires different derby properties, a test specific properties file +can be created to overwrite the defaults. The test specific properties file +needs to have a name starting with the test file name, followed with _<span +class=SpellE>derby.properties</span></p> + +<h3><a name=mozTocId874096></a>4.5 <a name=ov5></a><span class=SpellE>tmp</span> files, out files, master files, and canons</h3> -<p> -The test's output will be put into a file testname.tmp. Then the output -is modified if masking is required and the result is put into a .out -file.<br> -The expected output is found by examining the following directories, -based on certain input<br> -</p> -<ul> - <li>functionTests/master/framework/jcc_version/jvmcode</li> - <li>functionTests/master/framework/jcc_version/earlier_jvmcode</li> - <li>functionTests/master/framework/jcc_version</li> - <li>functionTests/master/framework/jvmcode</li> - <li>functionTests/master/framework/earlier_jvmcode</li> - <li>functionTests/master/jvmcode</li> - <li>functionTests/master</li> + +<p>The test's output will be put into a file <span class=SpellE>testname.tmp</span>. +Then the output is modified if masking is required and the result is put into <span +class=GramE>a</span> .out file.<br> +The expected output is found by examining the following directories, based on +certain input</p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'><span class=SpellE>functionTests/master/framework/jcc_version/jvmcode</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'><span class=SpellE>functionTests/master/framework/jcc_version/earlier_jvmcode</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'><span class=SpellE>functionTests/master/framework/jcc_version</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'><span class=SpellE>functionTests/master/framework/jvmcode</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'><span class=SpellE>functionTests/master/framework/earlier_jvmcode</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'><span class=SpellE>functionTests/master/jvmcode</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l13 level1 lfo13;tab-stops:list .5in'><span class=SpellE>functionTests</span>/master</li> </ul> -<p> -For example, if we are running a test and the flag -Dframework=DerbyNet -is used and the jvm we are -using is Sun's jdk 142, and the jcc version is 2.4 (not available at -time of writing) then the search for the master to compare with -starts in the functionTests/derbynet/jcc2.4/jdk14 directory. If a .out -file with the same name as the test is found in that directory, that -master is taken. If there is no such file in that directory, search -continues in the directory functionTests/derbynet/jcc2.4/jdk13 if it -exists.</p> -<p>If there is no file there, nor for any other jcc directory, it will -continue to derbynet/jdk14, and the search is continued for earlier jvm -versions.<br> -If we are not running network server, the DerbyNet and -jcc_version directories are not traversed.<br> -</p> -<p>The version details do not go into the subversion level, i.e. -running -with jdk141 or jdk142 is expected to have the same behavior. -</p> -<p> -This functionality supports dealing with minor differences in behavior -caused by minor differences in behavior in the underlying jvms, jcc -versions, differences between results returned through network server -vs. embedded and minor differences between a debug and non debug (jar) -build. </p> -<p> -However, having a large number of these files means a maintenance -problem. Every time test output changes due to modifications to derby -or to the test, all output files in all directories need to be updated -accordingly. If at all possible, irrelevant differences should be -masked out, or the test should be written so that the output does not -reflect such items. </p> -<p> -Suggestions to minimize canons: -</p> -<ul> - <li>create test specific masking</li> - <li>ensure test data has a specific correct returned order; or an -order by should be added to a query</li> - <li>when writing java tests, ensure only pertinent output is -reflected.</li> + +<p>For example, if we are running a test and the flag -<span class=SpellE>Dframework</span>=<span +class=SpellE>DerbyNet</span> is used and the <span class=SpellE>jvm</span> we +are using is Sun's <span class=SpellE>jdk</span> 142, and the <span +class=SpellE>jcc</span> version is 2.4 (not available at time of writing) then +the search for the master to compare with starts in the +functionTests/derbynet/jcc2.4/jdk14 directory. If <span class=GramE>a</span> +.out file with the same name as the test is found in that directory, that +master is taken. If there is no such file in that directory, search continues +in the directory functionTests/derbynet/jcc2.4/jdk13 if it exists.</p> + +<p>If there is no file there, <span class=GramE>nor</span> for any other <span +class=SpellE>jcc</span> directory, it will continue to derbynet/jdk14, and the +search is continued for earlier <span class=SpellE>jvm</span> versions.<br> +If we are not running network server, the <span class=SpellE>DerbyNet</span> +and <span class=SpellE>jcc_version</span> directories are not traversed.</p> + +<p>The version details do not go into the subversion level, i.e. running with +jdk141 or jdk142 is expected to have the same behavior. </p> + +<p>This functionality supports dealing with minor differences in behavior +caused by minor differences in behavior in the underlying <span class=SpellE>jvms</span>, +<span class=SpellE>jcc</span> versions, differences between results returned +through network server vs. embedded and minor differences between a debug and +non debug (jar) build. </p> + +<p>However, having a large number of these files means a maintenance problem. +Every time test output changes due to modifications to derby or to the test, +all output files in all directories need to be updated accordingly. If at all +possible, irrelevant differences should be masked out, or the test should be +written so that the output does not reflect such items. </p> + +<p>Suggestions to minimize canons: </p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l7 level1 lfo14;tab-stops:list .5in'>create test specific masking</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l7 level1 lfo14;tab-stops:list .5in'>ensure test data has a + specific correct returned order; or an order by should be added to a query</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l7 level1 lfo14;tab-stops:list .5in'><span class=GramE>when</span> + writing java tests, ensure only pertinent output is reflected.</li> </ul> -<br> -<h3><a class="mozTocH3" name="mozTocId68107"></a>4.6 <a name="ov6"></a>Masking -and comparing</h3> -<p> -Tests often fail because of unimportant differences, such as process -ids, statement ids, timestamps. The derby functional test harness -provides for masking of these differences at 2 levels:<br> -</p> -<ol> - <li>overall level. Masking required in all, or many tests can be -achieved using the class Sed in the test harness directory. This class -can either delete a reference present in the .tmp file from the .out -file, or replace it with a generic string. </li> - <li>test specific level. To make masking for only one test, a -(testname)_sed.properties file can be created which allows to either -remove a string from the output or to replace it.</li> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name=mozTocId68107></a>4.6 <a name=ov6></a>Masking and comparing</h3> + +<p>Tests often fail because of unimportant differences, such as process ids, +statement ids, timestamps. The derby functional test harness provides for +masking of these differences at 2 levels:</p> + +<ol start=1 type=1> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l2 level1 lfo15;tab-stops:list .5in'><span class=GramE>overall</span> + level. Masking required in all, or many tests can be achieved using the + class <span class=SpellE>Sed</span> in the test harness directory. This + class can either delete a reference present in the .<span class=SpellE>tmp</span> + file from the .out file, or replace it with a generic string. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l2 level1 lfo15;tab-stops:list .5in'><span class=GramE>test</span> + specific level. To make masking for only one test, a (<span class=SpellE>testname</span><span + class=GramE>)_</span><span class=SpellE>sed.properties</span> file can be + created which allows to either remove a string from the output or to + replace it.</li> </ol> -<p> -The diff is executed between the final resulting output and the master -file found.<br> -<br> -</p> -<h3><a name="Adding_a_new_test"></a>4.7<span style="font-weight: bold;"> -</span>Adding -a new test</h3> -<p> -To add a new test: -</p> -<ul> - <li>create the test file (e.g. newfunctest.java or newfunctest.sql) -in the appropriate tests subdirectory</li> - <li>list any files needed that are not .sql or .java files in a -supportfiles entry in a test specific _app.properties file. e.g. -newfunctest_app.properties: supportfiles=xyz.jar<br> - </li> - <li>list any specific derby properties in a test specific -_derby.properties file.</li> - <li>add the properties files to the copyfiles.ant file in the test -specific directory</li> - <li>run the test. The first time around, the test will fail because -no master file will be found. </li> - <li>if the output is correct, copy it to the master directory. Note -that there is no copyfiles.ant file needed for the master directory, -all .out files are automatically copied.</li> - <li>run the test again. Investigate if any differences need to be -masked out using a test specific sed.properties file (e.g. -newfunctest_sed.properties). If so, ensure this is added to -copyfiles.ant.</li> - <li>add the test to a specific suites/*.xml file, maintaining proper -xml syntax. </li> - <li>run the suite, and correct any problems found.</li> + +<p style='margin-bottom:12.0pt'>The diff is executed between the final +resulting output and the master file found.</p> + +<h3><a name="Adding_a_new_test"></a>4.7<span class=GramE> Adding</span> a +new test</h3> + +<p>To add a new test: </p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>create the test file (e.g. <span + class=SpellE>newfunctest.java</span> or <span class=SpellE>newfunctest.sql</span>) + in the appropriate tests subdirectory</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'><span class=GramE>list</span> + any files needed that are not .<span class=SpellE>sql</span> or .java + files in a <span class=SpellE>supportfiles</span> entry in a test specific + _<span class=SpellE>app.properties</span> file. e.g. <span class=SpellE>newfunctest_app.properties</span>: + <span class=SpellE>supportfiles</span>=<span class=SpellE>xyz.jar</span></li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'><span class=GramE>list</span> + any specific derby properties in a test specific _<span class=SpellE>derby.properties</span> + file.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'>add the properties files to + the <span class=SpellE>copyfiles.ant</span> file in the test specific + directory</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'><span class=GramE>run</span> + the test. The first time around, the test will fail because no master file + will be found. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'><span class=GramE>if</span> + the output is correct, copy it to the master directory. Note that there is + no <span class=SpellE>copyfiles.ant</span> file needed for the master + directory, all .out files are automatically copied.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'><span class=GramE>run</span> + the test again. Investigate if any differences need to be masked out using + a test specific <span class=SpellE>sed.properties</span> file (e.g. <span + class=SpellE>newfunctest_sed.properties</span>). If so, ensure this is + added to <span class=SpellE>copyfiles.ant</span>.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'><span class=GramE>add</span> + the test to a specific suites/*.xml file, maintaining proper xml syntax. </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l18 level1 lfo16;tab-stops:list .5in'><span class=GramE>run</span> + the suite, and correct any problems found.</li> </ul> -<br> -<h3><a name="4.8_Suites_and_Adding_a_new_suite"></a>4.8 Suites and -Adding a new suite</h3> -<p> -A suite constitutes of a <suitename>.properties file and/or a -<suitename>.runall file in the -org/apache/derbyTesting/functionTests/suites directory. The .properties -files hold references to other .properties files, or .runall files, the -.runall files are the actual lists of tests. -</p> -<p> -The lowest level suite always needs to have a .runall file. -</p> -<p> -For example, the derbyall suite is only a derbyall.properties file that -refers to other suites in the 'suites' property: -</p> -<table - style="text-align: left; width: 527px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small>-----------------------derbyall.properties---------------<br> -suites=derbylang derbynetmats storeall xa derbytools<br> -derby.debug.true=enableBtreeConsistencyCheck<br> -derby.stream.error.logSeverityLevel=0<br> - </small></td> - </tr> - </tbody> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name="4.8_Suites_and_Adding_a_new_suite"></a>4.8 Suites and Adding a new +suite</h3> + +<p>A suite constitutes of a <<span class=SpellE>suitename</span>>.properties +file and/or a <<span class=SpellE>suitename</span>>.<span class=SpellE>runall</span> +file in the org/apache/<span class=SpellE>derbyTesting/functionTests/suites</span> +directory. The .properties files hold references to other .properties files, or +.<span class=SpellE>runall</span> files, the .<span class=SpellE>runall</span> +files are the actual lists of tests. </p> + +<p>The lowest level suite always needs to have a .<span class=SpellE>runall</span> +file. </p> + +<p>For example, the <span class=SpellE>derbyall</span> suite is only a <span +class=SpellE>derbyall.properties</span> file that refers to other suites in the +'suites' property: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=617 style='width:462.75pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'>-----------------------<span + class=SpellE>derbyall.properties</span>---------------<br> + suites=<span class=SpellE>derbylang</span> <span class=SpellE>derbynetmats</span> + <span class=SpellE>storeall</span> <span class=SpellE>xa</span> <span + class=SpellE>derbytools</span><br> + <span class=SpellE>derby.debug.true</span>=<span class=SpellE>enableBtreeConsistencyCheck</span><br> + <span class=SpellE>derby.stream.error.logSeverityLevel</span>=0</span></p> + </td> + </tr> </table> -<p> -The derbylang suite is only a derbylang.runall, which lists the tests. -The derbynetmats suite has both a .runall and a .properties file, so -some additional properties can be specified that are true for all tests -in that suite. </p> -<table - style="text-align: left; width: 521px; height: 32px; margin-left: 40px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small>------------------derbynetmats.properties-----------------<br> -framework=DerbyNet<br> -suites=derbynetmats<br> -jdk12test=true<br> -runwithj9=false<br> -timeout=60<br> - </small></td> - </tr> - </tbody> + +<p>The <span class=SpellE>derbylang</span> suite is only a <span class=SpellE>derbylang.runall</span>, +which lists the tests. The <span class=SpellE>derbynetmats</span> suite has +both a .<span class=SpellE>runall</span> and a .properties file, so some +additional properties can be specified that are true for all tests in that +suite. </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=610 style='width:457.45pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'>------------------<span + class=SpellE>derbynetmats.properties</span>-----------------<br> + framework=<span class=SpellE>DerbyNet</span><br> + suites=<span class=SpellE>derbynetmats</span><br> + jdk12test=true<br> + runwithj9=false<br> + timeout=60</span></p> + </td> + </tr> </table> -<p> -To add a suite, you need to create at least a <suite>.runall -file, which lists the actual tests, or a properties file that refers to -other suites that do have a .runall file. The suite should be added -into the directory -${derby.source}/java/testing/org/apache/derbyTesting/functionTests/suites.<br> -<br> -</p> -<h3><a name="4.9_Running_with_a_new_jvm_"></a> <a name="ov9"></a>4.9 -Running -with a new jvm<br> -</h3> -<p>Currently, the supported jvms are: -</p> -<table style="text-align: left; width: 497px; height: 32px;" border="1" - cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;"><small> jdk131 -- Sun -HotSpot jdk1.3.1 - class: jdk13</small><br> - <small> jdk141 - Sun HotSpot jdk1.4.1 - class -jdk14</small><br> - <small> jdk142 - Sun HotSpot jdk1.4.2 - class -jdk14</small><br> - <small> jdk15 - Sun HotSpot jdk1.5 - class jdk15</small><br> - <small> ibm131 - IBM Classic jdk1.3.1 - -class ibm13</small><br> - <small> ibm141 - IBM Classic jdk1.4.1 - class -ibm14</small><br> - <small> ibm142 - IBM Classic jdk1.4.1 - class -ibm14</small><br> - <small> j9_13 - WCTME jvm (available with IBM -Websphere Client Technology Micro Edition) - class j9_13<br> - </small></td> - </tr> - </tbody> + +<p style='margin-bottom:12.0pt'>To add a suite, you need to create at least a +<suite>.<span class=SpellE>runall</span> file, which lists the actual +tests, or a properties file that refers to other suites that do have a .<span +class=SpellE>runall</span> file. The suite should be added into the directory +${<span class=SpellE>derby.source</span>}/java/testing/org/apache/<span +class=SpellE>derbyTesting/functionTests/suites</span>.</p> + +<h3><a name="4.9_Running_with_a_new_jvm_"></a><a name=ov9></a>4.9 Running with +a new <span class=SpellE>jvm</span></h3> + +<p>Currently, the supported <span class=SpellE>jvms</span> are: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=582 style='width:436.4pt; + mso-cellspacing:1.5pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span style='font-size:10.0pt'> jdk131 - + Sun <span class=SpellE>HotSpot</span> jdk1.3.1 - class: jdk13</span><br> + <span style='font-size:10.0pt'> jdk141 - Sun <span + class=SpellE>HotSpot</span> jdk1.4.1 - class jdk14</span><br> + <span style='font-size:10.0pt'> jdk142 - Sun <span + class=SpellE>HotSpot</span> jdk1.4.2 - class jdk14</span><br> + <span style='font-size:10.0pt'> jdk15 - Sun <span + class=SpellE>HotSpot</span> jdk1.5 - class jdk15</span><br> + <span style='font-size:10.0pt'> ibm131 - IBM Classic + jdk1.3.1 - class ibm13</span><br> + <span style='font-size:10.0pt'> ibm141 - IBM Classic + jdk1.4.1 - class ibm14</span><br> + <span style='font-size:10.0pt'> ibm142 - IBM Classic + jdk1.4.1 - class ibm14</span><br> + <span style='font-size:10.0pt'> j9_13 - WCTME <span + class=SpellE>jvm</span> (available with IBM <span class=SpellE>Websphere</span> + Client Technology Micro Edition) - class j9_13</span></p> + </td> + </tr> </table> -<p>The classes above are subclasses of -org.apache.derbyTesting.functionTests.harness.jvm. The name at the -front is just a convention.<br> -</p> -<p>To run a test with a jvm that does not have a matching class under -org.apache.derbyTesting.functionTests.harness, do the following:<br> -</p> -<ul> - <li>just run the tests as if there is a jvm class. The harness will -default to using -the jdk14 class. Unlikely, but possibly there are no differences<br> - </li> - <li>if there are failures showing that cannot be explained any other -way but genuine, acceptable jvm differences, do the following:</li> - <ul> - <li>create a subclass of -org.apache.derbyTesting.functionTests.harness.jvm. In this class, -specify any jvm specific property settings required </li> - <li>compile the new jvm class and run the tests</li> - <li>create a new canon directory for any additional canons that -need to be created.</li> - <li>in rare occasions, other harness changes may be required</li> - <li>for any tests that should not run with this environment, add a -line in the testname_app.properties file indicating this. For instance -to add a line for a jvm called jdk29, it would be like this: -runwithjdk29=false. Note that the versioning does not currently extend -past 2 digits.</li> - <li>Add code in RunTest.java to switch to the new jvm based on -values for system and vendor properties</li> - </ul> + +<p>The classes above are subclasses of <span class=SpellE>org.apache.derbyTesting.functionTests.harness.jvm</span>. +The name at the front is just a convention.</p> + +<p>To run a test with a <span class=SpellE>jvm</span> that does not have a +matching class under <span class=SpellE>org.apache.derbyTesting.functionTests.harness</span>, +do the following:</p> + +<ul type=disc> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l0 level1 lfo17;tab-stops:list .5in'><span class=GramE>just</span> + run the tests as if there is a <span class=SpellE>jvm</span> class. The + harness will default to using the jdk14 class. Unlikely, but possibly + there are no differences</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto; + mso-list:l0 level1 lfo17;tab-stops:list .5in'>if there are failures + showing that cannot be explained any other way but genuine, acceptable <span + class=SpellE>jvm</span> differences, do the following:</li> + <ul type=circle> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'><span class=GramE>create</span> + a subclass of <span class=SpellE>org.apache.derbyTesting.functionTests.harness.jvm</span>. + In this class, specify any <span class=SpellE>jvm</span> specific + property settings required </li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>compile the new <span + class=SpellE>jvm</span> class and run the tests</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'><span class=GramE>create</span> + a new canon directory for any additional canons that need to be created.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>in rare occasions, + other harness changes may be required</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'><span class=GramE>for</span> + any tests that should not run with this environment, add a line in the <span + class=SpellE>testname_app.properties</span> file indicating this. For + instance to add a line for a <span class=SpellE>jvm</span> called jdk29, + it would be like this: runwithjdk29=false. Note that the versioning does + not currently extend past 2 digits.</li> + <li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt: + auto;mso-list:l0 level2 lfo17;tab-stops:list 1.0in'>Add code in <span + class=SpellE>RunTest.java</span> to switch to the new <span class=SpellE>jvm</span> + based on values for system and vendor properties</li> + </ul> </ul> -<br> -<h3><a name="skipping"></a>4.10 Skipping a test</h3> -<p>There are 2 skipping mechanisms in place for different kinds of -skipping of a test.<br> -</p> -<p>Some tests are written to test specific functionality only available -with for instance certain jvms, or, with network server, certain -versions of the IBM Universal Driver. To control this, properties can -be set for each test, for instance, if a test should not be run when -using an ibm jvm, set runwithibmjvm=false. If a test should be run with -Sun Hotspot jvm version 14, then set runwithjdk14=true.<br> -The skip setting does not go into the subversion level, i.e. setting -runwithjdk141=false has no effect, and setting runwithjdk14 affects -runs with jdk141 as well as jdk142.<br> -Other skip reasons are encryption protocols specific to a certain jvm. <br> -</p> -<p>Another skipping mechanism works on entire 'frameworks'. Currently -there are only 3 supported in the harness, embedded, NetworkServer with -the IBM Universal JDBC Driver ('DerbyNet') and NetworkServer with the -not yet available new driver ('DerbyNetClient'). In the suites -directory there are .exclude files for each of the frameworks - if for -some reason an exclude file were not there, you would see a warning -message show up for every test run. In this 'framework'.exclude file -tests can be placed that for some reason need to be excluded from -running with that framework. This mechanism enables adding of suites to -a framework run even if a few of the tests are not appropriate for that -particular framework.</p> -<p>Note that at this time, only skipped suites show up in the .skip -result file. This still needs to be corrected.</p> -<br> -<h3><a name="frameworks"></a>4.11 Frameworks</h3> -<p> -Currently, the only framework used is DerbyNet for network server. <br> -Setting framework property setting will invoke the test harness class -NetServer, which currently has configuration for connecting to DB2 via -jcc (the IBM Universal Driver), and via the older db2 driver. But there -are currently no tests to exercise these settings.<br> -Setting this framework also causes the search for expected output to -include DerbyNet and jcc version specific subdirectories under master.<br> -</p> -<br> -<h3><a name="props"></a>4.12 Some test harness properties</h3> -<p> -For a complete set, refer to comments in RunTest.java, but here are -some valuable test properties which can be passed to the RunTest class: -</p> -<table - style="text-align: left; margin-left: 40px; width: 601px; height: 252px;" - border="1" cellpadding="2" cellspacing="2"> - <tbody> - <tr> - <td style="vertical-align: top;">runwith<jvm><br> - See above -section <a href="#skipping">4.10</a><br> -framework<br> - specifies which framework to run with. For example:<br> - java -Dframework=DerbyNet -org.apache.derbyTesting.functionTests.RunTest <br> -lang/supersimple.sql<br> -verbose<br> - Shows more detailed output. For example:<br> - java -Dverbose=true -org.apache.derbyTesting.functionTests.RunTest lang/arithmetic.sql<br> -keepfiles<br> - Indicates to not clean up any of the files if the test -passed.<br> - java -Dkeepfiles=true -org.apache.derbyTesting.functionTests.RunTest lang/arithmetic.sql<br> -TestSpecialFlags<br> - sets additional properties.<br> - java --D=TestSpecialFlags=derby.infolog.append=true -org.apache.derbyTesting.functionTests.RunTest lang/arithmetic.sql</td> - </tr> - </tbody> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name=skipping></a>4.10 Skipping a test</h3> + +<p>There are 2 skipping mechanisms in place for different kinds of skipping of +a test.</p> + +<p>Some tests are written to test specific functionality only available with +for instance certain <span class=SpellE>jvms</span>, or, with network server, +certain versions of the IBM Universal Driver. To control this, properties can +be set for each test, for instance, if a test should not be run when using an <span +class=SpellE><span class=GramE>ibm</span></span> <span class=SpellE>jvm</span>, +set <span class=SpellE>runwithibmjvm</span>=false. If a test should be run with +Sun Hotspot <span class=SpellE>jvm</span> version 14, then set +runwithjdk14=true.<br> +The skip setting does not go into the subversion level, i.e. setting runwithjdk141=false +has no effect, and setting runwithjdk14 affects runs with jdk141 as well as +jdk142.<br> +Other skip reasons are encryption protocols specific to a certain <span +class=SpellE>jvm</span>. </p> + +<p>Another skipping mechanism works on entire 'frameworks'. Currently there are +only 3 supported in the harness, embedded, <span class=SpellE>NetworkServer</span> +with the IBM Universal JDBC Driver ('<span class=SpellE>DerbyNet</span>') and <span +class=SpellE>NetworkServer</span> with the not yet available new driver ('<span +class=SpellE>DerbyNetClient</span>'). In the suites directory there are +.exclude files for each of the frameworks - if for some reason an exclude file +were not there, you would see a warning message show up for every test run. In +this '<span class=SpellE>framework'.exclude</span> file tests can be placed +that for some reason need to be excluded from running with that framework. This +mechanism enables adding of suites to a framework run even if a few of the +tests are not appropriate for that particular framework.</p> + +<p>Note that at this time, only skipped suites show up in the .skip result +file. This still needs to be corrected.</p> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name=frameworks></a>4.11 Frameworks</h3> + +<p>Currently, there are <span class=GramE>two <span +style='mso-spacerun:yes'>�</span>frameworks</span> <span +style='mso-spacerun:yes'>�</span><span style='mso-spacerun:yes'>�</span>for +network server, which are <span style='mso-spacerun:yes'>�</span><span +class=SpellE>DerbyNet</span> and <span class=SpellE>DerbyNetClient</span>.<br> +Setting framework property setting to <span class=SpellE>DerbyNet</span> <span +style='mso-spacerun:yes'>�</span>will invoke the test harness class <span +class=SpellE>NetServer</span>, which currently has configuration for connecting +to DB2 via <span class=SpellE>jcc</span> (the IBM Universal Driver), and via +the older db2 driver. But there are currently no tests to exercise these +settings.<br> +Setting this framework also causes the search for expected output to include <span +class=SpellE>DerbyNet</span> and <span class=SpellE>jcc</span> version specific +subdirectories under master.</p> + +<p>Setting the framework to <span class=SpellE>DerbyNetClient</span> will +invoke the test harness to use the configuration for the Derby Client.<span +style='mso-spacerun:yes'>� </span>An example is </p> + +<p><span class=GramE>java</span> –<span class=SpellE>Dframework</span>=<span +class=SpellE>DerbyNetClient</span> <span class=SpellE>org.apache.derbyTesting.functionTests.harness.RunSuite</span> +<span class=SpellE>derbynetclientmats</span></p> + +<p class=MsoNormal><o:p> </o:p></p> + +<h3><a name=props></a>4.12 Some test harness properties</h3> + +<p>For a complete set, refer to comments in <span class=SpellE>RunTest.java</span>, +but here are some valuable test properties which can be passed to the <span +class=SpellE>RunTest</span> class: </p> + +<table class=MsoNormalTable border=1 cellpadding=0 width=704 style='width:527.7pt; + mso-cellspacing:1.5pt;margin-left:35.1pt;mso-padding-alt:1.5pt 1.5pt 1.5pt 1.5pt'> + <tr style='mso-yfti-irow:0;mso-yfti-lastrow:yes'> + <td valign=top style='padding:1.5pt 1.5pt 1.5pt 1.5pt'> + <p class=MsoNormal><span class=SpellE><span class=GramE>runwith</span></span><span + class=GramE><</span><span class=SpellE>jvm</span>><br> + See above section <a href="#skipping">4.10</a><br> + framework<br> + specifies which framework to run with. For example:<br> + java -<span class=SpellE>Dframework</span>=<span + class=SpellE>DerbyNet</span> <span class=SpellE>org.apache.derbyTesting.functionTests.RunTest</span> + <br> + <span class=SpellE>lang/supersimple.sql</span><br> + verbose<br> + Shows more detailed output. For example:<br> + java -<span class=SpellE>Dverbose</span>=true + <span class=SpellE>org.apache.derbyTesting.functionTests.RunTest</span> <span + class=SpellE>lang/arithmetic.sql</span><br> + <span class=SpellE>keepfiles</span><br> + Indicates to not clean up any of the files if the test passed.<br> + <span class=GramE>java</span> -<span + class=SpellE>Dkeepfiles</span>=true <span class=SpellE>org.apache.derbyTesting.functionTests.RunTest</span> + <span class=SpellE>lang/arithmetic.sql</span><br> + <span class=SpellE>TestSpecialFlags</span><br> + sets additional properties.<br> + java -D=<span class=SpellE>TestSpecialFlags</span>=<span + class=SpellE>derby.infolog.append</span>=true <span class=SpellE>org.apache.derbyTesting.functionTests.RunTest</span> + <span class=SpellE>lang/arithmetic.sql</span></p> + </td> + </tr> </table> -<br> -<br> -<h3><br> -</h3> -<br> -<br> + +<p class=MsoNormal style='margin-bottom:12.0pt'><o:p> </o:p></p> + +<h3><o:p> </o:p></h3> + +<p class=MsoNormal style='margin-bottom:12.0pt'><o:p> </o:p></p> + <h2>Notes</h2> -<small><a name="Note1:"></a> Note1:<br> -</small> -<div style="margin-left: 40px;"><small>There is one more suite -included: the j9derbynetmats -suite is a modification of the derbynetmats suite. It is available to -test -the network server with the jvm available with IBM's WCTME (Workplace -Client Technology, Micro Edition; formerly WSDD), and will be run at IBM</small><small>. -Note that the setup for running the j9derbynetmats -tests is very specific to the test harness, not even using the WCTME -files in their normal location.</small><small> <br> -The j9derbynetmats suite is included to serve as an -example of splitting the network server process to run with a different -jvm than the test client. The j9derbynetmats suite will run with -another -jvm -as client (as defined in the suite properties), but start up -network server with the 'j9' jvm files (the reference to 'j9' is based -on the executable, j9.exe), based on the property 'serverJvm'. Running -this suite requires providing the property bootcp, -which is interpreted from the test harness class j9_13. See also -section on adding a new <a href="#ov9%22">jvm setup</a>. -<br> -Another suite is derbynetclientmats. This suite is for testing the -networkserver with a yet to be contributed open source client. IBM -staff is working on contributing this. In essence it is the same as the -derbynetmats suite. At this time, it can only be run by the IBM -staff working on this driver.<br> -</small></div> -<br> -<small><a name="Note2:"></a>Note2:<br> -</small> -<div style="margin-left: 40px;"><small>setting -RetrieveMessagesFromServerOnGetMessage to true -for the test harness is purely for -illustration, the test harness actually forces -RetrieveMessagesFromServerOnGetMessage to true for the tests so the -output is always as expected.</small><br> + +<p class=MsoNormal><a name="Note1:"></a><span style='font-size:10.0pt'>Note1:</span></p> + +<div style='margin-left:35.1pt'> + +<p class=MsoNormal><span style='font-size:10.0pt'>There is one more suite +included: the j9derbynetmats suite is a modification of the <span class=SpellE>derbynetmats</span> +suite. It is available to test the network server with the <span class=SpellE>jvm</span> +available with IBM's WCTME (Workplace Client Technology, Micro Edition; +formerly WSDD), and will be run at IBM. Note that the setup for running the j9derbynetmats +tests is very specific to the test harness, not even using the WCTME files in +their normal location. <br> +The j9derbynetmats suite is included to serve as an example of splitting the +network server process to run with a different <span class=SpellE>jvm</span> +than the test client. The j9derbynetmats suite will run with another <span +class=SpellE>jvm</span> as client (as defined in the suite properties), but +start up network server with the 'j9' <span class=SpellE>jvm</span> files (the +reference to 'j9' is based on the executable, j9.exe), based on the property '<span +class=SpellE>serverJvm</span>'. Running this suite requires providing the +property<span class=GramE> <span class=SpellE>bootcp</span></span>, which +is interpreted from the test harness class j9_13. See also section on +adding a new <a href="#ov9%22"><span class=SpellE>jvm</span> setup</a>. <br> + </div> -<br> -<small><a name="Note3:_"></a>Note3: <br> -</small> -<div style="margin-left: 40px;"><small>occasionally, cleanup is -unsuccessful. This does not -constitute a problem in any way, as the harness starts with a clean -database, and clean copies of all files. However, you will see -something like this in the output:</small><br> -<small>Warning: Cleanup failed on baseDir: -/local/myrun1/DerbyNet/supersimple</small><br> + +<p class=MsoNormal><br> +<a name="Note2:"></a><span style='font-size:10.0pt'>Note2:</span></p> + +<div style='margin-left:35.1pt'> + +<p class=MsoNormal><span class=GramE><span style='font-size:10.0pt'>setting</span></span><span +style='font-size:10.0pt'> <span class=SpellE>RetrieveMessagesFromServerOnGetMessage</span> +to true for the test harness is purely for illustration, the test harness +actually forces <span class=SpellE>RetrieveMessagesFromServerOnGetMessage</span> +to true for the tests so the output is always as expected.</span></p> + </div> -<br> + +<p class=MsoNormal><br> +<a name="Note3:_"></a><span style='font-size:10.0pt'>Note3: </span></p> + +<div style='margin-left:35.1pt'> + +<p class=MsoNormal><span class=GramE><span style='font-size:10.0pt'>occasionally</span></span><span +style='font-size:10.0pt'>, cleanup is unsuccessful. This does not constitute a +problem in any way, as the harness starts with a clean database, and clean +copies of all files. However, you will see something like this in the output<span +class=GramE>:</span></span><br> +<span style='font-size:10.0pt'>Warning: Cleanup failed on <span class=SpellE>baseDir</span>: +/local/myrun1/DerbyNet/supersimple</span></p> + +</div> + +<p class=MsoNormal><o:p> </o:p></p> + +</div> + </body> + </html> Index: BUILDING.txt =================================================================== --- BUILDING.txt (revision 161156) +++ BUILDING.txt (working copy) @@ -367,6 +367,7 @@ - derbytools.jar (utilities: sysinfo, dblook, ij) - derbynet.jar (network server). - derbyLocale_*.jar (9 jar files with locale support). + - derbyclient.jar (derby network client) If the tests were built, the following jar file will also be built: - derbyTesting.jar (the test framework and related files) @@ -377,6 +378,7 @@ - command "ant derbynetjar" to build derbynet.jar - command "ant derbylocalejars" to build the derby locale jar files. - command "ant derbytestingjar" to build derbyTesting.jar + - command "ant derbyclientjar" to build derbyclient.jar Notes: (1) The estimated total time for build completion is ~5-10 minutes. Index: build.xml =================================================================== --- build.xml (revision 161156) +++ build.xml (working copy) @@ -21,7 +21,7 @@ <!-- Targets --> - <target name="buildsource" depends="init,engine,tools,drda,build,versioninfo,localeinfo"/> + <target name="buildsource" depends="init,engine,tools,drda,client,build,versioninfo,localeinfo"/> <target name="all" depends="buildsource,demo,testing"/> <!-- ==================================================================== --> @@ -74,6 +74,7 @@ <available file="${out.dir}/org/apache/derby/info/DBMS.properties"/> <available file="${out.dir}/org/apache/derby/info/tools.properties"/> <available file="${out.dir}/org/apache/derby/info/net.properties"/> + <available file="${out.dir}/org/apache/derby/info/dnc.properties"/> </and> </condition> </target> @@ -102,12 +103,20 @@ <param name="info.productfile" value="codeline"/> <param name="info.file" value="${out.dir}/org/apache/derby/info/net.properties"/> </antcall> + <antcall target="infowriter"> + <param name="info.buildnumber" value="1"/> + <param name="info.iname" value="Apache Derby Network Client"/> + <param name="info.ename" value="Apache Derby"/> + <param name="info.productfile" value="codeline"/> + <param name="info.file" value="${out.dir}/org/apache/derby/info/dnc.properties"/> + </antcall> </target> <target name="cleanversion"> <delete file="${out.dir}/org/apache/derby/info/DBMS.properties"/> <delete file="${out.dir}/org/apache/derby/info/tools.properties"/> <delete file="${out.dir}/org/apache/derby/info/net.properties"/> + <delete file="${out.dir}/org/apache/derby/info/dnc.properties"/> </target> <!-- ==================================================================== --> <!-- Info writer build target --> @@ -267,6 +276,10 @@ <ant dir="${derby.drda.src.dir}"/> </target> + <target name="client" depends="engine,init"> + <ant dir="${derby.client.src.dir}"/> + </target> + <target name="build"> <ant dir="${derby.build.src.dir}"/> </target> @@ -493,6 +506,7 @@ <fileset dir="${derby.drda.src.dir}" includesfile="${javadoctools.dir}/publishedapi.ant"/> </copy> + <!-- engine files --> <copy todir="${out.javadoc.dir}/sourcedir"> @@ -634,8 +648,8 @@ <!-- Jar targets --> <!-- =================================================================== --> - <target name="buildjarsclean" depends="cleanjars,initjars,derbyjar,derbytoolsjar,derbynetjar,derbywar,derbylocalejars,derbytestingjar"/> - <target name="buildjars" depends="initjars,derbyjar,derbytoolsjar,derbynetjar,derbywar,derbylocalejars,derbytestingjar"/> + <target name="buildjarsclean" depends="cleanjars,initjars,derbyjar,derbytoolsjar,derbynetjar,derbyclientjar,derbywar,derbylocalejars,derbytestingjar"/> + <target name="buildjars" depends="initjars,derbyjar,derbytoolsjar,derbynetjar,derbyclientjar,derbywar,derbylocalejars,derbytestingjar"/> <target name="initjars" depends="setsanityname,getsvnversion"> <property name="derby.jar.dir" value="${basedir}/jars/${sanity.name}"/> @@ -887,6 +901,45 @@ </target> +<!-- - - - - - - - - - - - - - derbyclient.jar target - - - - - - - - --> + + <target name="derbyclientjar" depends="setsanityname,initjars"> + + <echo message="Beginning derbyclient.jar ${sanity.name} build"/> + + <echo message=" creating new dnc.properties file "/> + + <mkdir dir="${out.dir}/org/apache/derby/info/"/> + <antcall target="infowriter"> + <param name="info.buildnumber" value="${changenumber}"/> + <param name="info.iname" value="Apache Derby Network Client"/> + <param name="info.ename" value="Apache Derby"/> + <param name="info.productfile" value="codeline"/> + <param name="info.file" value="${out.dir}/org/apache/derby/info/dnc.properties"/> + </antcall> + + <!-- copy license file to lists dir for inclusion in derbyclient.jar --> + + <mkdir dir="${derby.jar.dir}/lists/META-INF"/> + <copy todir="${derby.jar.dir}/lists/META-INF"> + <fileset dir="${basedir}" includes="LICENSE*,NOTICE*,COPYRIGHT*"/> + </copy> + + <delete file="${derby.jar.dir}/derbyclient.jar"/> + + <jar destfile="${derby.jar.dir}/derbyclient.jar" + compress="true" + filesonly="true" + update="true"> + <fileset dir="${out.dir}" + includes="org/apache/derby/client/**, + org/apache/derby/client/jdbc/Client**,org/apache/derby/jdbc/Client**,org/apache/derby/iapi/services/info/** + org/apache/derby/info/dnc.properties"/> + <fileset dir="${derby.jar.dir}/lists" + includes="META-INF/**"/> + </jar> + </target> + <!-- - - - - - - - - - - - - - derby.war target - - - - - - - - - - - --> <target name="derbywar" depends="initjars">
