Author: desruisseaux
Date: Fri Feb 22 11:36:11 2013
New Revision: 1448999
URL: http://svn.apache.org/r1448999
Log:
Added documentation about random numbers generator in test cases.
Modified:
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/math/StatisticsTest.java
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/test/TestUtilities.java
Modified:
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/math/StatisticsTest.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/math/StatisticsTest.java?rev=1448999&r1=1448998&r2=1448999&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/math/StatisticsTest.java
(original)
+++
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/math/StatisticsTest.java
Fri Feb 22 11:36:11 2013
@@ -30,6 +30,16 @@ import static org.apache.sis.test.Assert
/**
* Tests {@link Statistics}.
*
+ * <p>This class uses {@link Random} numbers generator with hard-coded seeds.
We do not allow
+ * random seeds because the tests invoke the {@link Random#nextGaussian()}
method, then check
+ * if the statistical values are within some range. Because Gaussian
distributions have non-null
+ * probability to contain arbitrary large values (infinity is the only limit),
testing with random
+ * seeds could produce statistical values out of the expected range no matter
how large is this range.
+ * We could only reduce the probability, but never make it null. This is not a
flaw in the code,
+ * but a consequence of the probabilistic nature of those statistical
distributions.
+ * Consequently, in order to keep the build stable, the random seeds are fixed
to values
+ * that are known to produce results inside the range expected by this test
class.</p>
+ *
* @author Martin Desruisseaux (Geomatys)
* @since 0.3 (derived from geotk-3.00)
* @version 0.3
@@ -63,7 +73,7 @@ public final strictfp class StatisticsTe
*/
@Test
public void testGaussian() {
- final Random random = new Random(317780561);
+ final Random random = new Random(317780561); // See class javadoc.
final Statistics statistics = new Statistics(null);
for (int i=0; i<10000; i++) {
statistics.add(random.nextGaussian());
@@ -182,7 +192,7 @@ public final strictfp class StatisticsTe
*/
@Test
public void testConcatenation() {
- final Random random = new Random(429323868);
+ final Random random = new Random(429323868); // See class javadoc.
final Statistics global = new Statistics(null);
final Statistics byBlock = new Statistics(null);
for (int i=0; i<10; i++) {
Modified:
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/test/TestUtilities.java
URL:
http://svn.apache.org/viewvc/sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/test/TestUtilities.java?rev=1448999&r1=1448998&r2=1448999&view=diff
==============================================================================
---
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/test/TestUtilities.java
(original)
+++
sis/branches/JDK7/sis-utility/src/test/java/org/apache/sis/test/TestUtilities.java
Fri Feb 22 11:36:11 2013
@@ -120,6 +120,20 @@ public final strictfp class TestUtilitie
* Returns a new random number generator with a random seed. This method
logs the seed value
* to the {@link TestCase#out} stream, in order to allow reproducing a
test in case of failure.
*
+ * <p>This method doesn't need to be used in every cases. For example test
cases using
+ * {@link Random#nextGaussian()} should create their own random numbers
generator with
+ * the {@link Random#Random(long)} constructor instead
+ * (see {@link org.apache.sis.math.StatisticsTest} for more explanation).
+ * Or test cases that are mostly insensitive to the exact sequence of
numbers
+ * can use the {@link Random#Random()} constructor instead.</p>
+ *
+ * <p>This method is rather for testing relatively complex code which are
likely to behave
+ * differently depending on the exact sequence of numbers. We want to use
random sequence
+ * of numbers in order to test the code in a wider range of scenarios.
However in case of
+ * test failure, we need to know the <cite>seed</cite> which has been used
in order to allow
+ * the developer to reproduce the test with the exact same sequence of
numbers.
+ * Using this method, the seed can be retrieved in the messages sent to
the output stream.</p>
+ *
* @param testMethod The name of the method which need a random number
generator.
* @return A new random number generator initialized with a random seed.
*/
