[Db-derby Wiki] Update of "DerbyJUnitTesting" by JohnHEmbretsen

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Db-derby Wiki" for change notification.

The following page has been changed by JohnHEmbretsen:
http://wiki.apache.org/db-derby/DerbyJUnitTesting

The comment on the change is:
Some minor improvements

------------------------------------------------------------------------------
  === The suite() method ===
  The `suite()` method is a static method returning the tests to be run. We use it to gain more flexibility in which test methods are executed and the environment they are executed in. For instance, the use of the `suite()` method allows us to use test decorators (the most common case is setting up and populating a common database used by all tests in the suite).
  
- By default, all test methods whose name starts with `test` are added to the suite, typically with `new TestSuite(MyDerbyTests.class, "My suite name")`. If there are tests that should only be run in certain scenarioes, logic for doing this should be placed in `suite()`.
+ By default, all test methods whose name starts with `test` are added to the suite, typically with `new TestSuite(MyDerbyTests.class, "My suite name")`. If there are tests that should only be run in certain scenarios, logic for doing this should be placed in `suite()`.
  
  In general, all tests should be written to be able to run under any framework. Tests that need to be written for a specific framework should be placed in a separate test class and have their `suite()` method return an empty suite when running in a different framework.
  
- A test must be self-contained about which frameworks it can be run in. This avoids the situation with the [:KillDerbyTestHarness:old Derby harness] where discovering if a test is being run in a framework and/or environment is very painful. While JUnit tests continue to be run under the [:KillDerbyTestHarness:old Derby harness] when it is run should be controlled by the mechanisms provided (exclude/skip files etc.) '''when''' no such facility exists in the JUnit environment.
+ A test must be self-contained about which frameworks it can be run in. This avoids the situation with the [:KillDerbyTestHarness:old Derby harness] where discovering if a test is being run in a framework and/or environment is very painful.
  
  Tests that require a minimum level of JDBC support use the `vmSupportsJDBC2`, `vmSupportsJDBC3`, `vmSupportsJDBC4` and/or `vmSupportsJSR169` methods in the `JDBC` class. The style for using these methods should be "postive" and not "negative", e.g. "this test requires JDBC 3", not "this test doesn't run
- on JDBC 2 or JSR 169". This mechanism is to be used instead of any skip facility in the old test harness as it allows the tests to run correctly from standalone JUnit test runners.
+ on JDBC 2 or JSR 169". This mechanism is to be used instead of any skip facility in the [:KillDerbyTestHarness:old test harness] as it allows the tests to run correctly from standalone JUnit test runners.
  
  If a test has no test cases to run in a certain configuration or VM environment then it should just return an empty suite.
  
- See the [http://wiki.apache.org/db-derby/DerbyJunitTestConfiguration test configuration page] for meore details about how to write `suite()` methods
+ See the [http://wiki.apache.org/db-derby/DerbyJunitTestConfiguration test configuration page] for more details about how to write `suite()` methods
  and the definition of primary configurations.
  
  === Package Level _Suite ===
  
- A single suite defined by a class `_Suite` in a package should exist for all the JUnit tests in that package.
+ A single suite defined by a class `_Suite` in a package should exist for all the JUnit test classes in that package.
- That is it has a `suite()` method that returns all the tests in the package by invoking their `suite()` method and adding
- the result to an instance of !TestSuite.
+ The special `_Suite` class has a `suite()` method that returns all the tests in the package by invoking the `suite()` method of each test class and adding the result to an instance of !TestSuite.
+ 
- E.g. for the package `org.apache.derbyTesting.functionTests.tests.jdbcapi` a class `org.apache.derbyTesting.functionTests.tests.jdbcapi._Suite` would exist that runs all the tests in that package.
+ For example, for the package `org.apache.derbyTesting.functionTests.tests.jdbcapi` a class `org.apache.derbyTesting.functionTests.tests.jdbcapi._Suite` would exist that runs all the tests (usually defined in subsuites) in that package.
  
  See DerbyJunitTestConfiguration for details on top level suites.
  
@@ -78, +78 @@

  See DerbyJunitTestConfiguration
  
  === Usage of SQL states in JUnit tests ===
- In your tests, you might want to check for a specific SQL state when an SQLException is thrown. The recommended way to handle this, is to use the `BaseJDBCTestCase.assertSQLState(String,String,SQLException)` and either pass in a constant from `org.apache.derby.functionTesting.util.SQLStateConstants`, or simply hardcode the value or use your own test-local constant. Doing this will assure tests break if someone changes the SQL state for an exception in the internal class, and raises the awareness of SQL state changes in the community.
+ In your tests, you might want to check for a specific SQL state when an SQLException is thrown. The recommended way to handle this, is to use the `BaseJDBCTestCase.assertSQLState(String, String, SQLException)` and either pass in a constant from `org.apache.derby.functionTesting.util.SQLStateConstants`, or simply hardcode the value or use your own test-local constant. Doing this will assure that tests break if someone changes the SQL state for an exception in the internal class, and raises the awareness of SQL state changes in the community.
  
  Please do not reference the internal Derby class that define SQL states. This class is not part of Derby's public interface, and should thus not be used to check for expected SQL states.
  
@@ -90, +90 @@

  
  === Running tests using Junit directly ===
  
- Tests can be run using the Junit 3.8 !TestRunners. The classpath needs to include the junit.jar and the Derby classes.
+ Tests can be run using the Junit 3.8 !TestRunners. The classpath needs to include the junit.jar and the Derby classes (or jars).
  Most of Derby's JUnit test cases and suites run successfully using the !TestRunners directly, as that is the eventual goal.
  
- [http://issues.apache.org/jira/browse/DERBY-1952 DERBY-1952] is opened to start removing JUnit tests from the old harness and
+ [http://issues.apache.org/jira/browse/DERBY-1952 DERBY-1952] was opened to start removing JUnit tests from the old harness and
- instead only support them running directly using JUnit test runners. The top level suite
+ instead only support running them directly using JUnit test runners. The top level suite
  `org.apache.derbyTesting.functionTests.suites.All` successfully runs most of the JUnit tests standalone and those tests are not
  run by the old test harness.
  
- The class name of the test passed to the runners can be an individual test case or one one of the Derby suites, see examples.
+ The class name of the test passed to the runners can be an individual test case or one one of the Derby suites, see examples below.
  
  /!\ Some JUnit tests may require running in the old harness for two reasons:
     * they depend on harness functionality that has not be added to the JUnit utility classes or 
@@ -133, +133 @@

  > java -cp '../../tools/java/junit.jar;../../classes' junit.swingui.TestRunner -noloading
  }}}
  Then supply the complete name of the test class in the top window, e.g. `org.apache.derbyTesting.functionTests.tests.jdbcapi.ProcedureTest`.
- <!> The use of the `-noloading` flag is required, if you recompile Derby or the test classes you must restart the graphical test runners.
+ <!> The use of the `-noloading` flag is required, which means that if you recompile Derby or the test classes you must restart the graphical test runners.
  ==== GUI (awt) run ====
  {{{
  > java -cp '../../tools/java/junit.jar;../../classes' junit.awtui.TestRunner -noloading
  }}}
  Then supply the complete name of the test class in the top window, e.g. `org.apache.derbyTesting.functionTests.tests.jdbcapi.ProcedureTest`.
- <!> The use of the `-noloading` flag is required, if you recompile Derby or the test classes you must restart the graphical test runners.
+ <!> The use of the `-noloading` flag is required, which means that if you recompile Derby or the test classes you must restart the graphical test runners.
  
  === Running tests using ant in a code line ===
  The top-level build.xml file in the trunk codeline contains two targets for running JUnit tests.
  
  || '''Target''' || '''Action''' ||
- || `junit-all` || Run all the JUnit tests. Runs the same set of tests as `suites.All` though it is broken down into per-package `_Suite` runs. May also run additional tests that require special setup or need to run in their own JVM such as the tests for checking the auto-loading of JDBC drivers ||
+ || `junit-all` || Run all the JUnit tests. Runs the same set of tests as `suites.All` though it is broken down into per-package `_Suite` runs (thus the results may be different in some environments, especially when it comes to memory usage). May also run additional tests that require special setup or need to run in their own JVM such as the tests for checking the auto-loading of JDBC drivers ||
  || `junitreport` || Run `junit-all` and produce an HTML report in the output folder ||
  
  The tests are run using the CLASSPATH of the environment which needs to include the Derby code you want to test and junit.jar.
@@ -156, +156 @@

  Note this need not match the virtual machine defined in `JAVA_HOME`. If `jdk16` is not set then the Java SE 6/JDBC 4 tests will not run, '''even''' if `JAVA_HOME` points to a Java SE 6 environment.
  
  The output folder is created in the current directory with the name `junitYYYYMMDD_hhss`, e.g. `junit_20070112_0813`.
- When the report is generated it can viewed using the `index.html` file in the output folder.
+ The generated report can be viewed by opening the `index.html` file (located in the output folder) in a web browser.
  
  === Running tests using Eclipse ===
  
@@ -166, +166 @@

  
  === Running tests using the old Derby harness ===
  
- <!> All except two JUnit tests are now (Jan 2007) setup to run only as pure-JUnit tests, and it is expected that no new tests will be added
+ <!> All except two JUnit tests were as of January 2007 setup to run only as pure-JUnit tests, and it is expected that no new tests will be added
  that require the old harness, thus this section can be safely ignored for the most part. <!>
  
  The [:KillDerbyTestHarness:old Derby harness] supports running JUnit tests directly and from its suite.runall files.